Manage Administrative Repository Settings from Pull-Requests

Description

Manage all Github repo settings from a YAML file, enabling greater change control, transparency, and auditability.

Usage

Manage Administrative Repository Settings from within a repository - via a YAML file!

Why would you want to do this?

• Adhere to principal of least-privilegas for developers and other contributors.
  • Allows contributors without repo admin privileges to propose admin changes for review by repo owners and maintainers
• Enables contributors without admin rights ability to maintain variables, secrets, deployment environments, etc.
  • GitHub restricts many of these items to the repo admin role, but granting this role to many people runs in direct conflict to requirements by audit teams, generally accepted best practices for governance, or corporate standards and requirements
• Ability to centralize maintenance of repo configurations and permission standards
  • Use of .github repo or some other centralized repo
    • Make directories containing standardized example workflows and use the file-copy to maintain all CI/CD workflows matching a given regex pattern for repo names
    • Similary, add a settings.yml file to that directory to standardize variables, secrets, access control lists, etc.

What Items You May Manage:

• repos configure external repos
• repo settings
• branch protection(s)
• labels
• secrets
• variables
• deployment environments
• contributors e.g. access control lists or ACL management
• files such as CI/CD, codeowners, issue and pull-request templates, etc.

See examples/settings.yml for an example config file. The schemas for this file are in repo_manager.schemas.

File Management -- Experimental

File management can copy files from your local environment to a target repo, copy files from one location to another in the target repo, move files in the target repo, and delete files in the target repo.

File operations are performed using the Github BLOB API and your PAT. Each file operation is a separate commit.

This feature is helpful to keep workflows or settings file in sync from a central repo to many repos.

Example workflow

name: Run Repo Manager
on: [workflow_dispatch]
jobs:
  repo-manager:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      uses: actions/checkout@v4.1.6

    - name: Run RepoManager
      # you should always reference a version tag to ensure that your use of an action never changes until you update it
      uses: actuarysailor/gha-repo-manager@v2.0.0
      with:
        # Apply your settings to the repo, can also be check to just check repo settings vs your file or validate, to validate your
        # file is valid
        action: apply
        settings_file: .github/settings.yml
        # need a PAT that can edit repo settings
        # note, some settings may require additional permissions; see comments in examples/settings.yml for details
        token: ${{ secrets.GITHUB_PAT }}

Inputs

name	description	required	default
action	What action to take with this action. One of validate, check, or apply. Validate will validate your settings file, but not touch your repo. Check will check your repo with your settings file and output a report of any drift. Apply will apply the settings in your settings file to your repo	false	check
settings_file	What yaml file to use as your settings. This is local to runner running this action.	false	.github/settings.yml
repo	What repo to perform this action on. Default is self, as in the repo this action is running in	false	self
github_server_url	Set a custom github server url for github api operations. Useful if you're running on GHE. Will try to autodiscover from env.GITHUBSERVERURL if left at default	false	""
token	What github token to use with this action (one of token or app_id is required).	false	""
app_id	What github app id to use with this action (one of token or app_id is required).	false	""
private_key	What github app private key to use with this action (required if using an app_id to authenticate).	false	""
fail_on_diff	Fail the action if the repo settings differ from the settings file. Default is false. Note, this only applies if the action is set to 'check'	false	false

Outputs

name	description
result	Result of the action
diff	Diff of this action, dumped to a json string

Runs

This action is a docker action.

Contributors

Please see our Contribution Guide for more info on how you can contribute. All contributors and participants in this repo must follow our Code of Conduct.

Andrew 🤔 ⚠️ 💻

shiro 🐛 💻