saltext.github 1.1.0__py3-none-any.whl

saltext/github/modules/github_user.py

@@ -0,0 +1,75 @@
+"""
+Look up information about GitHub **user** accounts.
+
+.. versionadded:: 1.1.0
+
+:depends: PyGithub python module
+
+Configuration
+-------------
+
+This module reads its configuration from profiles, which are described
+in the :ref:`configuration guide <github-configuration>`. All functions
+accept a ``profile`` argument, defaulting to the ``github`` profile.
+"""
+
+import logging
+
+from saltext.github.utils.gh import profile as gh_profile
+from saltext.github.utils.gh import users as gh_users
+
+log = logging.getLogger(__name__)
+
+__virtualname__ = "github_user"
+
+
+def _get_conn(profile):
+    return gh_profile.get_conn(profile, opts=__opts__, context=__context__)
+
+
+def info(name=None, profile="github"):
+    """
+    Return the public profile of a user account. Fails when the account
+    is an organization. Use :py:func:`github.account_info
+    <saltext.github.modules.github.account_info>` to look up accounts of
+    either type (note that it defaults to the profile's owner instead of
+    the token's user).
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt-call github_user.info github-handle
+        salt-call github_user.info  # the token's user
+
+    name
+        Login of the user to look up. Defaults to the user the
+        profile's token belongs to.
+
+    profile
+        Profile configuration name to use. Defaults to ``github``.
+    """
+    return gh_users.get_info(_get_conn(profile), name, expect="User")
+
+
+def list_keys(name=None, profile="github"):
+    """
+    Return the verified public SSH keys of any user as a list of
+    mappings with ``id`` and ``key`` fields, e.g. for use with the
+    :py:func:`ssh_auth.present <salt.states.ssh_auth.present>` state.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt-call github_user.list_keys github-handle
+        salt-call github_user.list_keys  # the token's user
+
+    name
+        Login of the user whose keys to list. Defaults to the user the
+        profile's token belongs to.
+
+    profile
+        Profile configuration name to use. Defaults to ``github``.
+    """
+    return gh_users.list_keys(_get_conn(profile), name)

saltext/github/resources/github/__init__.py

@@ -0,0 +1,251 @@
+"""
+Connection module for the ``github`` resource type, which manages
+GitHub repositories as Salt resources (requires Salt 3008.3+).
+
+.. versionadded:: 1.1.0
+
+Each resource is a single repository, identified by ``owner/repo``
+(e.g. the SRN ``github:my-org/my-repo``). Jobs dispatched to a resource
+run the per-type execution and state modules shipped in this package's
+``modules``/``states`` directories, which operate on the targeted
+repository implicitly.
+
+Configuration
+-------------
+
+The resource type is declared in the managing minion's pillar, under
+the subtree selected by :conf_minion:`resource_pillar_key` (default
+``resources``)::
+
+    resources:
+      github:
+        profile: github
+        owners:
+          - my-org
+
+The declaration keys (:ghconf:`resource:profile`, :ghconf:`resource:owners`,
+:ghconf:`resource:repos`/:ghconf:`resource:exclude` patterns,
+:ghconf:`resource:include_archived` and :ghconf:`resource:grains_files`
+for custom grains sourced from in-repo YAML/JSON files) are described in
+the :ref:`configuration guide <github-resource-configuration>`.
+``owners`` may be a mapping, overriding any of the other declaration
+keys per owner::
+
+    resources:
+      github:
+        owners:
+          my-github-handle:
+            exclude:
+              - not-this
+          my-org:
+            repos:
+              - foo*
+          other-org:
+            profile: other_github_org
+"""
+
+import fnmatch
+import logging
+
+from salt.exceptions import CommandExecutionError
+
+from saltext.github.utils.gh import grains_files as gh_grains_files
+from saltext.github.utils.gh import profile as gh_profile
+from saltext.github.utils.gh import repos as gh_repos
+
+log = logging.getLogger(__name__)
+
+__virtualname__ = "github"
+
+
+def __virtual__():
+    return __virtualname__
+
+
+def _resource_id():
+    """
+    Return the ID (``owner/repo``) of the resource currently being
+    operated on.
+    """
+    return __resource__["id"]
+
+
+def _split_id(resource_id):
+    """
+    Split a resource ID into owner and repository name.
+    """
+    owner, _, repo_name = resource_id.partition("/")
+    return owner, repo_name
+
+
+def _matches(patterns, full_name, name):
+    """
+    Report whether a repository matches any of the fnmatch patterns.
+    Patterns containing a slash match the full name (``owner/repo``),
+    others the bare repository name, both case-insensitively.
+    """
+    for pattern in patterns:
+        target = full_name if "/" in pattern else name
+        if fnmatch.fnmatch(target.lower(), pattern.lower()):
+            return True
+    return False
+
+
+def _conn(opts, owner=None):
+    """
+    Return the connection for an owner per the resource declaration
+    (per-owner profile override or the declared default profile).
+    """
+    return gh_profile.resource_conn(opts, __context__, owner=owner)
+
+
+def init(opts):
+    """
+    Initialize the ``github`` resource type for this minion.
+
+    Validates that all declared profiles (the default one and any
+    per-owner overrides) carry a token (without contacting the API),
+    validates any ``grains_files`` declarations and records the
+    type-level state in ``__context__``.
+    """
+    profiles = gh_profile.resource_profiles(opts)
+    # Fail fast on unconfigured profiles; the connections themselves
+    # are established lazily on first use.
+    for profile in profiles:
+        gh_profile.get_config_value(profile, "token", opts=opts, context=__context__)
+    # Fail fast on malformed custom grains declarations.
+    decl = gh_profile.resource_decl(opts)
+    gh_grains_files.validate(decl.get("grains_files"))
+    owners = decl.get("owners")
+    if isinstance(owners, dict):
+        for settings in owners.values():
+            if isinstance(settings, dict):
+                gh_grains_files.validate(settings.get("grains_files"))
+    __context__["github_resource"] = {
+        "initialized": True,
+        "profiles": profiles,
+    }
+    log.debug("github resource init() done, profiles: %s", profiles)
+
+
+def initialized():
+    """
+    Return whether ``init()`` has been called successfully for this
+    resource type.
+    """
+    return __context__.get("github_resource", {}).get("initialized", False)
+
+
+def discover(opts):
+    """
+    Return the ``owner/repo`` IDs of the repositories this minion
+    manages: all repositories of the declared owners, filtered by the
+    ``repos``/``exclude`` patterns and the ``include_archived`` flag,
+    each of which can be overridden per owner.
+    """
+    owners = gh_profile.resource_owners(opts) or [_conn(opts).owner]
+
+    discovered = []
+    for owner in owners:
+        include = gh_profile.resource_owner_setting(opts, owner, "repos") or ["*"]
+        exclude = gh_profile.resource_owner_setting(opts, owner, "exclude") or []
+        include_archived = gh_profile.resource_owner_setting(opts, owner, "include_archived", False)
+        conn = _conn(opts, owner)
+        for repo in gh_repos.list_all(conn, owner=owner):
+            if repo.archived and not include_archived:
+                continue
+            if not _matches(include, repo.full_name, repo.name):
+                continue
+            if _matches(exclude, repo.full_name, repo.name):
+                continue
+            discovered.append(repo.full_name)
+    log.debug("github resource discover() returning: %s", discovered)
+    return sorted(discovered)
+
+
+def grains():
+    """
+    Return the grains of the current resource: the repository's identity
+    and basic metadata, merged with any custom grains sourced from
+    in-repo files per the declaration's ``grains_files`` key.
+    """
+    resource_id = _resource_id()
+    owner, repo_name = _split_id(resource_id)
+    conn = _conn(__opts__, owner)
+    # Warm the per-owner cache: a single listing serves the grains of
+    # all of this owner's resources within one context.
+    gh_repos.list_all(conn, owner=owner)
+    info = gh_repos.get_info(conn, repo_name, owner=owner)
+    ret = {
+        "id": resource_id,
+        "owner": info["owner"],
+        "repo": info["name"],
+        "full_name": info["full_name"],
+        "private": info["private"],
+        "visibility": info["visibility"],
+        "fork": info["fork"],
+        "archived": info["archived"],
+        "disabled": info["disabled"],
+        "is_template": info["is_template"],
+        "default_branch": info["default_branch"],
+        "language": info["language"],
+        "license": info["license"],
+        "topics": info["topics"],
+        "custom_properties": info["custom_properties"],
+        "html_url": info["html_url"],
+        "clone_url": info["clone_url"],
+        "ssh_url": info["ssh_url"],
+        "description": info["description"],
+        "homepage": info["homepage"],
+        "created_at": info["created_at"],
+        "has_discussions": info["has_discussions"],
+        "has_pages": info["has_pages"],
+        "has_projects": info["has_projects"],
+    }
+    spec = gh_profile.resource_owner_setting(__opts__, owner, "grains_files")
+    if spec:
+        # Revalidate: the pillar can have changed since init(). The
+        # identity grains must survive declaration/content problems.
+        try:
+            normalized = gh_grains_files.validate(spec)
+        except CommandExecutionError as err:
+            log.error("Invalid grains_files declaration, skipping custom grains: %s", err)
+        else:
+            custom = gh_grains_files.collect(conn, repo_name, normalized, owner=owner)
+            gh_grains_files.merge_grains(ret, custom)
+    return ret
+
+
+def grains_refresh():
+    """
+    Return freshly fetched grains for the current resource, bypassing
+    cached repository information and file contents.
+    """
+    owner, repo_name = _split_id(_resource_id())
+    conn = _conn(__opts__, owner)
+    gh_repos.get_info(conn, repo_name, owner=owner, ignore_cache=True)
+    gh_repos.clear_file_cache(conn, repo_name, owner=owner)
+    return grains()
+
+
+def ping():
+    """
+    Return whether the current resource's repository is reachable via
+    the API.
+    """
+    owner, repo_name = _split_id(_resource_id())
+    try:
+        conn = _conn(__opts__, owner)
+        gh_repos.get_info(conn, repo_name, owner=owner, ignore_cache=True)
+    except CommandExecutionError as err:
+        log.debug("github resource ping() failed for %s/%s: %s", owner, repo_name, err)
+        return False
+    return True
+
+
+def shutdown(opts):  # pylint: disable=unused-argument
+    """
+    Tear down the ``github`` resource type, dropping the type-level
+    state from ``__context__``.
+    """
+    __context__.pop("github_resource", None)

saltext/github/resources/github/modules/actions.py

@@ -0,0 +1,175 @@
+"""
+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: all functions operate on the
+repository the job was dispatched to. 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 import filter_fields
+from saltext.github.utils.gh import actions as gh_actions
+from saltext.github.utils.gh import resource as gh_resource
+
+log = logging.getLogger(__name__)
+
+
+_core_args = namespaced_function(gh_resource.core_args, globals())
+
+
+def list_secrets(*, fields=None, profile=None):
+    """
+    List the Actions secrets of the targeted repository, as a mapping
+    of secret name to metadata. Secret values are write-only, so this
+    only returns metadata (``created_at``, ``updated_at``).
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' actions.list_secrets
+
+    fields
+        Only include these fields in the output. A single field name
+        reduces each entry to the field's value.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    secrets = gh_actions.list_secrets(conn, repo_name, owner=owner)
+    return filter_fields({secret["name"]: secret for secret in secrets}, fields)
+
+
+def get_secret(name, *, profile=None):
+    """
+    Return the metadata of a single Actions secret of the targeted
+    repository. The value itself is write-only and cannot be retrieved.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' actions.get_secret MY_SECRET
+
+    name
+        Name of the secret.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    return gh_actions.get_secret(conn, repo_name, name, owner=owner)
+
+
+def set_secret(name, value, *, profile=None):
+    """
+    Create or update an Actions secret of the targeted repository. The
+    value is encrypted to the repository public key before leaving the
+    minion.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' actions.set_secret MY_SECRET hunter2
+
+    name
+        Name of the secret.
+
+    value
+        Plaintext secret value.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    gh_actions.set_secret(conn, repo_name, name, value, owner=owner)
+    return True
+
+
+def remove_secret(name, *, profile=None):
+    """
+    Remove an Actions secret from the targeted repository.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' actions.remove_secret MY_SECRET
+
+    name
+        Name of the secret.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    gh_actions.delete_secret(conn, repo_name, name, owner=owner)
+    return True
+
+
+def get_workflow_permissions(*, profile=None):
+    """
+    Return the default workflow permissions granted to the ``GITHUB_TOKEN``
+    in the targeted repository, a mapping with ``default_workflow_permissions``
+    (``read``/``write``) and ``can_approve_pull_request_reviews``.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' actions.get_workflow_permissions
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    return gh_actions.get_workflow_permissions(conn, repo_name, owner=owner)
+
+
+def set_workflow_permissions(
+    *, default_workflow_permissions=None, can_approve_pull_request_reviews=None, profile=None
+):
+    """
+    Update the default workflow permissions granted to the ``GITHUB_TOKEN``
+    in the targeted repository.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' actions.set_workflow_permissions \\
+            default_workflow_permissions=read can_approve_pull_request_reviews=true
+
+    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)
+    gh_actions.set_workflow_permissions(
+        conn,
+        repo_name,
+        default_workflow_permissions=default_workflow_permissions,
+        can_approve_pull_request_reviews=can_approve_pull_request_reviews,
+        owner=owner,
+    )
+    return True

saltext/github/resources/github/modules/config.py

@@ -0,0 +1,69 @@
+"""
+Look up configuration values from the managing minion.
+
+.. versionadded:: 1.1.0
+
+Repositories have no minion configuration of their own — GitHub
+profiles and related settings live on the managing minion. The stock
+:py:mod:`state <salt.modules.state>` execution module (re-exported for
+this resource type) relies on ``config.get``/``config.option``, so this
+override provides them: it delegates to the managing minion's loader
+when the ``__minion__`` escape hatch is packed (state-engine context)
+and falls back to the managing minion's opts otherwise (the minion's
+dispatch-context per-type loaders do not pack ``__minion__``).
+"""
+
+import logging
+
+import salt.utils.data
+
+log = logging.getLogger(__name__)
+
+
+def _minion():
+    try:
+        return __minion__
+    except NameError:
+        return None
+
+
+def get(key, default="", delimiter=":", omit_opts=False, **kwargs):
+    """
+    Look up a config value on the managing minion. See
+    :py:func:`config.get <salt.modules.config.get>` for details.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' config.get state_verbose
+    """
+    minion = _minion()
+    if minion is not None:
+        return minion["config.get"](
+            key, default=default, delimiter=delimiter, omit_opts=omit_opts, **kwargs
+        )
+    if omit_opts:
+        return default
+    return salt.utils.data.traverse_dict_and_list(__opts__, key, default, delimiter)
+
+
+def option(value, default="", omit_opts=False, omit_all=False, **kwargs):
+    """
+    Return the value of a specific config option on the managing minion.
+    See :py:func:`config.option <salt.modules.config.option>` for details.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' config.option state_queue
+    """
+    minion = _minion()
+    if minion is not None:
+        return minion["config.option"](
+            value, default=default, omit_opts=omit_opts, omit_all=omit_all, **kwargs
+        )
+    if not (omit_opts or omit_all) and value in __opts__:
+        return __opts__[value]
+    return default

saltext/github/resources/github/modules/deploy_key.py

@@ -0,0 +1,122 @@
+"""
+Manage the targeted repository's deploy keys.
+
+.. versionadded:: 1.1.0
+
+Part of the :py:mod:`github <saltext.github.resources.github>` resource type: all functions operate on the
+repository the job was dispatched to. 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 import filter_fields
+from saltext.github.utils.gh import deploy_keys as gh_deploy_keys
+from saltext.github.utils.gh import resource as gh_resource
+
+log = logging.getLogger(__name__)
+
+__func_alias__ = {"list_": "list"}
+
+
+_core_args = namespaced_function(gh_resource.core_args, globals())
+
+
+def list_(*, fields=None, profile=None):
+    """
+    List the deploy keys of the targeted repository.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' deploy_key.list
+
+    fields
+        Only include these fields in the output. A single field name
+        reduces each entry to the field's value.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    return filter_fields(gh_deploy_keys.list_all(conn, repo_name, owner=owner), fields)
+
+
+def get(key_id, *, profile=None):
+    """
+    Return the data of a single deploy key of the targeted repository.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' deploy_key.get 12345
+
+    key_id
+        ID 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 gh_deploy_keys.get(conn, repo_name, key_id, owner=owner)
+
+
+def add(title, key, *, read_only=False, profile=None):
+    """
+    Add a deploy key to the targeted repository.
+    Returns the data of the created key.
+
+    .. note::
+        Deploy keys are immutable. To modify one, remove it and add a replacement.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' deploy_key.add autorelease 'ssh-ed25519 AAAA...' read_only=false
+
+    title
+        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 gh_deploy_keys.create(
+        conn, repo_name, title, key, read_only=bool(read_only), owner=owner
+    )
+
+
+def remove(key_id, *, profile=None):
+    """
+    Remove a deploy key from the targeted repository.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt 'my-org/my-repo' deploy_key.remove 12345
+
+    key_id
+        ID of the deploy key.
+
+    profile
+        Profile configuration name to use. Defaults to the resource
+        declaration's profile.
+    """
+    conn, owner, repo_name = _core_args(profile)
+    gh_deploy_keys.delete(conn, repo_name, key_id, owner=owner)
+    return True