GitHub repository secrets

The GitHub repository sync destination allows Vault to safely synchronize secrets as GitHub repository action secrets. This is a low footprint option that enables your applications to benefit from Vault-managed secrets without requiring them to connect directly with Vault. This guide walks you through the configuration process.

Prerequisites:

• Ability to read or create KVv2 secrets
• Ability to create GitHub fine-grained or personal tokens with access to modify repository secrets
• Ability to create sync destinations and associations on your Vault server

Setup

1. To get started with syncing Vault secrets to your GitHub repository, you will need an access token with access to the repository you want to manage secrets for and write permissions on the repository secrets.

2. Configure a sync destination with the access token obtained in the previous steps.

   $ vault write sys/sync/destinations/gh/my-dest \
       access_token="$ACCESS_TOKEN" \
       repository_owner="$OWNER" \
       repository_name="$NAME"
   

   Copy

   Output:

   Key                   Value
   ---                   -----
   connection_details    map[access_token:***** repository_owner:<owner> repository_name:<name>]
   name                  my-dest
   type                  gh
   

Usage

1. If you do not already have a KVv2 secret to sync, mount a new KVv2 secrets engine.

   $ vault secrets enable -path=my-kv kv-v2
   

   Copy

   Output:

   Success! Enabled the kv-v2 secrets engine at: my-kv/
   

2. Create secrets you wish to sync with a target GitHub repository.

   $ vault kv put -mount='my-kv' my-secret foo=bar
   

   Copy

   Output:

   ==== Secret Path ====
   my-kv/data/my-secret
   
   ======= Metadata =======
   Key                Value
   ---                -----
   created_time       <timestamp>
   custom_metadata    <nil>
   deletion_time      n/a
   destroyed          false
   version            1
   

3. Create an association between your GitHub repository destination and the secret to synchronize.

   $ vault write sys/sync/destinations/gh/my-dest/associations/set \
       mount=my-kv \
       secret_name=my-secret
   

   Copy

   Output:

   Key                   Value
   ---                   -----
   associated_secrets    map[kv_1234/my-secret:map[accessor:kv_1234 secret_name:my-secret sync_status:SYNCED updated_at:<timestamp>>]]
   store_name            my-dest
   store_type            gh
   

4. Navigate to your GitHub repository settings to confirm your secret was successfully created.

Moving forward, any modification on the Vault secret will be propagated in near real time to its GitHub repository secrets counterpart. Creating a new secret version in Vault will create a new version in GitHub. Deleting the secret or the association in Vault will delete the secret in GitHub as well.

API

Please see the secrets sync API for more details.