From 3bda80649f786b3fc171807930dc596e0df4b117 Mon Sep 17 00:00:00 2001 From: Robert <17119716+robmonte@users.noreply.github.com> Date: Thu, 5 Sep 2024 16:11:01 -0500 Subject: [PATCH] Add docs for github sync environment secrets (#28175) --------- Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com> --- .../content/api-docs/system/secrets-sync.mdx | 13 ++- website/content/docs/deprecation/index.mdx | 4 +- website/content/docs/sync/github.mdx | 95 +++++++++++++------ 3 files changed, 80 insertions(+), 32 deletions(-) diff --git a/website/content/api-docs/system/secrets-sync.mdx b/website/content/api-docs/system/secrets-sync.mdx index aeae92edf2..25c822a2d8 100644 --- a/website/content/api-docs/system/secrets-sync.mdx +++ b/website/content/api-docs/system/secrets-sync.mdx @@ -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: )` - 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: )` - 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: )` - 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: )` - 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: )` - Specifies the GitHub application ID, provided by GitHub. diff --git a/website/content/docs/deprecation/index.mdx b/website/content/docs/deprecation/index.mdx index a29f1d13a9..49c967806e 100644 --- a/website/content/docs/deprecation/index.mdx +++ b/website/content/docs/deprecation/index.mdx @@ -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' @@ -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' diff --git a/website/content/docs/sync/github.mdx b/website/content/docs/sync/github.mdx index 78c6f80b66..6632a9176b 100644 --- a/website/content/docs/sync/github.mdx +++ b/website/content/docs/sync/github.mdx @@ -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. - -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: + + ``` + $ 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: repository_name:] - name my-dest + connection_details map[access_token:***** repository_owner:hashicorp repository_name:hcrepo] + name hcrepo-sandbox type gh ``` + 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: + + + + ``` + $ 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 + ``` + + + + ## 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. -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"}`. @@ -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_id= \ - private_key= + private_key=@/path/to/private/key Key Value --- -----