Add separate and modern github_org/github_repo modules

changelog/+actions_secrets.added.md

@@ -0,0 +1 @@
+Added management of repository Actions secrets, encrypted client-side to the repository public key ({py:func}`github_repo.list_actions_secrets <saltext.github.modules.github_repo.list_actions_secrets>`/{py:func}`get_actions_secret <saltext.github.modules.github_repo.get_actions_secret>`/{py:func}`set_actions_secret <saltext.github.modules.github_repo.set_actions_secret>`/{py:func}`remove_actions_secret <saltext.github.modules.github_repo.remove_actions_secret>` and the {py:func}`github_repo.actions_secret_present <saltext.github.states.github_repo.actions_secret_present>`/{py:func}`actions_secret_absent <saltext.github.states.github_repo.actions_secret_absent>` states)

changelog/+add_team_profile.fixed.md

@@ -1 +1 @@
-Fixed `add_team` refreshing the team cache using the default profile instead of the configured one
+Fixed {py:func}`github.add_team <saltext.github.modules.github.add_team>` refreshing the team cache using the default profile instead of the configured one

changelog/+api_url.added.md

@@ -1 +1 @@
-Added the optional `api_url` profile option for targeting GitHub Enterprise Server instances
+Added the optional {ghconf}`api_url` profile option for targeting GitHub Enterprise Server instances

changelog/+default_branch.added.md

@@ -0,0 +1 @@
+Added `default_branch` to {py:func}`github_repo.update <saltext.github.modules.github_repo.update>` and the {py:func}`github_repo.present <saltext.github.states.github_repo.present>` state

changelog/+deploy_keys.added.md

@@ -0,0 +1 @@
+Added management of repository deploy keys ({py:func}`github_repo.list_deploy_keys <saltext.github.modules.github_repo.list_deploy_keys>`/{py:func}`get_deploy_key <saltext.github.modules.github_repo.get_deploy_key>`/{py:func}`add_deploy_key <saltext.github.modules.github_repo.add_deploy_key>`/{py:func}`remove_deploy_key <saltext.github.modules.github_repo.remove_deploy_key>` and the {py:func}`github_repo.deploy_key_present <saltext.github.states.github_repo.deploy_key_present>`/{py:func}`deploy_key_absent <saltext.github.states.github_repo.deploy_key_absent>` states)

changelog/+environments.added.md

@@ -0,0 +1 @@
+Added management of repository environments, including deployment branch policies ({py:func}`github_repo.list_environments <saltext.github.modules.github_repo.list_environments>`/{py:func}`get_environment <saltext.github.modules.github_repo.get_environment>`/{py:func}`set_environment <saltext.github.modules.github_repo.set_environment>`/{py:func}`remove_environment <saltext.github.modules.github_repo.remove_environment>`/{py:func}`list_deployment_branch_policies <saltext.github.modules.github_repo.list_deployment_branch_policies>`/{py:func}`add_deployment_branch_policy <saltext.github.modules.github_repo.add_deployment_branch_policy>`/{py:func}`remove_deployment_branch_policy <saltext.github.modules.github_repo.remove_deployment_branch_policy>` and the {py:func}`github_repo.environment_present <saltext.github.states.github_repo.environment_present>`/{py:func}`environment_absent <saltext.github.states.github_repo.environment_absent>` states)

changelog/+get_user_pubkeys.removed.md

@@ -0,0 +1 @@
+Removed the unauthenticated `get_user_pubkeys` helper from `saltext.github.utils.github`. It ignored the configured {ghconf}`api_url`, relied on `salt.utils.http` and was not exposed in any module

changelog/+is_team_member_missing_team.fixed.md

@@ -1 +1 @@
-Fixed ``is_team_member`` crashing with a ``TypeError`` when the team does not exist. It now returns ``False``.
+Fixed {py:func}`github.is_team_member <saltext.github.modules.github.is_team_member>` crashing with a `TypeError` when the team does not exist. It now returns `False`.

changelog/+labels.added.md

@@ -0,0 +1 @@
+Added management of repository labels ({py:func}`github_repo.list_labels <saltext.github.modules.github_repo.list_labels>`/{py:func}`get_label <saltext.github.modules.github_repo.get_label>`/{py:func}`add_label <saltext.github.modules.github_repo.add_label>`/{py:func}`edit_label <saltext.github.modules.github_repo.edit_label>`/{py:func}`remove_label <saltext.github.modules.github_repo.remove_label>` and the {py:func}`github_repo.label_present <saltext.github.states.github_repo.label_present>`/{py:func}`label_absent <saltext.github.states.github_repo.label_absent>` states)

changelog/+legacy_modules.deprecated.md

@@ -0,0 +1 @@
+Deprecated all current functions of the {py:mod}`github execution module <saltext.github.modules.github>` as well as the {py:mod}`github state module <saltext.github.states.github>`. Use the corresponding functions of the new {py:mod}`github_org <saltext.github.modules.github_org>` and {py:mod}`github_repo <saltext.github.modules.github_repo>` modules instead. The `github` execution module remains the namespace for functionality that is not tied to a single organization. The {py:func}`github.list_members_without_mfa <saltext.github.modules.github.list_members_without_mfa>` function and the per-team MFA enforcement of {py:func}`github.team_present <saltext.github.states.github.team_present>` are deprecated without replacement - require 2FA organization-wide in the GitHub settings instead

changelog/+list_funcs_error_crash.fixed.md

@@ -1 +1 @@
-Fixed ``get_issues``, ``get_issue_comments``, ``get_prs`` and ``get_milestones`` crashing with an ``AttributeError`` when the API returned an error. They now raise a ``CommandExecutionError`` carrying the API error message.
+Fixed {py:func}`github.get_issues <saltext.github.modules.github.get_issues>`, {py:func}`github.get_issue_comments <saltext.github.modules.github.get_issue_comments>`, {py:func}`github.get_prs <saltext.github.modules.github.get_prs>` and {py:func}`github.get_milestones <saltext.github.modules.github.get_milestones>` crashing with an `AttributeError` when the API returned an error. They now raise a `CommandExecutionError` carrying the API error message.

changelog/+milestone_pops.fixed.md

@@ -1 +1 @@
-Fixed `get_milestones`/`get_milestone` crashing on API payloads missing optional keys
+Fixed {py:func}`github.get_milestones <saltext.github.modules.github.get_milestones>` / {py:func}`github.get_milestone <saltext.github.modules.github.get_milestone>` crashing on API payloads missing optional keys

changelog/+pages.added.md

@@ -0,0 +1 @@
+Added management of GitHub Pages sites ({py:func}`github_repo.get_pages <saltext.github.modules.github_repo.get_pages>`/{py:func}`setup_pages <saltext.github.modules.github_repo.setup_pages>`/{py:func}`update_pages <saltext.github.modules.github_repo.update_pages>`/{py:func}`remove_pages <saltext.github.modules.github_repo.remove_pages>` and the {py:func}`github_repo.pages_present <saltext.github.states.github_repo.pages_present>`/{py:func}`pages_absent <saltext.github.states.github_repo.pages_absent>` states)

changelog/+remove_repo_missing.fixed.md

@@ -1 +1 @@
-Fixed `remove_repo` raising an exception instead of returning `False` for nonexistent repositories
+Fixed {py:func}`github.remove_repo <saltext.github.modules.github.remove_repo>` raising an exception instead of returning `False` for nonexistent repositories

changelog/+repo_present_profile.fixed.md

@@ -1 +1 @@
-Fixed `repo_present` not passing the configured profile when creating repositories
+Fixed {py:func}`github.repo_present <saltext.github.states.github.repo_present>` not passing the configured profile when creating repositories

changelog/+repo_present_team_add_comment.fixed.md

@@ -1 +1 @@
-Fixed ``repo_present`` reporting a failed team *removal* when *adding* a repository to a team failed.
+Fixed {py:func}`github.repo_present <saltext.github.states.github.repo_present>` reporting a failed team *removal* when *adding* a repository to a team failed.

changelog/+ruleset_absent_delete_failure.fixed.md

@@ -1 +1 @@
-Fixed ``ruleset_absent`` reporting success when the ruleset could not be deleted. The module function returns a truthy error dict on failure, which was mistaken for success, and the failure result was subsequently overwritten by the "does not exist" fallback.
+Fixed {py:func}`github.ruleset_absent <saltext.github.states.github.ruleset_absent>` reporting success when the ruleset could not be deleted. The module function returns a truthy error dict on failure, which was mistaken for success, and the failure result was subsequently overwritten by the "does not exist" fallback.

changelog/+ruleset_states.fixed.md

@@ -1 +1 @@
-Fixed `ruleset_present` drift detection, which compared server-populated fields and iterated the wrong parameter set, and made the ruleset states report forecast changes in test mode
+Fixed {py:func}`github.ruleset_present <saltext.github.states.github.ruleset_present>` drift detection, which compared server-populated fields and iterated the wrong parameter set, and made the ruleset states report forecast changes in test mode

changelog/+scoped_modules.added.md

@@ -0,0 +1 @@
+Added scoped {py:mod}`github_org <saltext.github.modules.github_org>` and {py:mod}`github_repo <saltext.github.modules.github_repo>` execution and state modules, which replace the organization- and repository-related functionality of the monolithic `github` modules. Unlike the legacy functions, they raise errors instead of logging them and returning `False`. Collections with a unique natural key (repos, teams, team repos, labels, environments, Actions secrets) are returned as name-keyed mappings, id-addressed ones (issues, PRs, milestones, rulesets, deploy keys) as lists. All collection outputs can be reduced to specific fields via the `fields` argument. The new `github_org.team_present` state manages members as a simple list and drops the legacy per-team MFA enforcement options - require 2FA org-wide in the GitHub organization settings instead

changelog/+single_http_stack.changed.md

@@ -1 +1 @@
-All API calls are now routed through the PyGithub client, honoring the configured `api_url`, authentication and retry handling uniformly
+All API calls are now routed through the PyGithub client, honoring the configured {ghconf}`api_url`, authentication and retry handling uniformly

changelog/+structured_changes.added.md

@@ -0,0 +1 @@
+The new {py:mod}`github_org <saltext.github.states.github_org>` and {py:mod}`github_repo <saltext.github.states.github_repo>` states report machine-readable `changes` dictionaries (`created`/`deleted`/`updated` entity names, `old`/`new` setting mappings and `*_added`/`*_removed` name lists) instead of prose

changelog/+team_present_members.fixed.md

@@ -1 +1 @@
-Fixed `team_present` crashing when managing team members
+Fixed {py:func}`github.team_present <saltext.github.states.github.team_present>` crashing when managing team members

changelog/+testmode_projected_changes.fixed.md

@@ -1 +1 @@
-All states now report the projected changes in test mode, matching the changes reported on actual application. Exception: ``team_present`` does not project member/repo changes for teams that do not exist yet.
+All states now report the projected changes in test mode, matching the changes reported on actual application.

changelog/+user_owned_repos.added.md

@@ -0,0 +1 @@
+The new modules support repositories of any owner. Profiles take an {ghconf}`owner` (organization or user; preferred over the legacy `org_name` alias), which defaults to the token's user when unset. Repository listing and creation live on the `github_repo` module (`list`/`create`), and all of its functions and states as well as all functions of the (now strictly organization-scoped) `github_org` module accept a per-call `owner` override, so repositories, teams, members and rulesets of foreign organizations can be managed as well. Due to GitHub API limitations, repository creation is only supported for organizations and the authenticated user, private repositories of other users are not listable, tokens without an associated user account (e.g. GitHub App installation tokens) require an explicit `owner` and teams always belong to an organization

changelog/+utils-refactor.changed.md

@@ -1 +1 @@
-Refactored the GitHub API interaction layer into reusable per-entity modules below `saltext.github.utils.gh`. These raise `GitHubApiError`/`GitHubNotFoundError` (subclasses of `CommandExecutionError`) instead of returning error indicators. Existing execution module functions behave as before, except that unhandled API errors now surface as the above exceptions instead of raw PyGithub ones.
+Refactored the GitHub API interaction layer into reusable per-entity modules below {py:mod}`saltext.github.utils.gh`. These raise {py:class}`GitHubApiError <saltext.github.utils.gh.exceptions.GitHubApiError>`/{py:class}`GitHubNotFoundError <saltext.github.utils.gh.exceptions.GitHubNotFoundError>` (subclasses of {py:class}`CommandExecutionError <salt.exceptions.CommandExecutionError>`) instead of returning error indicators. Existing execution module functions behave as before, except that unhandled API errors now surface as the above exceptions instead of raw PyGithub ones.

changelog/+workflow_permissions.added.md

@@ -0,0 +1 @@
+Added management of default workflow permissions for the `GITHUB_TOKEN` ({py:func}`github_repo.get_workflow_permissions <saltext.github.modules.github_repo.get_workflow_permissions>`/{py:func}`set_workflow_permissions <saltext.github.modules.github_repo.set_workflow_permissions>` and the {py:func}`github_repo.workflow_permissions_managed <saltext.github.states.github_repo.workflow_permissions_managed>` state)

docs/_ext/ghdomain.py

@@ -0,0 +1,12 @@
+"""
+Allows to link configuration values using :ghconf:`config_val`.
+"""
+
+
+def setup(app):
+    app.add_crossref_type(
+        directivename="ghconf",
+        rolename="ghconf",
+        indextemplate="single: configuration; %s",
+    )
+    return {"parallel_read_safe": True, "parallel_write_safe": True}

docs/conf.py

@@ -93,6 +93,7 @@
     "sphinx_copybutton",
     "sphinxcontrib.spelling",
     "saltdomain",
+    "ghdomain",
     "sphinxcontrib.towncrier.ext",
     "myst_parser",
     "sphinx_inline_tabs",

docs/index.rst

@@ -1,14 +1,27 @@
 ``saltext-github``: Integrate Salt with GitHub
 ==============================================
 
-Salt Extension for interacting with GitHub
+Salt Extension for interacting with GitHub:
+
+* Manage organization members, teams and organization rulesets via the
+  :py:mod:`github_org <saltext.github.modules.github_org>` execution and
+  state modules.
+* List, create and manage organization- or user-owned repositories –
+  including their settings, teams, rulesets, deploy keys, Actions secrets
+  and workflow permissions, environments, labels and Pages sites – and
+  query their issues, milestones and pull requests via the
+  :py:mod:`github_repo <saltext.github.modules.github_repo>` execution
+  and state modules.
+* Works against GitHub Enterprise Server instances via the
+  :ghconf:`api_url` profile parameter.
 
 .. toctree::
   :maxdepth: 2
   :caption: Guides
   :hidden:
 
   topics/installation
+  topics/configuration
 
 .. toctree::
   :maxdepth: 2

docs/ref/modules/index.rst

@@ -10,3 +10,5 @@ _________________
     :toctree:
 
     github
+    github_org
+    github_repo

docs/ref/modules/saltext.github.modules.github_org.rst

@@ -0,0 +1,5 @@
+``github_org``
+==============
+
+.. automodule:: saltext.github.modules.github_org
+    :members:

docs/ref/modules/saltext.github.modules.github_repo.rst

@@ -0,0 +1,5 @@
+``github_repo``
+===============
+
+.. automodule:: saltext.github.modules.github_repo
+    :members:

docs/ref/states/index.rst

@@ -10,3 +10,5 @@ _____________
     :toctree:
 
     github
+    github_org
+    github_repo

docs/ref/states/saltext.github.states.github_org.rst

@@ -0,0 +1,5 @@
+``github_org``
+==============
+
+.. automodule:: saltext.github.states.github_org
+    :members:

docs/ref/states/saltext.github.states.github_repo.rst

@@ -0,0 +1,5 @@
+``github_repo``
+===============
+
+.. automodule:: saltext.github.states.github_repo
+    :members:

docs/ref/utils/index.rst

@@ -11,12 +11,18 @@ _________
 
     utils
     utils.gh
+    utils.gh.actions
     utils.gh.client
+    utils.gh.deploy_keys
+    utils.gh.environments
     utils.gh.exceptions
     utils.gh.issues
+    utils.gh.labels
+    utils.gh.members
     utils.gh.milestones
+    utils.gh.pages
+    utils.gh.profile
     utils.gh.pulls
     utils.gh.repos
     utils.gh.rulesets
     utils.gh.teams
-    utils.gh.users

docs/ref/utils/saltext.github.utils.gh.actions.rst

@@ -0,0 +1,5 @@
+saltext.github.utils.gh.actions
+===============================
+
+.. automodule:: saltext.github.utils.gh.actions
+    :members:

docs/ref/utils/saltext.github.utils.gh.deploy_keys.rst

@@ -0,0 +1,5 @@
+saltext.github.utils.gh.deploy_keys
+===================================
+
+.. automodule:: saltext.github.utils.gh.deploy_keys
+    :members:

docs/ref/utils/saltext.github.utils.gh.environments.rst

@@ -0,0 +1,5 @@
+saltext.github.utils.gh.environments
+====================================
+
+.. automodule:: saltext.github.utils.gh.environments
+    :members:

docs/ref/utils/saltext.github.utils.gh.labels.rst

@@ -0,0 +1,5 @@
+saltext.github.utils.gh.labels
+==============================
+
+.. automodule:: saltext.github.utils.gh.labels
+    :members:

docs/ref/utils/saltext.github.utils.gh.members.rst

@@ -0,0 +1,5 @@
+saltext.github.utils.gh.members
+===============================
+
+.. automodule:: saltext.github.utils.gh.members
+    :members:

docs/ref/utils/saltext.github.utils.gh.pages.rst

@@ -0,0 +1,5 @@
+saltext.github.utils.gh.pages
+=============================
+
+.. automodule:: saltext.github.utils.gh.pages
+    :members:

docs/ref/utils/saltext.github.utils.gh.profile.rst

@@ -0,0 +1,5 @@
+saltext.github.utils.gh.profile
+===============================
+
+.. automodule:: saltext.github.utils.gh.profile
+    :members:

docs/topics/configuration.md

@@ -0,0 +1,80 @@
+(github-configuration)=
+# Configuration
+
+All modules provided by this extension read their configuration from
+*profiles*. A profile is a mapping under a top-level key in the minion
+configuration, minion pillar or master configuration. Functions and
+states use the profile named `github` by default and accept a
+`profile` argument to select a different one.
+
+## Profile parameters
+
+:::{ghconf} token
+:::
+`token`
+: Required. Access token to authenticate with.
+
+:::{ghconf} owner
+:::
+`owner`
+: Default owner (organization or user) whose resources are managed.
+  Defaults to the token's user, so organization management and tokens
+  without an associated user account (e.g. GitHub App installation
+  tokens) require it to be set. `org_name` is supported as a legacy
+  alias.
+
+  :::{versionadded} 1.1.0
+  Renamed from `org_name`. The new {py:mod}`github_repo <saltext.github.modules.github_repo>`
+  modules can manage user repositories in addition to organization ones.
+  :::
+
+:::{ghconf} repo_name
+:::
+`repo_name`
+: The default repository the `github_repo` functions and states operate
+  on when no `repo_name` is passed.
+
+:::{ghconf} allow_repo_privacy_changes
+:::
+`allow_repo_privacy_changes`
+: Allow automated repository privacy modifications. It can be dangerous
+  to change the privacy of a repository in an automated way, hence this
+  defaults to false.
+
+:::{ghconf} api_url
+:::
+`api_url`
+: Base URL of the GitHub API. Set this when targeting a GitHub
+  Enterprise Server instance, e.g. `https://github.example.com/api/v3`.
+  Defaults to `https://api.github.com`.
+
+## Multiple profiles
+
+Any number of profiles can be defined and selected per call:
+
+```yaml
+github:
+  token: abc1234
+  owner: my_organization
+
+my_user:
+  token: def5678
+```
+
+```bash
+salt-call github_repo.list profile=my_user
+```
+
+## Secret management
+
+Profile values containing [SDB URIs](https://docs.saltproject.io/en/latest/topics/sdb/index.html)
+are rendered on access, which also works in pillar-sourced profiles:
+
+```yaml
+# Requires a corresponding SDB profile in the minion configuration, e.g.
+#   osenv:
+#     driver: env
+github:
+  token: sdb://osenv/GITHUB_TOKEN
+  owner: my_organization
+```

pyproject.toml

@@ -39,6 +39,8 @@ dynamic = ["version"]
 dependencies = [
     "salt>=3006",
     "PyGithub>=2.2",
+    # Used directly for Actions secret encryption (also a PyGithub dependency)
+    "pynacl>=1.4",
 ]
 
 [project.readme]