mirrors/vault
1
0
Fork 0
mirror of https://github.com/hashicorp/vault.git synced 2026-05-09 14:26:24 +02:00
Code Issues Projects Releases Wiki Activity

Add docs for github sync environment secrets (#28175)

Browse Source 
---------

Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com>
This commit is contained in:
Robert 2024-09-05 16:11:01 -05:00 committed by GitHub
parent b682a79551
commit 3bda80649f
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 80 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
website/content/api-docs/system/secrets-sync.mdx
View File

@ -428,8 +428,10 @@ This endpoint creates a destination to synchronize action secrets with a GitHub
Use `access_token` as an alternative to authenticating with a GitHub app.
- `app_name` `(string: <optional>)` - The name of a GitHub App configured in Vault to use for
authentication. Use `app_name` and `installation_id` as an alternative to
authenticating with an access token.
authentication. You can use `app_name` with `installation_id`
as authentication instead of an access token. Refer to the
[Configure a custom GitHub app section](/vault/api-docs/system/secrets-sync#configure-a-custom-github-app)
of the Secrets sync API docs for more information.
- `installation_id` `(string: <optional>)` - The installation ID of the GitHub
app to use for authentication. Required when using `app_name` for
@ -439,6 +441,10 @@ This endpoint creates a destination to synchronize action secrets with a GitHub
- `repository_name` `(string: <required>)` - Name of the repository. For example, if a repository is located at https://github.com/hashicorp/vault.git the name is vault.
- `environment_name` `(string: '')` - The name of a GitHub environment
within the repo specified by `repository_name`. By default, secrets are
global to the targeted repository.
- `secret_name_template` `(string: "")` - Template to use when generating the secret names on the external system.
The default template yields names like `VAULT_KV_1234_MY_SECRET`. See [this documentation](/vault/docs/sync#name-template) for more details.
@ -850,7 +856,8 @@ custom GitHub application for syncing secrets with GitHub repositories.
### Parameters
- `name` `(string: <required>)` - Specifies a custom name for the GitHub
application that is used when configuring the destination. Although this can be any name, we recommend using the same app name configured in GitHub.
application used when configuring a sync destination. We recommend using the same
app name configured in GitHub.
- `app_id` `(string: <required>)` - Specifies the GitHub application ID, provided by GitHub.

4
website/content/docs/deprecation/index.mdx
View File

@ -43,6 +43,8 @@ or raise a ticket with your support team.
@include 'deprecation/vault-agent-api-proxy.mdx'
@include 'deprecation/aws-field-change.mdx'
@include 'deprecation/centrify-auth-method.mdx'
</Tab>
@ -50,8 +52,6 @@ or raise a ticket with your support team.
@include 'deprecation/duplicative-docker-images.mdx'
@include 'deprecation/aws-field-change.mdx'
@include 'deprecation/azure-password-policy.mdx'
</Tab>

95
website/content/docs/sync/github.mdx
View File

@ -4,9 +4,9 @@ page_title: GitHub - Secrets Sync Destination
description: The GitHub destination syncs secrets from Vault to GitHub.
---
# GitHub repository secrets
# GitHub actions secrets
The GitHub repository sync destination allows Vault to safely synchronize secrets as GitHub repository action secrets.
The GitHub actions sync destination allows Vault to safely synchronize secrets as GitHub repository or environment 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.
@ -17,7 +17,7 @@ Prerequisites:
## Setup
1. To get started with syncing Vault secrets to your GitHub repository, you will need a configured [GitHub application](#github-application) or an
1. To get started with syncing Vault secrets to your GitHub, you will need a configured [GitHub application](#github-application) or an
[access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
which has access to the repository you want to manage secrets for and write permissions on the repository's actions secrets.
In the list of GitHub permissions, this is simply called "Secrets". Choosing this will automatically include read-only Metadata.
@ -27,30 +27,65 @@ Prerequisites:
GitHub applications are long-lived and do not expire. Using a GitHub application for authentication is preferred over using a personal access token.
</Warning>
If you decide to go with an access token, here's how you can configure a sync destination:
Use `vault write` to configure a repository sync destination with an access token:
```shell-session
$ vault write sys/sync/destinations/gh/my-dest \
access_token="$ACCESS_TOKEN" \
repository_owner="$OWNER" \
repository_name="$NAME"
$ vault write sys/sync/destinations/gh/DESTINATION_NAME \
access_token="GITHUB_ACCESS_TOKEN" \
repository_owner="GITHUB_OWNER_NAME" \
repository_name="GITHUB_REPO_NAME"
```
**Output:**
For example:
<CodeBlockConfig hideClipboard>
```
$ vault write sys/sync/destinations/gh/hcrepo-sandbox \
access_token="github_pat_11ABC000000000000000000000DEF" \
repository_owner="hashicorp" \
repository_name="hcrepo"
```plaintext
Key Value
--- -----
connection_details map[access_token:***** repository_owner:<owner> repository_name:<name>]
name my-dest
connection_details map[access_token:***** repository_owner:hashicorp repository_name:hcrepo]
name hcrepo-sandbox
type gh
```
</CodeBlockConfig>
Use `vault write` to configure an environment sync destination:
```shell-session
$ vault write sys/sync/destinations/gh/DESTINATION_NAME \
access_token="GITHUB_ACCESS_TOKEN" \
repository_owner="GITHUB_OWNER_NAME" \
repository_name="GITHUB_REPO_NAME" \
environment_name="GITHUB_ENVIRONMENT_NAME"
```
For example:
<CodeBlockConfig hideClipboard>
```
$ vault write sys/sync/destinations/gh/hcrepo-sandbox \
access_token="github_pat_11ABC000000000000000000000DEF" \
repository_owner="hashicorp" \
repository_name="hcrepo" \
environment_name="sandbox"
Key Value
--- -----
connection_details map[access_token:***** environment_name:sandbox repository_owner:hashicorp repository_name:hcrepo]
name hcrepo-sandbox
type gh
```
</CodeBlockConfig>
## Usage
1. If you do not already have a KVv2 secret to sync, mount a new KVv2 secrets engine.
@ -72,7 +107,7 @@ If you decide to go with an access token, here's how you can configure a sync de
1. Create secrets you wish to sync with a target GitHub repository for Actions.
```shell-session
$ vault kv put -mount='my-kv' my-secret foo='bar'
$ vault kv put -mount='my-kv' my-secret key1='val1' key2='val2'
```
**Output:**
@ -99,8 +134,8 @@ If you decide to go with an access token, here's how you can configure a sync de
```shell-session
$ vault write sys/sync/destinations/gh/my-dest/associations/set \
mount=my-kv \
secret_name=my-secret
mount='my-kv' \
secret_name='my-secret'
```
**Output:**
@ -119,7 +154,7 @@ If you decide to go with an access token, here's how you can configure a sync de
1. 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
Moving forward, any modification on the Vault secret will be propagated in near-real time to its GitHub 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.
@ -127,9 +162,15 @@ or the association in Vault will delete the secret in GitHub as well.
<Note>
GitHub only supports single value secrets, so KVv2 secrets from Vault will be stored as a JSON string.
In the example above, the value for secret "my-secret" will be synced to GitHub as the JSON string `{"foo":"bar"}` if the
destination is configured to use the `secret-path` [granularity level](/vault/docs/sync#granularity).
GitHub only supports single-value secrets, and Vault syncs secrets differently
depending on whether you have configured
`secret-key` or `secret-path` [granularity](/vault/docs/sync#granularity):
- `secret-key` granularity splits KVv2 secrets from Vault into key-value pairs
and stores the pairs as distinct entries in GitHub secrets. For example,
`secrets.key1="val1"` and `secrets.key2="val2"`.
- `secret-path` granularity stores secrets as a single JSON string that contains
all of the associated key-value pairs. For example, `{"key1":"val1", "key2":"val2"}`.
</Note>
@ -177,11 +218,11 @@ Then add your GitHub application to your Vault instance.
To use your GitHub application with Vault:
- the application must have permission to read and write secrets.
- you must generate a private key for the application on GitHub.
- the application must be installed on the repository you want to sync secrets with.
- you must know the application ID assigned by GitHub.
- you must know the installation ID assigned by GitHub.
- The application must have permission to read and write secrets.
- You must generate a private key for the application on GitHub.
- The application must be installed on the repository you want to sync secrets with.
- You must know the application ID assigned by GitHub.
- You must know the installation ID assigned by GitHub.
Callback, redirect URLs, and webhooks are not required at this time.
@ -194,7 +235,7 @@ information:
```shell-session
$ vault write sys/sync/github-apps/<APP_NAME> \
app_id=<APP_ID> \
private_key=<PATH_TO_PRIVATE_KEY>
private_key=@/path/to/private/key
Key Value
--- -----