GitHubProjectService#
- class gafaelfawr.services.github_project.GitHubProjectService(*, config, known_scopes, project_store, template_store, history_store, github_storage, token_service, session, logger)#
Bases:
objectManage the registry of GitHub projects.
The registry is the trust configuration of the GitHub Actions token exchange: it says which GitHub workflows may obtain Gafaelfawr tokens, as whom, with which scopes, and for how long. This service enforces the rules of the registry, such as deriving bot usernames, pinning the GitHub IDs of repositories, and refusing projects whose constraints overlap, and records every change in the project history. It also manages project templates, from which a provisioner holding a narrower scope than a token administrator may create projects of a shape an administrator defined.
- Parameters:
config (
GitHubTokenExchangeConfig) – Configuration for the GitHub Actions token exchange.known_scopes (
set[str]) – Scopes known to this Gafaelfawr instance.project_store (
GitHubProjectStore) – Backing store for GitHub projects.template_store (
GitHubProjectTemplateStore) – Backing store for GitHub project templates.history_store (
GitHubProjectHistoryStore) – Backing store for the history of changes to GitHub projects and project templates.github_storage (
GitHubStorage) – Client for looking up repository and owner metadata from GitHub.token_service (
TokenService) – Token manipulation service, used to revoke the tokens of a project.session (
AsyncSession) – Database session.logger (
BoundLogger) – Logger to use.
Methods Summary
create_project(create, auth_data, *, ip_address)Create a new GitHub project.
create_template(create, auth_data, *, ip_address)Create a new GitHub project template.
delete_project(project_id, auth_data, *, ...)Delete a GitHub project and revoke its outstanding tokens.
delete_template(name, auth_data, *, ip_address)Delete a GitHub project template.
get_project(project_id, auth_data)Retrieve a GitHub project.
get_template(name, auth_data)Retrieve a GitHub project template.
list_projects(auth_data, *[, repository, ...])List GitHub projects.
list_templates(auth_data)List GitHub project templates.
provision_project(name, provision, ...)Create a GitHub project from a template.
update_project(project_id, update, ...)Modify a GitHub project.
update_template(name, update, auth_data, *, ...)Modify a GitHub project template.
Methods Documentation
- async create_project(create, auth_data, *, ip_address)#
Create a new GitHub project.
The repository is looked up on GitHub to pin its numeric IDs. If no username was given, one is derived from the repository. If no maximum lifetime was given, the default lifetime is used, capped by the configured maximum lifetime of the token exchange.
- Parameters:
create (
GitHubProjectCreate) – Fields of the new project.auth_data (
TokenData) – The data for the authenticated user making the request.ip_address (
str|None) – The IP address from which the request came, orNonefor internal requests by Gafaelfawr.
- Returns:
The newly-created project.
- Return type:
- Raises:
DuplicateGitHubUsernameError – Raised if the derived username is already used by a project for a different repository.
GitHubError – Raised if GitHub returned invalid repository data.
GitHubProjectOverlapError – Raised if the project is enabled and its constraints overlap those of an existing enabled project for the same repository.
GitHubWebError – Raised if an HTTP error occurred talking to GitHub.
InvalidGitHubUsernameError – Raised if the derived username is not a valid username.
InvalidMaxLifetimeError – Raised if the maximum lifetime is out of range.
InvalidScopesError – Raised if the scopes are unknown or not permitted.
PermissionDeniedError – Raised if the authenticated user is not a token administrator.
UnknownGitHubRepositoryError – Raised if the repository does not exist or is not public.
- async create_template(create, auth_data, *, ip_address)#
Create a new GitHub project template.
Each owner is looked up on GitHub to pin its numeric ID. If no maximum lifetime was given, the default lifetime is used, capped by the configured maximum lifetime of the token exchange.
- Parameters:
create (
GitHubProjectTemplateCreate) – Fields of the new template.auth_data (
TokenData) – The data for the authenticated user making the request.ip_address (
str|None) – The IP address from which the request came, orNonefor internal requests by Gafaelfawr.
- Returns:
The newly-created template.
- Return type:
- Raises:
DuplicateGitHubProjectTemplateError – Raised if a template with the same name already exists.
GitHubError – Raised if GitHub returned invalid owner data.
GitHubWebError – Raised if an HTTP error occurred talking to GitHub.
InvalidMaxLifetimeError – Raised if the maximum lifetime is out of range.
InvalidScopesError – Raised if the scopes are unknown or not permitted.
PermissionDeniedError – Raised if the authenticated user is not a token administrator.
UnknownGitHubOwnerError – Raised if an owner does not exist on GitHub.
- async delete_project(project_id, auth_data, *, ip_address)#
Delete a GitHub project and revoke its outstanding tokens.
- Parameters:
- Raises:
NotFoundError – Raised if no project has that ID.
PermissionDeniedError – Raised if the authenticated user is not a token administrator.
- Return type:
- async delete_template(name, auth_data, *, ip_address)#
Delete a GitHub project template.
A template that any project records as its template cannot be deleted, so that the template a project names always exists. Such a template is retired by disabling it instead.
- Parameters:
- Raises:
GitHubProjectTemplateInUseError – Raised if any project was provisioned from the template.
NotFoundError – Raised if no template has that name.
PermissionDeniedError – Raised if the authenticated user is not a token administrator.
- Return type:
- async get_project(project_id, auth_data)#
Retrieve a GitHub project.
- Parameters:
- Returns:
The project.
- Return type:
- Raises:
NotFoundError – Raised if no project has that ID.
PermissionDeniedError – Raised if the authenticated user is not a token administrator.
- async get_template(name, auth_data)#
Retrieve a GitHub project template.
- Parameters:
- Returns:
The template.
- Return type:
- Raises:
NotFoundError – Raised if no template has that name.
PermissionDeniedError – Raised if the authenticated user is not a token administrator.
- async list_projects(auth_data, *, repository=None, username=None, template=None, requested_by=None)#
List GitHub projects.
- Parameters:
auth_data (
TokenData) – The data for the authenticated user making the request.repository (
str|None, default:None) – Limit the results to projects for this repository, compared case-insensitively.username (
str|None, default:None) – Limit the results to projects for this bot username.template (
str|None, default:None) – Limit the results to projects provisioned from this template.requested_by (
str|None, default:None) – Limit the results to projects requested by this identifier.
- Returns:
Matching projects, ordered by ID.
- Return type:
- Raises:
PermissionDeniedError – Raised if the authenticated user is not a token administrator.
- async list_templates(auth_data)#
List GitHub project templates.
- Parameters:
auth_data (
TokenData) – The data for the authenticated user making the request.- Returns:
All templates, ordered by name.
- Return type:
- Raises:
PermissionDeniedError – Raised if the authenticated user is not a token administrator.
- async provision_project(name, provision, auth_data, *, ip_address)#
Create a GitHub project from a template.
The repository is looked up on GitHub and must belong to one of the owners allowed by the template, by name and by pinned ID, and its name must match the template’s repository pattern if it has one. The project is then created as
create_projectwould create it from a request carrying the template’s fields and the given repository, except that the username is always derived from the repository and the project records the template.Provisioning is idempotent: if a project for the same repository that records the same template already exists, it is returned instead of creating another, since provisioners may retry after a failure. A project for the same repository created directly or from another template conflicts as usual.
- Parameters:
name (
str) – Name of the template.provision (
GitHubProjectProvision) – Repository and descriptive fields of the new project.auth_data (
TokenData) – The data for the authenticated user making the request. Eitheradmin:tokenor the provisioning scope is required.ip_address (
str|None) – The IP address from which the request came, orNonefor internal requests by Gafaelfawr.
- Returns:
The project and
Trueif it was created by this call, or the existing project andFalseif it already existed.- Return type:
- Raises:
DuplicateGitHubUsernameError – Raised if the derived username is already used by a project for a different repository.
GitHubError – Raised if GitHub returned invalid repository data.
GitHubProjectOverlapError – Raised if the constraints of the new project overlap those of an existing enabled project for the same repository.
GitHubProjectTemplateDisabledError – Raised if the template is disabled.
GitHubRepositoryNotAllowedError – Raised if the repository owner is not allowed by the template or the repository name does not match its pattern.
GitHubWebError – Raised if an HTTP error occurred talking to GitHub.
InvalidGitHubUsernameError – Raised if the derived username is not a valid username.
NotFoundError – Raised if no template has that name.
PermissionDeniedError – Raised if the authenticated user has neither
admin:tokennor the provisioning scope.UnknownGitHubRepositoryError – Raised if the repository does not exist or is not public.
- async update_project(project_id, update, auth_data, *, ip_address)#
Modify a GitHub project.
Only the fields set in the update are changed. Changing the repository looks up its numeric IDs again, but keeps the username unless it is also changed, since identity should not move when a label does. Disabling the project revokes its outstanding tokens. Other changes do not affect tokens already minted. An update that changes nothing is not recorded in the project history and leaves the modification time and actor alone.
- Parameters:
- Returns:
The modified project.
- Return type:
- Raises:
DuplicateGitHubUsernameError – Raised if the derived username is already used by a project for a different repository.
GitHubError – Raised if GitHub returned invalid repository data.
GitHubProjectOverlapError – Raised if the project is enabled and its constraints overlap those of another enabled project for the same repository.
GitHubWebError – Raised if an HTTP error occurred talking to GitHub.
InvalidGitHubUsernameError – Raised if the derived username is not a valid username.
InvalidMaxLifetimeError – Raised if the maximum lifetime is out of range.
InvalidScopesError – Raised if the scopes are unknown or not permitted.
NotFoundError – Raised if no project has that ID.
PermissionDeniedError – Raised if the authenticated user is not a token administrator.
UnknownGitHubRepositoryError – Raised if the new repository does not exist or is not public.
- async update_template(name, update, auth_data, *, ip_address)#
Modify a GitHub project template.
Only the fields set in the update are changed. Changing the owners looks up the IDs of owners not already in the list and keeps the pinned IDs of those that remain. Changes affect only projects provisioned afterwards; projects already provisioned from the template are not touched. An update that changes nothing is not recorded in the project history and leaves the modification time and actor alone.
- Parameters:
- Returns:
The modified template.
- Return type:
- Raises:
GitHubError – Raised if GitHub returned invalid owner data.
GitHubWebError – Raised if an HTTP error occurred talking to GitHub.
InvalidMaxLifetimeError – Raised if the maximum lifetime is out of range.
InvalidScopesError – Raised if the scopes are unknown or not permitted.
NotFoundError – Raised if no template has that name.
PermissionDeniedError – Raised if the authenticated user is not a token administrator.
UnknownGitHubOwnerError – Raised if a new owner does not exist on GitHub.