saltext.github 1.1.0__py3-none-any.whl

saltext/github/resources/github/states/actions.py

@@ -0,0 +1,117 @@
+"""
+Manage the targeted repository's Actions secrets and workflow
+permissions.
+
+.. versionadded:: 1.1.0
+
+Part of the :py:mod:`github <saltext.github.resources.github>` resource type: states operate on the repository
+the state run was dispatched to, so there is no ``repo_name``/``owner``
+parameter. The ``profile`` parameter defaults to the :ghconf:`profile <resource:profile>` named in
+the resource declaration.
+"""
+
+import logging
+
+from salt.utils.functools import namespaced_function
+
+from saltext.github.utils.gh import resource as gh_resource
+from saltext.github.utils.gh.statecores import actions as sc_actions
+from saltext.github.utils.gh.statecores import catch_errors
+
+log = logging.getLogger(__name__)
+
+
+_core_args = namespaced_function(gh_resource.core_args, globals())
+
+
+@catch_errors
+def secret_present(name, value=None, force=False, profile=None):
+    """
+    Ensure an Actions secret is present in the targeted 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.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    return sc_actions.secret_present(
+        conn,
+        name,
+        repo_name,
+        value=value,
+        force=force,
+        owner=owner,
+        test=__opts__["test"],
+    )
+
+
+@catch_errors
+def secret_absent(name, profile=None):
+    """
+    Ensure an Actions secret is absent from the targeted repository.
+
+    name
+        Name of the secret. GitHub treats secret names
+        case-insensitively.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    return sc_actions.secret_absent(conn, name, repo_name, owner=owner, test=__opts__["test"])
+
+
+@catch_errors
+def workflow_permissions_managed(
+    name,
+    default_workflow_permissions=None,
+    can_approve_pull_request_reviews=None,
+    profile=None,
+):
+    """
+    Manage the default workflow permissions granted to the ``GITHUB_TOKEN``
+    in the targeted repository.
+
+    name
+        State name (the repository is implied by the resource).
+
+    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.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    return sc_actions.workflow_permissions_managed(
+        conn,
+        name,
+        repo_name,
+        default_workflow_permissions=default_workflow_permissions,
+        can_approve_pull_request_reviews=can_approve_pull_request_reviews,
+        owner=owner,
+        test=__opts__["test"],
+    )

saltext/github/resources/github/states/deploy_key.py

@@ -0,0 +1,130 @@
+"""
+Manage the targeted repository's deploy keys.
+
+.. versionadded:: 1.1.0
+
+Part of the :py:mod:`github <saltext.github.resources.github>` resource type: states operate on the repository
+the state run was dispatched to, so there is no ``repo_name``/``owner``
+parameter. The ``profile`` parameter defaults to the :ghconf:`profile <resource:profile>` named in
+the resource declaration.
+"""
+
+import logging
+
+from salt.utils.functools import namespaced_function
+
+from saltext.github.utils.gh import resource as gh_resource
+from saltext.github.utils.gh.statecores import catch_errors
+from saltext.github.utils.gh.statecores import deploy_keys as sc_deploy_keys
+
+log = logging.getLogger(__name__)
+
+
+_core_args = namespaced_function(gh_resource.core_args, globals())
+
+
+@catch_errors
+def present(name, key, read_only=False, profile=None):
+    """
+    Ensure a deploy key with this title and public key is present
+    in the targeted 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:
+
+    .. code-block:: yaml
+
+        Autorelease deploy key is present:
+          deploy_key.present:
+            - name: autorelease
+            - key: ssh-ed25519 AAAA...
+
+    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.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    return sc_deploy_keys.present(
+        conn,
+        name,
+        key,
+        repo_name,
+        read_only=read_only,
+        owner=owner,
+        test=__opts__["test"],
+    )
+
+
+@catch_errors
+def actions_present(name, secret_name, read_only=False, rotate=False, profile=None):
+    """
+    Ensure a generated SSH keypair is distributed to the targeted
+    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 on the managing minion via :py:func:`ssh_pki.create_private_key
+    <salt.modules.ssh_pki.create_private_key>` 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.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    return sc_deploy_keys.actions_present(
+        conn,
+        name,
+        secret_name,
+        repo_name,
+        keygen=lambda: __minion__["ssh_pki.create_private_key"](algo="ed25519"),
+        read_only=read_only,
+        rotate=rotate,
+        owner=owner,
+        test=__opts__["test"],
+    )
+
+
+@catch_errors
+def absent(name, profile=None):
+    """
+    Ensure no deploy key with this title is present in the targeted
+    repository.
+
+    name
+        Display title of the deploy key.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    return sc_deploy_keys.absent(conn, name, repo_name, owner=owner, test=__opts__["test"])

saltext/github/resources/github/states/environment.py

@@ -0,0 +1,99 @@
+"""
+Manage the targeted repository's (deployment) environments.
+
+.. versionadded:: 1.1.0
+
+Part of the :py:mod:`github <saltext.github.resources.github>` resource type: states operate on the repository
+the state run was dispatched to, so there is no ``repo_name``/``owner``
+parameter. The ``profile`` parameter defaults to the :ghconf:`profile <resource:profile>` named in
+the resource declaration.
+"""
+
+import logging
+
+from salt.utils.functools import namespaced_function
+
+from saltext.github.utils.gh import resource as gh_resource
+from saltext.github.utils.gh.statecores import catch_errors
+from saltext.github.utils.gh.statecores import environments as sc_environments
+
+log = logging.getLogger(__name__)
+
+
+_core_args = namespaced_function(gh_resource.core_args, globals())
+
+
+@catch_errors
+def present(
+    name,
+    wait_timer=None,
+    prevent_self_review=None,
+    reviewers=None,
+    deployment_branches=None,
+    profile=None,
+):
+    """
+    Ensure an environment is present in the targeted repository and
+    configured as specified. Unspecified settings are left unmanaged.
+
+    Example:
+
+    .. code-block:: yaml
+
+        release:
+          environment.present:
+            - deployment_branches:
+              - main
+
+    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.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    return sc_environments.present(
+        conn,
+        name,
+        repo_name,
+        wait_timer=wait_timer,
+        prevent_self_review=prevent_self_review,
+        reviewers=reviewers,
+        deployment_branches=deployment_branches,
+        owner=owner,
+        test=__opts__["test"],
+    )
+
+
+@catch_errors
+def absent(name, profile=None):
+    """
+    Ensure an environment is absent from the targeted repository.
+
+    name
+        Name of the environment.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    return sc_environments.absent(conn, name, repo_name, owner=owner, test=__opts__["test"])

saltext/github/resources/github/states/label.py

@@ -0,0 +1,71 @@
+"""
+Manage the targeted repository's labels.
+
+.. versionadded:: 1.1.0
+
+Part of the :py:mod:`github <saltext.github.resources.github>` resource type: states operate on the repository
+the state run was dispatched to, so there is no ``repo_name``/``owner``
+parameter. The ``profile`` parameter defaults to the :ghconf:`profile <resource:profile>` named in
+the resource declaration.
+"""
+
+import logging
+
+from salt.utils.functools import namespaced_function
+
+from saltext.github.utils.gh import resource as gh_resource
+from saltext.github.utils.gh.statecores import catch_errors
+from saltext.github.utils.gh.statecores import labels as sc_labels
+
+log = logging.getLogger(__name__)
+
+
+_core_args = namespaced_function(gh_resource.core_args, globals())
+
+
+@catch_errors
+def present(name, color=None, description=None, profile=None):
+    """
+    Ensure a label is present in the targeted 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.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    return sc_labels.present(
+        conn,
+        name,
+        repo_name,
+        color=color,
+        description=description,
+        owner=owner,
+        test=__opts__["test"],
+    )
+
+
+@catch_errors
+def absent(name, profile=None):
+    """
+    Ensure a label is absent from the targeted repository.
+
+    name
+        Name of the label.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    return sc_labels.absent(conn, name, repo_name, owner=owner, test=__opts__["test"])

saltext/github/resources/github/states/pages.py

@@ -0,0 +1,92 @@
+"""
+Manage the targeted repository's GitHub Pages site.
+
+.. versionadded:: 1.1.0
+
+Part of the :py:mod:`github <saltext.github.resources.github>` resource type: states operate on the repository
+the state run was dispatched to, so there is no ``repo_name``/``owner``
+parameter. The ``profile`` parameter defaults to the :ghconf:`profile <resource:profile>` named in
+the resource declaration.
+"""
+
+import logging
+
+from salt.utils.functools import namespaced_function
+
+from saltext.github.utils.gh import resource as gh_resource
+from saltext.github.utils.gh.statecores import catch_errors
+from saltext.github.utils.gh.statecores import pages as sc_pages
+
+log = logging.getLogger(__name__)
+
+
+_core_args = namespaced_function(gh_resource.core_args, globals())
+
+
+@catch_errors
+def present(
+    name,
+    build_type=None,
+    source_branch=None,
+    source_path=None,
+    cname=None,
+    https_enforced=None,
+    profile=None,
+):
+    """
+    Ensure GitHub Pages are enabled for the targeted repository and
+    configured as specified. Unspecified settings are left unmanaged.
+
+    name
+        State name (the repository is implied by the resource).
+
+    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.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    return sc_pages.present(
+        conn,
+        name,
+        repo_name,
+        build_type=build_type,
+        source_branch=source_branch,
+        source_path=source_path,
+        cname=cname,
+        https_enforced=https_enforced,
+        owner=owner,
+        test=__opts__["test"],
+    )
+
+
+@catch_errors
+def absent(name, profile=None):
+    """
+    Ensure GitHub Pages are disabled for the targeted repository.
+
+    name
+        State name (the repository is implied by the resource).
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    return sc_pages.absent(conn, name, repo_name, owner=owner, test=__opts__["test"])

saltext/github/resources/github/states/repo.py

@@ -0,0 +1,108 @@
+"""
+Manage the targeted repository's settings and team associations.
+
+.. versionadded:: 1.1.0
+
+Part of the :py:mod:`github <saltext.github.resources.github>` resource type: states operate on the repository
+the state run was dispatched to, so there is no ``repo_name``/``owner``
+parameter. The ``profile`` parameter defaults to the :ghconf:`profile <resource:profile>` named in
+the resource declaration.
+"""
+
+import logging
+
+from salt.utils.functools import namespaced_function
+
+from saltext.github.utils.gh import profile as gh_profile
+from saltext.github.utils.gh import resource as gh_resource
+from saltext.github.utils.gh.statecores import catch_errors
+from saltext.github.utils.gh.statecores import repo as sc_repo
+
+log = logging.getLogger(__name__)
+
+
+_core_args = namespaced_function(gh_resource.core_args, globals())
+
+
+@catch_errors
+def managed(
+    name,
+    description=None,
+    homepage=None,
+    private=None,
+    has_issues=None,
+    has_wiki=None,
+    has_downloads=None,
+    default_branch=None,
+    teams=None,
+    profile=None,
+):
+    """
+    Ensure the targeted repository is configured as specified.
+    Unspecified settings are left unmanaged.
+
+    Unlike the classic ``github_repo.present`` state, this never
+    creates the repository — the resource's existence is a given.
+
+    name
+        State name (the repository is implied by the resource).
+
+    description
+        Repository description.
+
+    homepage
+        URL with more information about the repository, e.g. rendered docs.
+
+    private
+        Repository visibility. Changing this requires :ghconf:`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.
+
+    default_branch
+        Default branch of the repository. The branch must already exist.
+
+    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.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    allow_privacy_change = gh_profile.get_config_value(
+        profile or gh_profile.resource_owner_profile(__opts__, owner),
+        "allow_repo_privacy_changes",
+        opts=__opts__,
+        context=__context__,
+        default=False,
+    )
+    ret = sc_repo.present(
+        conn,
+        repo_name,
+        owner=owner,
+        description=description,
+        homepage=homepage,
+        private=private,
+        has_issues=has_issues,
+        has_wiki=has_wiki,
+        has_downloads=has_downloads,
+        default_branch=default_branch,
+        teams=teams,
+        allow_privacy_change=allow_privacy_change,
+        allow_create=False,
+        test=__opts__["test"],
+    )
+    ret["name"] = name
+    return ret

saltext/github/resources/github/states/ruleset.py

@@ -0,0 +1,81 @@
+"""
+Manage the targeted repository's rulesets.
+
+.. versionadded:: 1.1.0
+
+Part of the :py:mod:`github <saltext.github.resources.github>` resource type: states operate on the repository
+the state run was dispatched to, so there is no ``repo_name``/``owner``
+parameter. The ``profile`` parameter defaults to the :ghconf:`profile <resource:profile>` named in
+the resource declaration.
+"""
+
+import logging
+
+from salt.utils.functools import namespaced_function
+
+from saltext.github.utils.gh import resource as gh_resource
+from saltext.github.utils.gh.statecores import catch_errors
+from saltext.github.utils.gh.statecores import rulesets as sc_rulesets
+
+log = logging.getLogger(__name__)
+
+
+_core_args = namespaced_function(gh_resource.core_args, globals())
+
+
+@catch_errors
+def present(name, ruleset_params=None, profile=None):
+    """
+    Ensure a ruleset is present in the targeted repository and
+    configured as specified. Only the parameters included in
+    ``ruleset_params`` are compared, server-populated fields are
+    ignored.
+
+    Example:
+
+    .. code-block:: yaml
+
+        Ensure ruleset test is present:
+          ruleset.present:
+            - name: test
+            - 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``.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    return sc_rulesets.present(
+        conn,
+        name,
+        repo_name,
+        ruleset_params=ruleset_params,
+        owner=owner,
+        test=__opts__["test"],
+    )
+
+
+@catch_errors
+def absent(name, profile=None):
+    """
+    Ensure a ruleset is absent from the targeted repository.
+
+    name
+        Ruleset name to manage.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    return sc_rulesets.absent(conn, name, repo_name, owner=owner, test=__opts__["test"])