Changelog

The changelog format is based on Keep a Changelog.

This project uses Semantic Versioning - MAJOR.MINOR.PATCH

1.0.1.dev44+gae9ff589d (2026-10-16)

Removed

  • Removed the unauthenticated get_user_pubkeys helper from saltext.github.utils.github. It ignored the configured api_url, relied on salt.utils.http and was not exposed in any module

Deprecated

Changed

  • All API calls are now routed through the PyGithub client, honoring the configured api_url, authentication and retry handling uniformly

  • Exception tracebacks are only logged at debug loglevel now

  • 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.

  • The execution module now exclusively relies on public PyGithub APIs instead of internal ones (_requester, _identity, _rawData, manual PaginatedList construction). It also avoids deprecated API paths (/teams/{team_id}/...) by addressing teams by slug and checking team memberships via the memberships endpoints. The minimum supported PyGithub version is now 2.2.

Fixed

  • All states now report the projected changes in test mode, matching the changes reported on actual application.

  • Fixed a PyGithub deprecation warning by migrating to github.Auth.Token authentication

  • Fixed compound states (github_repo.present, github_org.team_present, environment management) reporting no changes when failing after some changes had already been applied

  • Fixed legacy github state functions rendering a traceback instead of a failed state when an unexpected CommandExecutionError was raised, e.g. caused by missing profile configuration

  • Fixed github.add_team refreshing the team cache using the default profile instead of the configured one

  • Fixed github.get_issues, github.get_issue_comments, github.get_prs and github.get_milestones crashing with an AttributeError when the API returned an error. They now raise a CommandExecutionError carrying the API error message.

  • Fixed github.get_milestones / github.get_milestone crashing on API payloads missing optional keys

  • Fixed github.is_team_member crashing with a TypeError when the team does not exist. It now returns False.

  • Fixed github.remove_repo raising an exception instead of returning False for nonexistent repositories

  • Fixed github.repo_present not passing the configured profile when creating repositories

  • Fixed github.repo_present reporting a failed team removal when adding a repository to a team failed.

  • Fixed 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.

  • Fixed 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

  • Fixed github.team_present crashing when managing team members

Added

  • Added default_branch to github_repo.update and the github_repo.present state

  • Added github.query for making direct calls to arbitrary GitHub API endpoints, transparently following pagination

  • Added github.rate_limit for querying the API rate limit status of the profile’s token

  • Added github.revoke_app_token for immediately revoking a GitHub App profile’s current installation access token (otherwise valid for one hour), e.g. as the last step of an ephemeral CI run

  • Added github_user.list_keys for listing the verified public SSH keys of any user, defaulting to the token’s user, e.g. for use with the ssh_auth state module

  • Added a persistent cross-process per-connection cache (on by default, opt out via the cache profile parameter), serving token/account identities and file-based custom resource grains (validated against each repository’s pushed_at timestamp) without refetching, e.g. across salt-call --local invocations

  • Added composite states that generate an SSH keypair in memory via the ssh_pki module and distribute the public half as a deploy key and the private half as an Actions secret, with optional rotation (github_repo.deploy_key_actions_present and the resource-type deploy_key.actions_present)

  • Added custom repository resource grains sourced from in-repo YAML/JSON files (e.g. copier answers) via the grains_files resource declaration key, with per-namespace key filtering, renaming and optional merging into the root grains

  • Added management of GitHub Pages sites (github_repo.get_pages/setup_pages/update_pages/remove_pages and the github_repo.pages_present/pages_absent states)

  • Added management of default workflow permissions for the GITHUB_TOKEN (github_repo.get_workflow_permissions/set_workflow_permissions and the github_repo.workflow_permissions_managed state)

  • Added management of repository Actions secrets, encrypted client-side to the repository public key (github_repo.list_actions_secrets/get_actions_secret/set_actions_secret/remove_actions_secret and the github_repo.actions_secret_present/actions_secret_absent states)

  • Added management of repository deploy keys (github_repo.list_deploy_keys/get_deploy_key/add_deploy_key/remove_deploy_key and the github_repo.deploy_key_present/deploy_key_absent states)

  • Added management of repository environments, including deployment branch policies (github_repo.list_environments/get_environment/set_environment/remove_environment/list_deployment_branch_policies/add_deployment_branch_policy/remove_deployment_branch_policy and the github_repo.environment_present/environment_absent states)

  • Added management of repository labels (github_repo.list_labels/get_label/add_label/edit_label/remove_label and the github_repo.label_present/label_absent states)

  • Added native GitHub App authentication via the app_id, private_key/private_key_path and optional installation_id and permissions profile parameters. Installation access tokens are minted and refreshed automatically (optionally restricted to a subset of the app’s granted permissions), the app’s installation on owner is discovered when not pinned, and the connection identity derives from the app’s identity instead of its short-lived tokens, keeping the persistent cache effective across token rotation (e.g. in CI)

  • Added scoped github_org and 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

  • Added the optional api_url profile option for targeting GitHub Enterprise Server instances

  • Added the github Salt resource type for Salt 3008.3+, exposing each GitHub repository as an individually targetable resource with per-repository grains and repository-implicit execution and state modules

  • Added github.account_info for looking up the public profile of any user or organization account, defaulting to the profile’s owner

  • Added github_org.info for looking up the public profile of an organization account, defaulting to the profile’s owner and failing on users

  • Added github_user.info for looking up the public profile of a user account, defaulting to the token’s user and failing on organizations

  • Extended repository information (github_repo.info/github_repo.list, but also affects the legacy github.get_repo_info and the resource grains) with visibility, archived, disabled, is_template, license, topics, custom_properties, clone_url, ssh_url, created_at, has_discussions, has_pages and has_projects (info additionally carries updated_at)

  • Profile configuration values containing SDB URIs (e.g. token: sdb://osenv/GITHUB_TOKEN) are now rendered on access. Salt itself only renders them inside the minion/master configuration during startup, so this makes them work in pillar-sourced profiles as well.

  • The new modules support repositories of any owner. Profiles take an 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

  • The new github_org and 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

v1.0.0 (2024-08-13)

Initial release of saltext-github. This release mostly tracks the functionality in the core Salt code base as of version 3007.1.

Added

  • Add CRUD funtionality for Github rulesets #11