saltext.github 1.1.0__py3-none-any.whl

saltext/github/utils/gh/statecores/__init__.py

@@ -0,0 +1,70 @@
+"""
+Shared cores implementing the repository-scoped states: the full
+inspect -> test-gate -> apply flow, including change reporting.
+
+They are consumed by the classic :py:mod:`github_repo
+<saltext.github.states.github_repo>` state module as well as the
+``github`` resource type's state modules, which are both thin wrappers
+handling identity and connection resolution.
+
+The cores return complete state return dictionaries (``name``,
+``changes``, ``result``, ``comment``) and raise
+:py:class:`CommandExecutionError <salt.exceptions.CommandExecutionError>`
+(usually the :py:mod:`gh <saltext.github.utils.gh>` subclasses) on
+failures, which the wrappers translate into a failed state return.
+"""
+
+import functools
+
+from salt.exceptions import CommandExecutionError
+
+
+class StateError(CommandExecutionError):
+    """
+    Raised when applying state changes failed. Compound states can
+    attach the changes that were applied before the failure, which
+    :func:`failed`/:func:`catch_errors` include in the state return.
+    """
+
+    def __init__(self, message, *, changes=None):
+        super().__init__(message)
+        self.changes = changes or {}
+
+
+def failed(name, err):
+    """
+    Render a raised error into a failed state return, including
+    partially applied changes carried by the error (:class:`StateError`).
+    """
+    return {
+        "name": name,
+        "changes": getattr(err, "changes", None) or {},
+        "result": False,
+        "comment": str(err),
+    }
+
+
+def catch_errors(func):
+    """
+    Wrap a state function to render raised
+    :class:`CommandExecutionError <salt.exceptions.CommandExecutionError>`
+    into a failed state return instead of a traceback.
+    """
+
+    @functools.wraps(func)
+    def wrapper(name, *args, **kwargs):
+        try:
+            return func(name, *args, **kwargs)
+        except CommandExecutionError as err:
+            return failed(name, err)
+
+    return wrapper
+
+
+def differs(current, desired):
+    """
+    Report whether a managed parameter needs updating. The identity check
+    makes boolean comparisons exact: since ``True == 1`` in Python, an
+    equality check alone would not register e.g. ``1`` -> ``True``.
+    """
+    return current is not desired and current != desired

saltext/github/utils/gh/statecores/actions.py

@@ -0,0 +1,180 @@
+"""
+State cores managing repository Actions secrets and workflow permissions.
+"""
+
+import logging
+
+from salt.exceptions import CommandExecutionError
+
+from saltext.github.utils import filter_unset
+from saltext.github.utils.gh import actions as gh_actions
+
+log = logging.getLogger(__name__)
+
+
+def secret_present(conn, name, repo_name, *, value=None, force=False, owner=None, test=False):
+    """
+    Ensure an Actions secret is present in a repository.
+
+    Secret values are write-only in the GitHub API, so this core cannot
+    detect value drift. By default, an existing secret is left untouched.
+    Set ``force`` to push the value on every run.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    name
+        Name of the secret. GitHub treats secret names
+        case-insensitively.
+
+    repo_name
+        Name of the repository.
+
+    value
+        Plaintext secret value. 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.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+
+    test
+        Only project the changes without applying them (``test`` mode).
+    """
+    ret = {"name": name, "changes": {}, "result": True, "comment": ""}
+
+    secrets = [sec["name"] for sec in gh_actions.list_secrets(conn, repo_name, owner=owner)]
+    current = next((sec for sec in secrets if sec.lower() == name.lower()), None)
+
+    if current is not None and not force:
+        ret["comment"] = (
+            f"Secret {name} is already present. Note that secret values are "
+            "write-only and cannot be verified, set force to push the value."
+        )
+        return ret
+
+    if value is None:
+        raise CommandExecutionError(f"A value is required to set secret {name}")
+
+    if current is None:
+        ret["changes"]["created"] = name
+        verb = "created"
+    else:
+        ret["changes"]["updated"] = name
+        verb = "updated"
+
+    if test:
+        ret["result"] = None
+        ret["comment"] = f"Secret {name} would have been {verb}"
+        return ret
+
+    gh_actions.set_secret(conn, repo_name, name, value, owner=owner)
+    ret["comment"] = f"Secret {name} has been {verb}"
+    return ret
+
+
+def secret_absent(conn, name, repo_name, *, owner=None, test=False):
+    """
+    Ensure an Actions secret is absent from a repository.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    name
+        Name of the secret. GitHub treats secret names
+        case-insensitively.
+
+    repo_name
+        Name of the repository.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+
+    test
+        Only project the changes without applying them (``test`` mode).
+    """
+    ret = {"name": name, "changes": {}, "result": True, "comment": ""}
+
+    secrets = [sec["name"] for sec in gh_actions.list_secrets(conn, repo_name, owner=owner)]
+    current = next((sec for sec in secrets if sec.lower() == name.lower()), None)
+    if current is None:
+        ret["comment"] = f"Secret {name} is already absent"
+        return ret
+
+    ret["changes"]["deleted"] = current
+    if test:
+        ret["result"] = None
+        ret["comment"] = f"Secret {name} would have been removed"
+        return ret
+
+    gh_actions.delete_secret(conn, repo_name, current, owner=owner)
+    ret["comment"] = f"Secret {name} has been removed"
+    return ret
+
+
+def workflow_permissions_managed(
+    conn,
+    name,
+    repo_name,
+    *,
+    default_workflow_permissions=None,
+    can_approve_pull_request_reviews=None,
+    owner=None,
+    test=False,
+):
+    """
+    Manage the default workflow permissions granted to the ``GITHUB_TOKEN``
+    in a repository.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    name
+        State name (reported back unchanged).
+
+    repo_name
+        Name of the repository.
+
+    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.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+
+    test
+        Only project the changes without applying them (``test`` mode).
+    """
+    ret = {"name": name, "changes": {}, "result": True, "comment": ""}
+
+    desired = filter_unset(
+        {
+            "default_workflow_permissions": default_workflow_permissions,
+            "can_approve_pull_request_reviews": can_approve_pull_request_reviews,
+        }
+    )
+    if not desired:
+        raise CommandExecutionError("At least one setting to manage must be specified")
+
+    current = gh_actions.get_workflow_permissions(conn, repo_name, owner=owner)
+    diff = {key: val for key, val in desired.items() if current.get(key) != val}
+    if not diff:
+        ret["comment"] = "Workflow permissions are already set as specified"
+        return ret
+
+    ret["changes"]["old"] = {key: current.get(key) for key in diff}
+    ret["changes"]["new"] = diff
+    if test:
+        ret["result"] = None
+        ret["comment"] = "Workflow permissions would have been updated"
+        return ret
+
+    gh_actions.set_workflow_permissions(conn, repo_name, owner=owner, **diff)
+    ret["comment"] = "Workflow permissions have been updated"
+    return ret

saltext/github/utils/gh/statecores/deploy_keys.py

@@ -0,0 +1,241 @@
+"""
+State core managing repository deploy keys.
+"""
+
+import logging
+
+from salt.exceptions import CommandExecutionError
+
+from saltext.github.utils.gh import actions as gh_actions
+from saltext.github.utils.gh import deploy_keys as gh_deploy_keys
+from saltext.github.utils.gh.statecores import StateError
+
+log = logging.getLogger(__name__)
+
+
+def present(conn, name, key, repo_name, *, read_only=False, owner=None, test=False):
+    """
+    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).
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    name
+        Display title of the deploy key.
+
+    key
+        SSH public key.
+
+    repo_name
+        Name of the repository.
+
+    read_only
+        Deny write access to the repository for this key. Defaults to false.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+
+    test
+        Only project the changes without applying them (``test`` mode).
+    """
+    ret = {"name": name, "changes": {}, "result": True, "comment": ""}
+
+    keys = gh_deploy_keys.list_all(conn, repo_name, owner=owner)
+    current = next((cur for cur in keys if cur["title"] == name), None)
+
+    if current is not None:
+        if gh_deploy_keys.key_body(current["key"]) == gh_deploy_keys.key_body(key) and bool(
+            current["read_only"]
+        ) is bool(read_only):
+            ret["comment"] = f"Deploy key {name} is present as specified"
+            return ret
+        ret["changes"]["old"] = {"key": current["key"], "read_only": current["read_only"]}
+        ret["changes"]["new"] = {"key": gh_deploy_keys.key_body(key), "read_only": bool(read_only)}
+    else:
+        ret["changes"]["created"] = name
+
+    verb = "added" if current is None else "replaced"
+    if test:
+        ret["result"] = None
+        ret["comment"] = f"Deploy key {name} would have been {verb}"
+        return ret
+
+    if current is not None:
+        gh_deploy_keys.delete(conn, repo_name, current["id"], owner=owner)
+    gh_deploy_keys.create(conn, repo_name, name, key, read_only=bool(read_only), owner=owner)
+    ret["comment"] = f"Deploy key {name} has been {verb}"
+    return ret
+
+
+def actions_present(
+    conn,
+    name,
+    secret_name,
+    repo_name,
+    *,
+    keygen,
+    read_only=False,
+    rotate=False,
+    owner=None,
+    test=False,
+):
+    """
+    Ensure a generated SSH keypair is distributed to a repository:
+    the public half as a deploy key, the private half as an Actions
+    secret. The keypair is generated in memory 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.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    name
+        Display title of the deploy key.
+
+    secret_name
+        Name of the Actions secret holding the private key. GitHub
+        treats secret names case-insensitively.
+
+    repo_name
+        Name of the repository.
+
+    keygen
+        Callable generating the keypair, returning a mapping with
+        ``private_key`` (OpenSSH PEM format) and ``public_key``
+        (OpenSSH single-line format), like
+        :py:func:`ssh_pki.create_private_key
+        <salt.modules.ssh_pki.create_private_key>` does. Only invoked
+        when a new pair needs to be distributed.
+
+    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.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+
+    test
+        Only project the changes without applying them (``test`` mode).
+    """
+    ret = {"name": name, "changes": {}, "result": True, "comment": ""}
+
+    keys = gh_deploy_keys.list_all(conn, repo_name, owner=owner)
+    current = next((cur for cur in keys if cur["title"] == name), None)
+    secrets = [sec["name"] for sec in gh_actions.list_secrets(conn, repo_name, owner=owner)]
+    current_secret = next((sec for sec in secrets if sec.lower() == secret_name.lower()), None)
+
+    if current is not None and current_secret is not None and not rotate:
+        if bool(current["read_only"]) is bool(read_only):
+            ret["comment"] = (
+                f"Deploy key {name} and secret {secret_name} are present. Note that "
+                "the private key cannot be verified to match the deploy key, "
+                "set rotate to regenerate the pair."
+            )
+            return ret
+        # Deploy keys are immutable, but the read_only flag can be
+        # flipped by re-adding the known public key. The secret is
+        # left untouched since the pair still matches.
+        ret["changes"]["old"] = {"read_only": current["read_only"]}
+        ret["changes"]["new"] = {"read_only": bool(read_only)}
+        if test:
+            ret["result"] = None
+            ret["comment"] = f"Deploy key {name} would have been replaced"
+            return ret
+        applied = {}
+        try:
+            gh_deploy_keys.delete(conn, repo_name, current["id"], owner=owner)
+            applied["deleted"] = name
+            gh_deploy_keys.create(
+                conn, repo_name, name, current["key"], read_only=bool(read_only), owner=owner
+            )
+        except CommandExecutionError as err:
+            raise StateError(str(err), changes=applied) from err
+        ret["comment"] = f"Deploy key {name} has been replaced"
+        return ret
+
+    key_verb = "created" if current is None else "replaced"
+    secret_verb = "created" if current_secret is None else "updated"
+    ret["changes"]["deploy_key"] = {key_verb: name}
+    ret["changes"]["secret"] = {secret_verb: secret_name}
+
+    if test:
+        ret["result"] = None
+        ret["comment"] = (
+            f"A keypair would have been generated and distributed as "
+            f"deploy key {name} and secret {secret_name}"
+        )
+        return ret
+
+    pair = keygen()
+    private, public = pair["private_key"], f"{pair['public_key'].strip()} {name}"
+    ret["changes"]["deploy_key"]["fingerprint"] = gh_deploy_keys.fingerprint(public)
+
+    # Remove a stale deploy key before pushing the new pair: if a later
+    # step fails, the missing deploy key makes the next run regenerate
+    # the pair. Other orderings can leave a mismatched key and secret
+    # both present, which is undetectable afterwards.
+    applied = {}
+    try:
+        if current is not None:
+            gh_deploy_keys.delete(conn, repo_name, current["id"], owner=owner)
+            applied["deploy_key"] = {"deleted": name}
+        gh_actions.set_secret(conn, repo_name, secret_name, private, owner=owner)
+        applied["secret"] = ret["changes"]["secret"]
+        gh_deploy_keys.create(conn, repo_name, name, public, read_only=bool(read_only), owner=owner)
+    except CommandExecutionError as err:
+        raise StateError(str(err), changes=applied) from err
+
+    ret["comment"] = (
+        f"A keypair has been generated and distributed as "
+        f"deploy key {name} and secret {secret_name}"
+    )
+    return ret
+
+
+def absent(conn, name, repo_name, *, owner=None, test=False):
+    """
+    Ensure no deploy key with this title is present in a repository.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    name
+        Display title of the deploy key.
+
+    repo_name
+        Name of the repository.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+
+    test
+        Only project the changes without applying them (``test`` mode).
+    """
+    ret = {"name": name, "changes": {}, "result": True, "comment": ""}
+
+    keys = gh_deploy_keys.list_all(conn, repo_name, owner=owner)
+    current = next((cur for cur in keys if cur["title"] == name), None)
+    if current is None:
+        ret["comment"] = f"Deploy key {name} is already absent"
+        return ret
+
+    ret["changes"]["deleted"] = name
+    if test:
+        ret["result"] = None
+        ret["comment"] = f"Deploy key {name} would have been removed"
+        return ret
+
+    gh_deploy_keys.delete(conn, repo_name, current["id"], owner=owner)
+    ret["comment"] = f"Deploy key {name} has been removed"
+    return ret

saltext/github/utils/gh/statecores/environments.py

@@ -0,0 +1,212 @@
+"""
+State core managing repository (deployment) environments.
+"""
+
+import logging
+
+from salt.exceptions import CommandExecutionError
+
+from saltext.github.utils import filter_unset
+from saltext.github.utils.gh import environments as gh_environments
+from saltext.github.utils.gh.exceptions import GitHubNotFoundError
+from saltext.github.utils.gh.statecores import StateError
+
+log = logging.getLogger(__name__)
+
+
+def _environment_settings_diff(ret, current_settings, desired):
+    """
+    Record an existing environment's settings that need updating in
+    ``ret`` and return whether there are any.
+    """
+    diff = {}
+    for key, val in desired.items():
+        current_val = current_settings.get(key)
+        if key == "reviewers":
+            matches = sorted((reviewer["type"], reviewer["id"]) for reviewer in val) == sorted(
+                (reviewer["type"], reviewer["id"]) for reviewer in current_val
+            )
+        else:
+            matches = current_val == val
+        if not matches:
+            diff[key] = val
+    if diff:
+        ret["changes"]["old"] = {key: current_settings.get(key) for key in diff}
+        ret["changes"]["new"] = diff
+    return bool(diff)
+
+
+def present(
+    conn,
+    name,
+    repo_name,
+    *,
+    wait_timer=None,
+    prevent_self_review=None,
+    reviewers=None,
+    deployment_branches=None,
+    owner=None,
+    test=False,
+):
+    """
+    Ensure an environment is present in a repository and configured
+    as specified. Unspecified settings are left unmanaged.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    name
+        Name of the environment.
+
+    repo_name
+        Name of the repository.
+
+    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.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+
+    test
+        Only project the changes without applying them (``test`` mode).
+    """
+    ret = {
+        "name": name,
+        "changes": {},
+        "result": True,
+        "comment": f"Environment {name} is configured as specified",
+    }
+
+    try:
+        current = gh_environments.get(conn, repo_name, name, owner=owner)
+    except GitHubNotFoundError:
+        current = None
+
+    desired = filter_unset(
+        {
+            "wait_timer": wait_timer,
+            "prevent_self_review": prevent_self_review,
+            "reviewers": reviewers,
+        }
+    )
+    if deployment_branches is not None:
+        desired["deployment_branch_policy"] = gh_environments.branch_policy_from_patterns(
+            deployment_branches
+        )
+
+    settings_diff = False
+    branches_added, branches_removed, current_policies = [], [], []
+    if current is None:
+        ret["changes"]["created"] = name
+        set_kwargs = desired
+        if isinstance(deployment_branches, list):
+            branches_added = sorted(set(deployment_branches))
+    else:
+        current_settings = gh_environments.normalize(current)
+        settings_diff = _environment_settings_diff(ret, current_settings, desired)
+        # The API call replaces the whole configuration, so settings
+        # that are not managed here need to be carried over.
+        set_kwargs = {**current_settings, **desired}
+        if isinstance(deployment_branches, list):
+            try:
+                current_policies = gh_environments.list_branch_policies(
+                    conn, repo_name, name, owner=owner
+                )
+            except GitHubNotFoundError:
+                # Not found when the current policy type is not "custom"
+                current_policies = []
+            current_patterns = {policy["name"] for policy in current_policies}
+            branches_added = sorted(set(deployment_branches) - current_patterns)
+            branches_removed = sorted(current_patterns - set(deployment_branches))
+
+    if branches_added or branches_removed:
+        ret["changes"]["deployment_branches"] = {
+            "added": branches_added,
+            "removed": branches_removed,
+        }
+
+    if not ret["changes"]:
+        return ret
+
+    verb = "created" if current is None else "updated"
+    if test:
+        ret["result"] = None
+        ret["comment"] = f"Environment {name} would have been {verb}"
+        return ret
+
+    applied = {}
+    try:
+        if current is None or settings_diff:
+            gh_environments.set_(conn, repo_name, name, owner=owner, **set_kwargs)
+            if current is None:
+                applied["created"] = name
+            else:
+                applied["old"] = ret["changes"]["old"]
+                applied["new"] = ret["changes"]["new"]
+        for pattern in branches_added:
+            gh_environments.create_branch_policy(conn, repo_name, name, pattern, owner=owner)
+            applied.setdefault("deployment_branches", {}).setdefault("added", []).append(pattern)
+        for policy in current_policies:
+            if policy["name"] in branches_removed:
+                gh_environments.delete_branch_policy(
+                    conn, repo_name, name, policy["id"], owner=owner
+                )
+                applied.setdefault("deployment_branches", {}).setdefault("removed", []).append(
+                    policy["name"]
+                )
+    except CommandExecutionError as err:
+        raise StateError(str(err), changes=applied) from err
+    ret["comment"] = f"Environment {name} has been {verb}"
+    return ret
+
+
+def absent(conn, name, repo_name, *, owner=None, test=False):
+    """
+    Ensure an environment is absent from a repository.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    name
+        Name of the environment.
+
+    repo_name
+        Name of the repository.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+
+    test
+        Only project the changes without applying them (``test`` mode).
+    """
+    ret = {"name": name, "changes": {}, "result": True, "comment": ""}
+
+    try:
+        gh_environments.get(conn, repo_name, name, owner=owner)
+    except GitHubNotFoundError:
+        ret["comment"] = f"Environment {name} is already absent"
+        return ret
+
+    ret["changes"]["deleted"] = name
+    if test:
+        ret["result"] = None
+        ret["comment"] = f"Environment {name} would have been removed"
+        return ret
+
+    gh_environments.delete(conn, repo_name, name, owner=owner)
+    ret["comment"] = f"Environment {name} has been removed"
+    return ret