API Reference¶

class cirun.Cirun(token=None)[source]¶

Cirun Client to interact to cirun’s API

add_repo_to_resources(org, repo, resources, teams=None, roles=None, users=None, users_from_json=None, policy_args=None)[source]¶

Creates a Pull request in the <org>/.cirun repository updating the .access.yml to grant access to specified resources for a repository within an organization, with constraints for teams, roles, users, users_from_json, policy_args.

Parameters¶

orgstr: The GitHub organization name.
repostr: The name of the repository to which resources are to be added.
resourceslist of str: A list of resource identifiers to grant access to.
teamslist of str, optional: Teams to grant access to the resources.
roleslist of str, optional: Roles to grant access to the resource, i.e. users with specified roles will have access to the resources.
userslist of str, optional: Users to grant access to the resources.
users_from_jsonstr, optional: Users specified via a JSON URL
policy_argsdict, optional: Additional policy arguments, such as {“pull_request”: True} to enforce specific policies on access.

Returns¶

requests.Response: The response object from the API after attempting to add access.

Raises¶

CirunAPIException: If the API call fails with an error status code.

cloud_connect(name, credentials, print_error=False)[source]¶

Connect a new cloud provider to Cirun.

This method integrates a specified cloud provider with Cirun by providing the necessary credentials. Once connected, the cloud provider can be used to create GitHub Actions runners.

Parameters¶

name: str: Name of cloud provider
credentials: str: Cloud Credentials

Returns¶

dict:: Response json

Raises¶

CirunAPIException: If the API call fails and print_error is False.

clouds(print_error=False)[source]¶

Retrieve all cloud providers connected to Cirun.

This method fetches the list of cloud providers that have been integrated with Cirun (have credentials added to cirun).

Parameters¶

print_errorbool, optional: If set to True, errors encountered during the API call will be printed. Default is False.

Returns¶

dict: A dictionary containing information about connected cloud providers.

Raises¶

CirunAPIException: If the API call fails and print_error is False.

get_repo_resources(org, repo)[source]¶

Retrieve the list of resources that a repository has access to within an organization.

This method parses the access control configuration to determine which resources the specified repository is permitted to access based on its assigned policies.

Parameters¶

orgstr: The GitHub organization name.
repostr: The repository name whose accessible resources are to be retrieved.

Returns¶

list of str or None: A list of resource identifiers that the repository has access to, or None if access control configuration is not found.

Raises¶

KeyError: If the repository does not have an associated policy in the access control configuration.

get_repos(print_error=False)[source]¶: Get all the repositories connected to cirun.

remove_repo_from_resources(org, repo, resources)[source]¶

Creates a Pull request in the <org>/.cirun repository updating the .access.yml to revoke access to specified resources for a repository within an organization.

Parameters¶

org: str: GitHub Organization
repo: str: GitHub Repository
resources: List[str]: List of resources

Returns¶

requests.Response

set_repo(name, active=True, print_error=False, installation_id=None)[source]¶

Activate or deactivate a repository for Cirun.

This method allows you to enable or disable a repository’s integration with Cirun. When activating a repository, it can also handle the installation of the Cirun GitHub App if an installation_id is provided and GITHUB_TOKEN environment variable is set.

Parameters¶

name: str: Repository name
active: bool: True to activate, False otherwise. Default is True
installation_id: int: Cirun App’s Installation ID for the Organization

Returns¶

dict