`github_repo`¶

Manage a single GitHub repository within an organization or user account: the repository itself, its rulesets, deploy keys, Actions secrets and settings, environments, labels and Pages.

Added in version 1.1.0.

All states default repo_name to the value configured in the profile. For the states managing per-repository singletons (present, absent, pages_present, …), name doubles as the repository name instead.

All states accept an owner argument (defaulting to the profile’s owner) to manage repositories of other owners, including user-owned ones. The teams parameter of present only applies to organization-owned repositories (teams belong to the owning organization), and repository creation is only supported for organizations and the authenticated user, a GitHub API limitation.

saltext.github.states.github_repo.present(name, description=None, homepage=None, private=None, has_issues=None, has_wiki=None, has_downloads=None, auto_init=False, gitignore_template=None, license_template=None, default_branch=None, teams=None, owner=None, profile='github')[source]¶

Ensure a repository is present and configured as specified. Unspecified settings are left unmanaged.

name: Name of the repository.
description: Repository description.
homepage: URL with more information about the repository, e.g. rendered docs.
private: Repository visibility. Changing this on an existing repository requires allow_repo_privacy_changes to be enabled in the profile.
has_issues: Enable issues for this repository.
has_wiki: Enable the wiki for this repository.
has_downloads: Enable downloads for this repository.
auto_init: Create an initial commit with an empty README when creating the repository.
gitignore_template: Desired language or platform for a .gitignore, e.g. “Haskell”. Only applies when creating the repository.
license_template: Desired LICENSE template to apply, e.g. “mit” or “mozilla”. Only applies when creating the repository.
default_branch: Default branch of the repository. The branch must already exist, so this is not applied when the repository is newly created.
teams: Teams this repo should belong to, specified as a dict of team name to permission (pull, push or admin). Unlisted teams are removed from the repository. The teams belong to the repository’s owning organization, so this is only supported for organization-owned repositories.
owner: Owner of the repository. Defaults to the profile’s owner. Repository creation is only supported for organizations and the authenticated user.
profile: Profile configuration name to use. Defaults to github.

saltext.github.states.github_repo.absent(name, owner=None, profile='github')[source]¶

Ensure a repository is absent.

name: Name of the repository.
owner: Owner of the repository. Defaults to the profile’s owner.
profile: Profile configuration name to use. Defaults to github.

saltext.github.states.github_repo.ruleset_present(name, ruleset_params=None, repo_name=None, owner=None, profile='github')[source]¶

Ensure a repository ruleset is present and configured as specified. Only the parameters included in ruleset_params are compared, server-populated fields are ignored.

Example:

Ensure ruleset test is present in my-repo:
  github_repo.ruleset_present:
    - name: test
    - repo_name: my-repo
    - ruleset_params:
        target: branch
        enforcement: active

name: Ruleset name to manage.
ruleset_params: Ruleset definition. Must contain at least enforcement when the ruleset needs to be created. name is pulled from this state’s name.
repo_name: Name of the repository. Defaults to the profile’s repo_name.
owner: Owner of the repository. Defaults to the profile’s owner.
profile: Profile configuration name to use. Defaults to github.

saltext.github.states.github_repo.ruleset_absent(name, repo_name=None, owner=None, profile='github')[source]¶

Ensure a repository ruleset is absent.

name: Ruleset name to manage.
repo_name: Name of the repository. Defaults to the profile’s repo_name.
owner: Owner of the repository. Defaults to the profile’s owner.
profile: Profile configuration name to use. Defaults to github.

saltext.github.states.github_repo.deploy_key_present(name, key, read_only=False, repo_name=None, owner=None, profile='github')[source]¶

Ensure a deploy key with this title and public key is present in a repository.

Since deploy keys are immutable in the GitHub API, a key whose key or read_only setting differs is replaced (removed and recreated).

Example:

Autorelease deploy key is present:
  github_repo.deploy_key_present:
    - name: autorelease
    - key: ssh-ed25519 AAAA...
    - repo_name: my-repo

name: Display title of the deploy key.
key: SSH public key.
read_only: Deny write access to the repository for this key. Defaults to false.
repo_name: Name of the repository. Defaults to the profile’s repo_name.
owner: Owner of the repository. Defaults to the profile’s owner.
profile: Profile configuration name to use. Defaults to github.

saltext.github.states.github_repo.deploy_key_absent(name, repo_name=None, owner=None, profile='github')[source]¶

Ensure no deploy key with this title is present in a repository.

name: Display title of the deploy key.
repo_name: Name of the repository. Defaults to the profile’s repo_name.
owner: Owner of the repository. Defaults to the profile’s owner.
profile: Profile configuration name to use. Defaults to github.

saltext.github.states.github_repo.deploy_key_actions_present(name, secret_name, read_only=False, rotate=False, repo_name=None, owner=None, profile='github')[source]¶

Ensure a generated SSH keypair is distributed to a repository: the public half as a deploy key with this title, the private half as an Actions secret. The ed25519 keypair is generated in memory via ssh_pki.create_private_key (requires Salt 3008+) and never persisted; only the public key’s fingerprint is reported.

Since secret values are write-only in the GitHub API, an existing pair cannot be verified to match and is left untouched unless rotate is set. A pair with a missing half is regenerated.

name: Display title of the deploy key.
secret_name: Name of the Actions secret holding the private key. GitHub treats secret names case-insensitively.
read_only: Deny write access to the repository for this key. Defaults to false.
rotate: Generate and distribute a new keypair even when both halves are present. Defaults to false.
repo_name: Name of the repository. Defaults to the profile’s repo_name.
owner: Owner of the repository. Defaults to the profile’s owner.
profile: Profile configuration name to use. Defaults to github.

saltext.github.states.github_repo.actions_secret_present(name, value=None, force=False, repo_name=None, owner=None, profile='github')[source]¶

Ensure an Actions secret is present in a repository.

Secret values are write-only in the GitHub API, so this state cannot detect value drift. By default, an existing secret is left untouched. Set force to push the value on every run.

name: Name of the secret. GitHub treats secret names case-insensitively.
value: Plaintext secret value. It is encrypted to the repository public key before leaving the minion and never appears in the state output. Required when the secret does not exist yet or force is set.
force: Push the value even when the secret already exists. Defaults to false.
repo_name: Name of the repository. Defaults to the profile’s repo_name.
owner: Owner of the repository. Defaults to the profile’s owner.
profile: Profile configuration name to use. Defaults to github.

saltext.github.states.github_repo.actions_secret_absent(name, repo_name=None, owner=None, profile='github')[source]¶

Ensure an Actions secret is absent from a repository.

name: Name of the secret. GitHub treats secret names case-insensitively.
repo_name: Name of the repository. Defaults to the profile’s repo_name.
owner: Owner of the repository. Defaults to the profile’s owner.
profile: Profile configuration name to use. Defaults to github.

saltext.github.states.github_repo.workflow_permissions_managed(name, default_workflow_permissions=None, can_approve_pull_request_reviews=None, repo_name=None, owner=None, profile='github')[source]¶

Manage the default workflow permissions granted to the GITHUB_TOKEN in a repository.

name: Name of the repository, unless repo_name is passed.
default_workflow_permissions: Default permissions for the GITHUB_TOKEN, either read or write.
can_approve_pull_request_reviews: Allow GitHub Actions to approve pull requests.
repo_name: Name of the repository, if it differs from name.
owner: Owner of the repository. Defaults to the profile’s owner.
profile: Profile configuration name to use. Defaults to github.

saltext.github.states.github_repo.environment_present(name, wait_timer=None, prevent_self_review=None, reviewers=None, deployment_branches=None, repo_name=None, owner=None, profile='github')[source]¶

Ensure an environment is present in a repository and configured as specified. Unspecified settings are left unmanaged.

name: Name of the environment.
wait_timer: Amount of time to delay a job after it is initially triggered, in minutes.
prevent_self_review: Prevent a user who created a job from approving it.
reviewers: People or teams that may review jobs that reference the environment, as a list of mappings with type (User or Team) and id.
deployment_branches: Which branches can deploy to this environment. Either all, protected (branches with branch protection rules) or a list of branch name patterns.
repo_name: Name of the repository. Defaults to the profile’s repo_name.
owner: Owner of the repository. Defaults to the profile’s owner.
profile: Profile configuration name to use. Defaults to github.

saltext.github.states.github_repo.environment_absent(name, repo_name=None, owner=None, profile='github')[source]¶

Ensure an environment is absent from a repository.

name: Name of the environment.
repo_name: Name of the repository. Defaults to the profile’s repo_name.
owner: Owner of the repository. Defaults to the profile’s owner.
profile: Profile configuration name to use. Defaults to github.

saltext.github.states.github_repo.label_present(name, color=None, description=None, repo_name=None, owner=None, profile='github')[source]¶

Ensure a label is present in a repository and configured as specified. Unspecified settings are left unmanaged.

name: Name of the label.
color: Hexadecimal color code for the label. A leading # is accepted.
description: Short description of the label.
repo_name: Name of the repository. Defaults to the profile’s repo_name.
owner: Owner of the repository. Defaults to the profile’s owner.
profile: Profile configuration name to use. Defaults to github.

saltext.github.states.github_repo.label_absent(name, repo_name=None, owner=None, profile='github')[source]¶

Ensure a label is absent from a repository.

name: Name of the label.
repo_name: Name of the repository. Defaults to the profile’s repo_name.
owner: Owner of the repository. Defaults to the profile’s owner.
profile: Profile configuration name to use. Defaults to github.

saltext.github.states.github_repo.pages_present(name, build_type=None, source_branch=None, source_path=None, cname=None, https_enforced=None, repo_name=None, owner=None, profile='github')[source]¶

Ensure GitHub Pages are enabled for a repository and configured as specified. Unspecified settings are left unmanaged.

name: Name of the repository, unless repo_name is passed.
build_type: Process by which the site is built, either legacy (deploy from a branch) or workflow (GitHub Actions).
source_branch: For legacy builds, the repository branch to publish from.
source_path: For legacy builds, the repository directory to publish from, either / or /docs.
cname: Custom domain for the site.
https_enforced: Enforce HTTPS for the site.
repo_name: Name of the repository, if it differs from name.
owner: Owner of the repository. Defaults to the profile’s owner.
profile: Profile configuration name to use. Defaults to github.

saltext.github.states.github_repo.pages_absent(name, repo_name=None, owner=None, profile='github')[source]¶

Ensure GitHub Pages are disabled for a repository.

name: Name of the repository, unless repo_name is passed.
repo_name: Name of the repository, if it differs from name.
owner: Owner of the repository. Defaults to the profile’s owner.
profile: Profile configuration name to use. Defaults to github.

github_repo¶

`github_repo`¶