gh-env-manager 0.4.1

A CLI tool to update GitHub Actions secrets and variables from a YAML file

GitHub Environment Manager - gh_env_manager

This tool is in early development - use with care and expect to find bugs, When you do, please raise issues to help guide development 😊

GitHub Environment Manager helps you maintain GitHub Actions Secrets and Variables across your repositories, and environments within them. You provide your target state in the form of a YAML file - the desired Secrets and Variables that your repositories and their environments should contain - and the tool does the rest.

Installation

pip install gh-env-manager

---

Quick start to update entities in your repositories

gh-env-manager requires as an input a YAML file that describes the target state of your GitHub repository (or repositories) and its (their) Secrets and Variables. It does not create any repositories or environments for you - so every repository, and every environment within your repositories, that you add to the configuration must exist already. The tool maintains the entities - Secrets and Variables - within.

1. Install this tool with pip install gh-env-manager

2. Create a GitHub personal access token following this guide from GitHub

3. Create a YAML file that describes your target state, following the format below. You can also check the example used for tests.

   GH_SECRET_SYNC_KEY: <your GitHub personal access token>
   
   repositories:
     username/repositoryname: # e.g. Antvirf/gh-environment-manager 
       secrets:
         - YOUR_SECRET: "something"
       variables:
         - YOUR_VARIABLE: "something" 
       environments:
         dev: # assuming 'dev' environment exists in your repository
           secrets:
             - YOUR_DEV_SECRET: "something"
           variables:
             - YOUR_DEV_VARIABLE: "something"
   
     # you can add as many repositories as desired
     username/repositoryname: #...
       secrets:
         ...
       variables:
         ...
   

4. Run gh-env-manager fetch ./path_to_your_yaml_file to get current state of your repositories

5. Run gh-env-manager update ./path_to_your_yaml_file to push the contents of the YAML file to your repositories

   • By default, nothing is overwritten - if an entity exists already, it is NOT updated. Use the --overwrite flag to enable that behaviour.
   • By default, nothing is deleted - if your repository has an entity that is not in the YAML file, it is ignored. Use the --delete-nonexisting or --delete-nonexisting-without-prompt to delete any secret or variable from your repository that was missing from your input YAML file.

Usage

PATH_TO_FILE is always required for each command.

$ gh_env_manager [COMMANDS] PATH_TO_FILE [OPTIONS]

# examples
$ gh_env_manager read .env.yaml
$ gh_env_manager fetch .env.yaml
$ gh_env_manager update .env.yaml

# to overwrite existing entries
$ gh_env_manager update .env.yaml --overwrite 

# to delete any secret/variable missing from your YAML
$ gh_env_manager update .env.yaml --delete-nonexisting

# fully sync your repository with the contents of the yaml by updating all values, and deleting any that are not present
$ gh_env_manager update .env.yaml --overwrite --delete-nonexisting-without-prompt 

Commands

• read: Read given YAML file and output the interpreted contents.
• fetch: Fetch all secrets and all variables from the specific GitHub repositories provided in your environment YAML file.
• update: Update secrets and variables of the GitHub repositories using data from the provided YAML file. By default, existing secrets or variables are NOT overwritten. Try gh-env-manager update --help to view the available options.

Options for update

• -o, --overwrite: If enabled, overwrite existing secrets and values in GitHub to match the provided YAML file. [default: False]
• -d, --delete-nonexisting: If enabled, delete secrets and variables that are not found in the provided YAML file. [default: False]
• --delete-nonexisting-without-prompt: Applies the same commands as delete_nonexisting, but without prompting the user for confirmation. [default: False]

FAQ

1. Why do secrets sometimes state their value as None?
   1. GitHub Secrets API does NOT support fetching the value of a secret, and hence they are shown as None when data coming from GitHub is output.

Known missing features & potential roadmap items

• Support for GitHub Organizations (see API ref for org Variables, org Secrets)
  • Potentially support for scoped secrets and variables (ability to set visibility at repo level)