vault page title Upgrading to Vault 0 5 0 Guides layout docs actions you must take to facilitate a smooth upgrade path This page contains the full list of breaking changes for Vault 0 5 including Overview

Answer:
---
layout: docs
page_title: Upgrading to Vault 0.5.0 - Guides
description: |-
  This page contains the full list of breaking changes for Vault 0.5, including
  actions you must take to facilitate a smooth upgrade path.
---

# Overview

This page contains the list of breaking changes for Vault 0.5. Please read it
carefully.

Please note that these are changes to Vault itself. Client libraries maintained
by HashiCorp have been updated with support for these changes, but if you are
using community-supported libraries, you should ensure that they are ready for
Vault 0.5 before upgrading.

## Rekey requires nonce

Vault now generates a nonce when a rekey operation is started in order to
ensure that the operation cannot be hijacked. The nonce is output when the
rekey operation is started and when rekey status is requested.

The nonce must be provided as part of the request parameters when providing an
unseal key. The nonce can be communicated from the request initiator to unseal
key holders via side channels; the unseal key holders can then verify the nonce
(by providing it) when they submit their unseal key.

As a convenience, if using the CLI interactively to provide the unseal key, the
nonce will be displayed for verification but the user will not be required to
manually re-type it.

## `TTL` field in token lookup

Previously, the `ttl` field returned when calling `lookup` or `lookup-self` on
the token auth method displayed the TTL set at token creation. It
now displays the time remaining (in seconds) for the token's validity period.
The original behavior has been moved to a field named `creation_ttl`.

## Grace periods removed

Vault no longer uses grace periods internally for leases or token TTLs.
Previously these were set by backends and could differ greatly from one backend
to another, causing confusion. TTLs (the `lease_duration` field for a lease,
or, for a token lookup, the `ttl`) are now exact.

## `token-renew` CLI command

If the token given for renewal is the same as the token in use by the client,
the `renew-self` endpoint will be used in the API rather than the `renew`
endpoint. Since the `default` policy contains `auth/token/renew-self` this
makes it much more likely that the request will succeed rather than somewhat
confusingly failing due to a lack of permissions on `auth/token/renew`.

## `status` CLI command

The `status` CLI command now returns an exit code of `0` for an unsealed Vault
(as before), `2` for a sealed Vault, and `1` for an error. This keeps error
return codes consistent across commands.

## Transit upsertion behavior uses capabilities

Previously, attempting to encrypt with a key that did not exist would create a
key with default values. This was convenient but ultimately allowed a client to
potentially escape an ACL policy restriction, albeit without any dangerous
access. Now that Vault supports more granular capabilities in policies,
upsertion behavior is controlled by whether the client has the `create`
capability for the request (upsertion is allowed) or only the `update`
capability (upsertion is denied).

## etcd physical backend uses `sync`

The `etcd` physical backend now supports `sync` functionality and it is turned
on by default, which maps to the upstream library's default. It can be
disabled; see the configuration page for information.

## S3 physical backend prefers environment variables

The `s3` physical backend now prefers environment variables over configuration
file variables. This matches the behavior of the rest of the backends and of
Vault generally.

## Lease default and renewal handling

All backends now honor system and mount-specific default and maximum lease
times, except when specifically overridden by backend configuration or role
parameters, or when doing so would not make sense (e.g. AWS STS tokens cannot
have a lifetime of greater than 1 hour).

This allows for a _much_ more uniform approach to managing leases on both the
operational side and the user side, and removes much ambiguity and uncertainty
resulting from backend-hardcoded limits.

However, also this means that the leases generated by the backends may return
significantly different TTLs in 0.5 than in previous versions, unless they have
been preconfigured. You can use the `mount-tune` CLI command or the
`/sys/mounts/<mount point>/tune` endpoint to adjust default and max TTL
behavior for any mount. This is supported in 0.4, so you can perform this
tuning before upgrading.

The following list details the ways in which lease handling has changed
per-backend. In all cases the "mount TTL" means the mount-specific value for
default or max TTL; however, if no value is set on a given mount, the system
default/max values are used. This lists only the changes; any lease-issuing
or renew function not listed here behaves the same as in 0.4.

(As a refresher: the default TTL is the amount of time that the initial
lease/token is valid for before it must be renewed; the maximum TTL is the
amount of time a lease or token is valid for before it can no longer be renewed
and must be reissued. A mount can be more restrictive with its maximum TTL, but
cannot be less restrictive than the mount's maximum TTL.)

#### Credential (Auth) backends

- `github` – The renewal function now uses the backend's configured maximum
  TTL, if set; otherwise, the mount maximum TTL is used.
- `ldap` – The renewal function now uses the mount default TTL instead of always
  using one hour.
- `token` – Tokens can no longer be renewed forever; instead, they now honor the
  mount default/max TTL.
- `userpass` – The renew function now uses the backend's configured maximum TTL,
  if set; otherwise the mount maximum TTL is used.

#### Secrets engines

- `aws` – New IAM roles no longer always have a default TTL of one hour, instead
  honoring the configured default if available and the mount default TTL if not
  (renewal always used the configured values if available). STS tokens return a
  TTL corresponding to the lifetime of the token in AWS and cannot be renewed.
- `cassandra` – `lease_grace_period` has been removed since Vault no longer uses
  grace periods.
- `consul` – The mount default TTL is now used as the default TTL if there is no
  backend configuration parameter. Renewal now uses the mount default and
  maximum TTLs.
- `mysql` – The mount default TTL is now used as the default TTL if there is no
  backend configuration parameter.
- `postgresql` – The mount default TTL is now used as the default TTL if there
  is no backend configuration parameter. In addition, there is no longer any
  grace period with the time configured for password expiration within Postgres
  itself.

layout  docs page title  Upgrading to Vault 0 5 0   Guides description       This page contains the full list of breaking changes for Vault 0 5  including   actions you must take to facilitate a smooth upgrade path         Overview  This page contains the list of breaking changes for Vault 0 5  Please read it carefully   Please note that these are changes to Vault itself  Client libraries maintained by HashiCorp have been updated with support for these changes  but if you are using community supported libraries  you should ensure that they are ready for Vault 0 5 before upgrading      Rekey requires nonce  Vault now generates a nonce when a rekey operation is started in order to ensure that the operation cannot be hijacked  The nonce is output when the rekey operation is started and when rekey status is requested   The nonce must be provided as part of the request parameters when providing an unseal key  The nonce can be communicated from the request initiator to unseal key holders via side channels  the unseal key holders can then verify the nonce  by providing it  when they submit their unseal key   As a convenience  if using the CLI interactively to provide the unseal key  the nonce will be displayed for verification but the user will not be required to manually re type it       TTL  field in token lookup  Previously  the  ttl  field returned when calling  lookup  or  lookup self  on the token auth method displayed the TTL set at token creation  It now displays the time remaining  in seconds  for the token s validity period  The original behavior has been moved to a field named  creation ttl       Grace periods removed  Vault no longer uses grace periods internally for leases or token TTLs  Previously these were set by backends and could differ greatly from one backend to another  causing confusion  TTLs  the  lease duration  field for a lease  or  for a token lookup  the  ttl   are now exact       token renew  CLI command  If the token given for renewal is the same as the token in use by the client  the  renew self  endpoint will be used in the API rather than the  renew  endpoint  Since the  default  policy contains  auth token renew self  this makes it much more likely that the request will succeed rather than somewhat confusingly failing due to a lack of permissions on  auth token renew        status  CLI command  The  status  CLI command now returns an exit code of  0  for an unsealed Vault  as before    2  for a sealed Vault  and  1  for an error  This keeps error return codes consistent across commands      Transit upsertion behavior uses capabilities  Previously  attempting to encrypt with a key that did not exist would create a key with default values  This was convenient but ultimately allowed a client to potentially escape an ACL policy restriction  albeit without any dangerous access  Now that Vault supports more granular capabilities in policies  upsertion behavior is controlled by whether the client has the  create  capability for the request  upsertion is allowed  or only the  update  capability  upsertion is denied       etcd physical backend uses  sync   The  etcd  physical backend now supports  sync  functionality and it is turned on by default  which maps to the upstream library s default  It can be disabled  see the configuration page for information      S3 physical backend prefers environment variables  The  s3  physical backend now prefers environment variables over configuration file variables  This matches the behavior of the rest of the backends and of Vault generally      Lease default and renewal handling  All backends now honor system and mount specific default and maximum lease times  except when specifically overridden by backend configuration or role parameters  or when doing so would not make sense  e g  AWS STS tokens cannot have a lifetime of greater than 1 hour    This allows for a  much  more uniform approach to managing leases on both the operational side and the user side  and removes much ambiguity and uncertainty resulting from backend hardcoded limits   However  also this means that the leases generated by the backends may return significantly different TTLs in 0 5 than in previous versions  unless they have been preconfigured  You can use the  mount tune  CLI command or the   sys mounts  mount point  tune  endpoint to adjust default and max TTL behavior for any mount  This is supported in 0 4  so you can perform this tuning before upgrading   The following list details the ways in which lease handling has changed per backend  In all cases the  mount TTL  means the mount specific value for default or max TTL  however  if no value is set on a given mount  the system default max values are used  This lists only the changes  any lease issuing or renew function not listed here behaves the same as in 0 4    As a refresher  the default TTL is the amount of time that the initial lease token is valid for before it must be renewed  the maximum TTL is the amount of time a lease or token is valid for before it can no longer be renewed and must be reissued  A mount can be more restrictive with its maximum TTL  but cannot be less restrictive than the mount s maximum TTL         Credential  Auth  backends     github    The renewal function now uses the backend s configured maximum   TTL  if set  otherwise  the mount maximum TTL is used     ldap    The renewal function now uses the mount default TTL instead of always   using one hour     token    Tokens can no longer be renewed forever  instead  they now honor the   mount default max TTL     userpass    The renew function now uses the backend s configured maximum TTL    if set  otherwise the mount maximum TTL is used        Secrets engines     aws    New IAM roles no longer always have a default TTL of one hour  instead   honoring the configured default if available and the mount default TTL if not    renewal always used the configured values if available   STS tokens return a   TTL corresponding to the lifetime of the token in AWS and cannot be renewed     cassandra     lease grace period  has been removed since Vault no longer uses   grace periods     consul    The mount default TTL is now used as the default TTL if there is no   backend configuration parameter  Renewal now uses the mount default and   maximum TTLs     mysql    The mount default TTL is now used as the default TTL if there is no   backend configuration parameter     postgresql    The mount default TTL is now used as the default TTL if there   is no backend configuration parameter  In addition  there is no longer any   grace period with the time configured for password expiration within Postgres   itself


vault The Vercel Project sync destination allows Vault to safely synchronize secrets as Vercel environment variables Sync secrets from Vault to Vercel Project Automatically sync and unsync the secrets from Vault to a Vercel project to centralize visibility and control of secrets lifecycle management layout docs page title Sync secrets from Vault to Vercel Project

Answer:
---
layout: docs
page_title: Sync secrets from Vault to Vercel Project
description: >-
  Automatically sync and unsync the secrets from Vault to a Vercel project to centralize visibility and control of secrets lifecycle management.
---

# Sync secrets from Vault to Vercel Project

The Vercel Project sync destination allows Vault to safely synchronize secrets as Vercel environment variables.
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 Vercel tokens with access to modify project environment variables
* Ability to create sync destinations and associations on your Vault server

## Setup

1. If you do not already have a Vercel token, navigate [your account settings](https://vercel.com/account/tokens) to
   generate credentials with the necessary permissions to manage your project's environment variables.

1. Next you need to locate your project ID. It can be found under the `Settings` tab in your project's overview page.

1. Configure a sync destination with the access token and project ID obtained in the previous steps.

  ```shell-session
  $ vault write sys/sync/destinations/vercel-project/my-dest \
      access_token="$TOKEN" \
      project_id="$PROJECT_ID" \
      deployment_environments=development \
      deployment_environments=preview \
      deployment_environments=production
  ```

  **Output:**

  <CodeBlockConfig hideClipboard>

  ```plaintext
  Key                   Value
  ---                   -----
  connection_details    map[access_token:***** deployment_environments:[development preview production] project_id:<project-id>]
  name                  my-dest
  type                  vercel-project
  ```

  </CodeBlockConfig>

## Usage

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

  ```shell-session
  $ vault secrets enable -path='my-kv' kv-v2
  ```

  **Output:**

  <CodeBlockConfig hideClipboard>

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

  </CodeBlockConfig>

1. Create secrets you wish to sync with a target Vercel project.

  ```shell-session
  $ vault kv put -mount='my-kv' my-secret key1='val1'
  ```

  **Output:**

  <CodeBlockConfig hideClipboard>

  ```plaintext
  ==== Secret Path ====
  my-kv/data/my-secret

  ======= Metadata =======
  Key                Value
  ---                -----
  created_time       <timestamp>
  custom_metadata    <nil>
  deletion_time      n/a
  destroyed          false
  version            1
  ```

  </CodeBlockConfig>

1. Create an association between the destination and a secret to synchronize.

  ```shell-session
  $ vault write sys/sync/destinations/vercel-project/my-dest/associations/set \
    mount='my-kv' \
    secret_name='my-secret'
  ```

  **Output:**

  <CodeBlockConfig hideClipboard>

  ```plaintext
  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            vercel-project
  ```

  </CodeBlockConfig>

1. Navigate to your project's settings under the `Environment Variables` section to confirm your secret was successfully
  created in your Vercel project.

Moving forward, any modification on the Vault secret will be propagated in near real time to its Vercel environment variable
counterpart. Creating a new secret version in Vault will overwrite the value in your Vercel Project. Deleting the secret
or the association in Vault will delete the secret on Vercel as well.

<Note>

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 Vercel. For example,
  `secrets.key1="val1"` and `secrets.key2="val2"`.

- `secret-path` granularity stores secrets as a single JSON string that contains
  all the associated key-value pairs. For example, `{"key1":"val1", "key2":"val2"}`.

Since Vercel projects limit environment variables to single-value secrets, the
sync granularity defaults to `secret-key`.

</Note>

## API

Please see the [secrets sync API](/vault/api-docs/system/secrets-sync) for more details.

layout  docs page title  Sync secrets from Vault to Vercel Project description       Automatically sync and unsync the secrets from Vault to a Vercel project to centralize visibility and control of secrets lifecycle management         Sync secrets from Vault to Vercel Project  The Vercel Project sync destination allows Vault to safely synchronize secrets as Vercel environment variables  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 Vercel tokens with access to modify project environment variables   Ability to create sync destinations and associations on your Vault server     Setup  1  If you do not already have a Vercel token  navigate  your account settings  https   vercel com account tokens  to    generate credentials with the necessary permissions to manage your project s environment variables   1  Next you need to locate your project ID  It can be found under the  Settings  tab in your project s overview page   1  Configure a sync destination with the access token and project ID obtained in the previous steps        shell session     vault write sys sync destinations vercel project my dest         access token   TOKEN          project id   PROJECT ID          deployment environments development         deployment environments preview         deployment environments production            Output        CodeBlockConfig hideClipboard        plaintext   Key                   Value                                 connection details    map access token       deployment environments  development preview production  project id  project id     name                  my dest   type                  vercel project            CodeBlockConfig      Usage  1  If you do not already have a KVv2 secret to sync  mount a new KVv2 secrets engine        shell session     vault secrets enable  path  my kv  kv v2            Output        CodeBlockConfig hideClipboard        plaintext   Success  Enabled the kv v2 secrets engine at  my kv             CodeBlockConfig   1  Create secrets you wish to sync with a target Vercel project        shell session     vault kv put  mount  my kv  my secret key1  val1             Output        CodeBlockConfig hideClipboard        plaintext        Secret Path        my kv data my secret            Metadata           Key                Value                              created time        timestamp    custom metadata     nil    deletion time      n a   destroyed          false   version            1            CodeBlockConfig   1  Create an association between the destination and a secret to synchronize        shell session     vault write sys sync destinations vercel project my dest associations set       mount  my kv        secret name  my secret             Output        CodeBlockConfig hideClipboard        plaintext   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            vercel project            CodeBlockConfig   1  Navigate to your project s settings under the  Environment Variables  section to confirm your secret was successfully   created in your Vercel project   Moving forward  any modification on the Vault secret will be propagated in near real time to its Vercel environment variable counterpart  Creating a new secret version in Vault will overwrite the value in your Vercel Project  Deleting the secret or the association in Vault will delete the secret on Vercel as well    Note   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 Vercel  For example     secrets key1  val1   and  secrets key2  val2        secret path  granularity stores secrets as a single JSON string that contains   all the associated key value pairs  For example     key1   val1    key2   val2      Since Vercel projects limit environment variables to single value secrets  the sync granularity defaults to  secret key      Note      API  Please see the  secrets sync API   vault api docs system secrets sync  for more details


vault The Google Cloud Platform GCP Secret Manager sync destination allows Vault to safely synchronize secrets to your GCP projects page title Sync secrets from Vault to GCP Secret Manager Sync secrets from Vault to GCP Secret Manager layout docs Automatically sync and unsync the secrets from Vault to GCP Secret Manager to centralize visibility and control of secrets lifecycle management

Answer:
---
layout: docs
page_title: Sync secrets from Vault to GCP Secret Manager
description: >-
  Automatically sync and unsync the secrets from Vault to GCP Secret Manager to centralize visibility and control of secrets lifecycle management.
---

# Sync secrets from Vault to GCP Secret Manager

The Google Cloud Platform (GCP) Secret Manager sync destination allows Vault to safely synchronize secrets to your GCP projects.
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 GCP Service Account credentials with access to the Secret Manager
* Ability to create sync destinations and associations on your Vault server

## Setup

1. If you do not already have a Service Account, navigate to the IAM & Admin page in the Google Cloud console to
  [create a new Service Account](https://cloud.google.com/iam/docs/service-accounts-create) with the
  [necessary permissions](/vault/docs/sync/gcpsm#permissions). [Instructions](/vault/docs/sync/gcpsm#provision-service-account)
  to provision this Service Account via Terraform can be found below.

1. Configure a sync destination with the Service Account JSON credentials created in the previous step. See docs for
  [alternative ways](/vault/docs/secrets/gcp#authentication) to pass in the `credentials` parameter.

  ```shell-session
  $ vault write sys/sync/destinations/gcp-sm/my-dest \
      credentials='@path/to/credentials.json'
      replication_locations='us-east1,us-west1'
  ```

  **Output:**

  <CodeBlockConfig hideClipboard>

  ```plaintext
  Key                   Value
  ---                   -----
  connection_details    map[credentials:***** replication_locations:us-east1,us-west1]
  name                  my-dest
  type                  gcp-sm
  ```

  </CodeBlockConfig>

## Usage

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

  ```shell-session
  $ vault secrets enable -path=my-kv kv-v2
  ```

  **Output**:

  <CodeBlockConfig hideClipboard>

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

  </CodeBlockConfig>

1. Create secrets you wish to sync with a target GCP Secret Manager.

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

  **Output**:

  <CodeBlockConfig hideClipboard>

  ```plaintext
  ==== Secret Path ====
  my-kv/data/my-secret

  ======= Metadata =======
  Key                Value
  ---                -----
  created_time       <timestamp>
  custom_metadata    <nil>
  deletion_time      n/a
  destroyed          false
  version            1
  ```

  </CodeBlockConfig>

1. Create an association between the destination and a secret to synchronize.

  ```shell-session
  $ vault write sys/sync/destinations/gcp-sm/my-dest/associations/set \
      mount='my-kv' \
      secret_name='my-secret'
  ```

  **Output:**

  <CodeBlockConfig hideClipboard>

  ```plaintext
  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            gcp-sm
  ```

  </CodeBlockConfig>

1. Navigate to the [Secret Manager](https://console.cloud.google.com/security/secret-manager) in the Google Cloud console
  to confirm your secret was successfully created in your GCP project.

Moving forward, any modification on the Vault secret will be propagated in near real time to its GCP Secret Manager
counterpart. Creating a new secret version in Vault will create a new version in GCP Secret Manager. Deleting the secret
or the association in Vault will delete the secret in your GCP project as well.

### Replication policy

GCP can target specific geographic regions to provide strict control on where
your applications store data and sync secrets. You can target specific GCP
regions for each sync destinations during creation which will limit where Vault writes
secrets.

Regardless of the region limits on writes, synced secrets are always readable
globally when the client has the required permissions.

## Permissions

The credentials given to Vault must have the following permissions to synchronize secrets:

```shell-session
secretmanager.secrets.create
secretmanager.secrets.delete
secretmanager.secrets.update
secretmanager.versions.add
secretmanager.versions.destroy
```

## Provision service account

Vault needs to be configured with credentials to establish a trust relationship with your GCP project so it can manage
Secret Manager secrets on your behalf. The IAM & Admin page in the Google Cloud console can be used to
[create a new Service Account](https://cloud.google.com/iam/docs/service-accounts-create) with access to the Secret Manager.

You can equally use the [Terraform Google provider](https://registry.terraform.io/providers/hashicorp/google/latest/docs#authentication-and-configuration)
to provision a GCP Service Account with the appropriate policies.

1. Copy-paste this HCL snippet into a `secrets-sync-setup.tf` file.

  ```hcl
  provider "google" {
      // See https://registry.terraform.io/providers/hashicorp/google/latest/docs#authentication-and-configuration to setup the Google Provider
      // for options on how to configure this provider. The following parameters or environment
      // variables are typically used.

      // Parameters
      // region = "" (Optional)
      // project = ""
      // credentials = ""

      // Environment Variables
      // GOOGLE_REGION (optional)
      // GOOGLE_PROJECT
      // GOOGLE_CREDENTIALS (The path to a service account key file with the
      //                    "Service Account Admin", "Service Account Key Admin",
      //                    "Secret Manager Admin", and "Project IAM Admin" roles
      //                    attached)
  }

  data "google_client_config" "config" {}

  resource "google_service_account" "vault_secrets_sync_account" {
    account_id  = "gcp-sm-vault-secrets-sync"
    description = "service account for Vault Secrets Sync feature"
  }

  // Production environments should use a more restricted role.
  // The built-in secret manager admin role is used as an example for simplicity.
  data "google_iam_policy" "vault_secrets_sync_iam_policy" {
    binding {
      role = "roles/secretmanager.admin"
      members = [
        google_service_account.vault_secrets_sync_account.email,
      ]
    }
  }

  resource "google_project_iam_member" "vault_secrets_sync_iam_member" {
    project = data.google_client_config.config.project
    role    = "roles/secretmanager.admin"
    member  = google_service_account.vault_secrets_sync_account.member
  }

  resource "google_service_account_key" "vault_secrets_sync_account_key" {
    service_account_id = google_service_account.vault_secrets_sync_account.name
    public_key_type    = "TYPE_X509_PEM_FILE"
  }

  resource "local_file" "vault_secrets_sync_credentials_file" {
    content  = base64decode(google_service_account_key.vault_secrets_sync_account_key.private_key)
    filename = "gcp-sm-sync-service-account-credentials.json"
  }

  output "vault_secrets_sync_credentials_file_path" {
    value = abspath("${path.module}/${local_file.sync_service_account_credentials_file.filename}")
  }
  ```

1. Execute a plan to validate the Terraform Google provider is properly configured.

  ```shell-session
  $ terraform init && terraform plan
  ```

  **Output:**

  <CodeBlockConfig hideClipboard>

  ```plaintext
  (...)
  Plan: 4 to add, 0 to change, 0 to destroy.
  ```

  </CodeBlockConfig>

1. Execute an apply to provision the Service Account.

  ```shell-session
  $ terraform apply
  ```

  **Output:**

  <CodeBlockConfig hideClipboard>

  ```plaintext
  (...)
  Apply complete! Resources: 4 added, 0 changed, 0 destroyed.

  Outputs:

  sync_service_account_credentials_file = "/path/to/credentials/file/gcp-sm-sync-service-account-credentials.json"
  ```

  </CodeBlockConfig>

The generated Service Account credentials file can then be used to configure the Vault GCP Secret Manager destination
following the [setup](/vault/docs/sync/gcpsm#setup) steps.

## Targeting specific GCP projects

By default, the target GCP project to sync secrets with is derived from the service
account JSON [credentials](/vault/api-docs/system/secrets-sync#credentials) or application
default credentials for a particular GCP sync destination. This means secrets will be synced
within the parent project of the configured service account.

In some cases, it's desirable to use a single service account or [workload identity](https://cloud.google.com/compute/docs/access/create-enable-service-accounts-for-instances)
to sync secrets with any number of GCP projects within an organization. To achieve this,
you can set the `project_id` parameter to the target project to sync secrets with:

```shell-session
  $ vault write sys/sync/destinations/gcp-sm/my-dest \
      project_id='target-project-id'
```

This overrides the project ID derived from the service account JSON credentials or application
default credentials. The service account must be [authorized](https://cloud.google.com/iam/docs/service-account-overview#locations)
to perform Secret Manager actions in the target project.

## Access management

You can allow or restrict access to secrets based on
[IAM conditions](https://cloud.google.com/iam/docs/conditions-resource-attributes#resource-name)
against the fully-qualified resource name. For secrets in Secret Manager, a fully-qualified resource name must have the following
format:

  `projects/<project_number>/secrets/<secret_name>`

<Tip title="Use the project number, not the project ID">

  The project **number** is not the same as the project **ID**. Project numbers
  are **numeric** while project IDs are **alphanumeric**. They can be found on
  the Project info panel in the web dashboard or on the Welcome screen.

</Tip>

For example, the default secret name template prepends the word `vault` to the
beginning of secret names. To prevent Vault from modifying secrets that were not
created by a sync operation, you can use a role binding against the resource
name with the `startsWith` condition:

  <CodeBlockConfig hideClipboard>

    resource.name.startsWith("projects/<project_number>/secrets/vault")

  </CodeBlockConfig>

To prevent out-of-band overwrites, simply add a negative condition with `!` on any
write-access role bindings not being used by Vault that contain Secret Manager permissions:

  <CodeBlockConfig hideClipboard>

    !(resource.name.startsWith("projects/<project_number>/secrets/vault"))

  </CodeBlockConfig>

To add conditions to IAM principles in GCP, click "+ADD IAM CONDITION" on the **Assign Roles** screen.

![Assign Roles screen in GCP with the "+ADD IAM CONDITION" link circled in red](/img/gcp-add-iam-conditions_light.png#light-theme-only)
![Assign Roles screen in GCP with the "+ADD IAM CONDITION" link circled in red](/img/gcp-add-iam-conditions_dark.png#dark-theme-only)

<Tip title="Refer to Google's Overview of IAM Conditions documentation">

  [Google's documentation](https://cloud.google.com/iam/docs/conditions-overview) on IAM Conditions provides
  further information on how they work and how they should be used, as well as their limits.

</Tip>

## API

Please see the [secrets sync API](/vault/api-docs/system/secrets-sync) for more details.

layout  docs page title  Sync secrets from Vault to GCP Secret Manager description       Automatically sync and unsync the secrets from Vault to GCP Secret Manager to centralize visibility and control of secrets lifecycle management         Sync secrets from Vault to GCP Secret Manager  The Google Cloud Platform  GCP  Secret Manager sync destination allows Vault to safely synchronize secrets to your GCP projects  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 GCP Service Account credentials with access to the Secret Manager   Ability to create sync destinations and associations on your Vault server     Setup  1  If you do not already have a Service Account  navigate to the IAM   Admin page in the Google Cloud console to    create a new Service Account  https   cloud google com iam docs service accounts create  with the    necessary permissions   vault docs sync gcpsm permissions    Instructions   vault docs sync gcpsm provision service account    to provision this Service Account via Terraform can be found below   1  Configure a sync destination with the Service Account JSON credentials created in the previous step  See docs for    alternative ways   vault docs secrets gcp authentication  to pass in the  credentials  parameter        shell session     vault write sys sync destinations gcp sm my dest         credentials   path to credentials json        replication locations  us east1 us west1             Output        CodeBlockConfig hideClipboard        plaintext   Key                   Value                                 connection details    map credentials       replication locations us east1 us west1    name                  my dest   type                  gcp sm            CodeBlockConfig      Usage  1  If you do not already have a KVv2 secret to sync  mount a new KVv2 secrets engine        shell session     vault secrets enable  path my kv kv v2            Output        CodeBlockConfig hideClipboard        plaintext   Success  Enabled the kv v2 secrets engine at  my kv             CodeBlockConfig   1  Create secrets you wish to sync with a target GCP Secret Manager        shell session     vault kv put  mount my kv my secret foo  bar             Output        CodeBlockConfig hideClipboard        plaintext        Secret Path        my kv data my secret            Metadata           Key                Value                              created time        timestamp    custom metadata     nil    deletion time      n a   destroyed          false   version            1            CodeBlockConfig   1  Create an association between the destination and a secret to synchronize        shell session     vault write sys sync destinations gcp sm my dest associations set         mount  my kv          secret name  my secret             Output        CodeBlockConfig hideClipboard        plaintext   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            gcp sm            CodeBlockConfig   1  Navigate to the  Secret Manager  https   console cloud google com security secret manager  in the Google Cloud console   to confirm your secret was successfully created in your GCP project   Moving forward  any modification on the Vault secret will be propagated in near real time to its GCP Secret Manager counterpart  Creating a new secret version in Vault will create a new version in GCP Secret Manager  Deleting the secret or the association in Vault will delete the secret in your GCP project as well       Replication policy  GCP can target specific geographic regions to provide strict control on where your applications store data and sync secrets  You can target specific GCP  regions for each sync destinations during creation which will limit where Vault writes  secrets    Regardless of the region limits on writes  synced secrets are always readable  globally when the client has the required permissions      Permissions  The credentials given to Vault must have the following permissions to synchronize secrets      shell session secretmanager secrets create secretmanager secrets delete secretmanager secrets update secretmanager versions add secretmanager versions destroy          Provision service account  Vault needs to be configured with credentials to establish a trust relationship with your GCP project so it can manage Secret Manager secrets on your behalf  The IAM   Admin page in the Google Cloud console can be used to  create a new Service Account  https   cloud google com iam docs service accounts create  with access to the Secret Manager   You can equally use the  Terraform Google provider  https   registry terraform io providers hashicorp google latest docs authentication and configuration  to provision a GCP Service Account with the appropriate policies   1  Copy paste this HCL snippet into a  secrets sync setup tf  file        hcl   provider  google             See https   registry terraform io providers hashicorp google latest docs authentication and configuration to setup the Google Provider          for options on how to configure this provider  The following parameters or environment          variables are typically used            Parameters          region       Optional           project               credentials                Environment Variables          GOOGLE REGION  optional           GOOGLE PROJECT          GOOGLE CREDENTIALS  The path to a service account key file with the                              Service Account Admin    Service Account Key Admin                                Secret Manager Admin   and  Project IAM Admin  roles                             attached         data  google client config   config        resource  google service account   vault secrets sync account        account id     gcp sm vault secrets sync      description    service account for Vault Secrets Sync feature            Production environments should use a more restricted role       The built in secret manager admin role is used as an example for simplicity    data  google iam policy   vault secrets sync iam policy        binding         role    roles secretmanager admin        members             google service account vault secrets sync account email                       resource  google project iam member   vault secrets sync iam member        project   data google client config config project     role       roles secretmanager admin      member    google service account vault secrets sync account member        resource  google service account key   vault secrets sync account key        service account id   google service account vault secrets sync account name     public key type       TYPE X509 PEM FILE         resource  local file   vault secrets sync credentials file        content    base64decode google service account key vault secrets sync account key private key      filename    gcp sm sync service account credentials json         output  vault secrets sync credentials file path        value   abspath    path module    local file sync service account credentials file filename               1  Execute a plan to validate the Terraform Google provider is properly configured        shell session     terraform init    terraform plan            Output        CodeBlockConfig hideClipboard        plaintext           Plan  4 to add  0 to change  0 to destroy             CodeBlockConfig   1  Execute an apply to provision the Service Account        shell session     terraform apply            Output        CodeBlockConfig hideClipboard        plaintext           Apply complete  Resources  4 added  0 changed  0 destroyed     Outputs     sync service account credentials file     path to credentials file gcp sm sync service account credentials json             CodeBlockConfig   The generated Service Account credentials file can then be used to configure the Vault GCP Secret Manager destination following the  setup   vault docs sync gcpsm setup  steps      Targeting specific GCP projects  By default  the target GCP project to sync secrets with is derived from the service  account JSON  credentials   vault api docs system secrets sync credentials  or application  default credentials for a particular GCP sync destination  This means secrets will be synced within the parent project of the configured service account   In some cases  it s desirable to use a single service account or  workload identity  https   cloud google com compute docs access create enable service accounts for instances  to sync secrets with any number of GCP projects within an organization  To achieve this   you can set the  project id  parameter to the target project to sync secrets with      shell session     vault write sys sync destinations gcp sm my dest         project id  target project id       This overrides the project ID derived from the service account JSON credentials or application default credentials  The service account must be  authorized  https   cloud google com iam docs service account overview locations  to perform Secret Manager actions in the target project      Access management  You can allow or restrict access to secrets based on  IAM conditions  https   cloud google com iam docs conditions resource attributes resource name  against the fully qualified resource name  For secrets in Secret Manager  a fully qualified resource name must have the following format      projects  project number  secrets  secret name     Tip title  Use the project number  not the project ID       The project   number   is not the same as the project   ID    Project numbers   are   numeric   while project IDs are   alphanumeric    They can be found on   the Project info panel in the web dashboard or on the Welcome screen     Tip   For example  the default secret name template prepends the word  vault  to the beginning of secret names  To prevent Vault from modifying secrets that were not created by a sync operation  you can use a role binding against the resource name with the  startsWith  condition      CodeBlockConfig hideClipboard       resource name startsWith  projects  project number  secrets vault        CodeBlockConfig   To prevent out of band overwrites  simply add a negative condition with     on any write access role bindings not being used by Vault that contain Secret Manager permissions      CodeBlockConfig hideClipboard         resource name startsWith  projects  project number  secrets vault         CodeBlockConfig   To add conditions to IAM principles in GCP  click   ADD IAM CONDITION  on the   Assign Roles   screen     Assign Roles screen in GCP with the   ADD IAM CONDITION  link circled in red   img gcp add iam conditions light png light theme only    Assign Roles screen in GCP with the   ADD IAM CONDITION  link circled in red   img gcp add iam conditions dark png dark theme only    Tip title  Refer to Google s Overview of IAM Conditions documentation        Google s documentation  https   cloud google com iam docs conditions overview  on IAM Conditions provides   further information on how they work and how they should be used  as well as their limits     Tip      API  Please see the  secrets sync API   vault api docs system secrets sync  for more details


vault page title Sync secrets from Vault to GitHub Sync secrets from Vault to GitHub Automatically sync and unsync the secrets from Vault to GitHub to centralize visibility and control of secrets lifecycle management layout docs The GitHub actions sync destination allows Vault to safely synchronize secrets as GitHub organization repository or environment secrets

Answer:
---
layout: docs
page_title: Sync secrets from Vault to GitHub
description: >-
  Automatically sync and unsync the secrets from Vault to GitHub to centralize visibility and control of secrets lifecycle management.
---

# Sync secrets from Vault to GitHub

The GitHub actions sync destination allows Vault to safely synchronize secrets as GitHub organization, 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.

Prerequisites:
* Ability to read or create KVv2 secrets
* Ability to create GitHub fine-grained or personal tokens (or a GitHub application) with access to modify organization and/or 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, 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)
  that has write permission on the target sync location in GitHub for "Secrets". The "Secrets" permissions in GitHub automatically includes read-only "Metadata" access.

<Warning title="Pitfalls of using an access token">

  Access tokens are tied to a user account and can be revoked at any time, causing disruptions to the sync process.
  GitHub applications are long-lived and do not expire. Using a GitHub application for authentication is preferred over using a personal access token.

</Warning>

### Repositories

Use `vault write` to configure a repository sync destination with an access token:

  ```shell-session
  $ vault write sys/sync/destinations/gh/DESTINATION_NAME \
      access_token="GITHUB_ACCESS_TOKEN"                  \
      secrets_location="GITHUB_SECRETS_LOCATION"          \
      repository_owner="GITHUB_OWNER_NAME"                \
      repository_name="GITHUB_REPO_NAME"
  ```

  For example:

  <CodeBlockConfig hideClipboard>

  ```
  $ vault write sys/sync/destinations/gh/hcrepo-sandbox       \
      access_token="github_pat_11ABC000000000000000000000DEF" \
      secrets_location="repository"                           \
      repository_owner="hashicorp"                            \
      repository_name="hcrepo"

  Key                   Value
  ---                   -----
  connection_details    map[access_token:***** secrets_location:repository repository_owner:hashicorp repository_name:hcrepo]
  name                  hcrepo-sandbox
  type                  gh
  ```

  </CodeBlockConfig>

### Environments

Use `vault write` to configure an environment sync destination:

  ```shell-session
  $ vault write sys/sync/destinations/gh/DESTINATION_NAME \
      access_token="GITHUB_ACCESS_TOKEN"                  \
      secrets_location="GITHUB_SECRETS_LOCATION"          \
      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" \
      secrets_location="repository"                           \
      repository_owner="hashicorp"                            \
      repository_name="hcrepo"                                \
      environment_name="sandbox"

  Key                   Value
  ---                   -----
  connection_details    map[access_token:***** secrets_location:repository environment_name:sandbox repository_owner:hashicorp repository_name:hcrepo]
  name                  hcrepo-sandbox
  type                  gh
  ```

  </CodeBlockConfig>

### Organizations

@include 'alerts/beta.mdx'

Beta limitations:

- You cannot update visibility (`organization_visibility`) after creating a
  secrets sync destination.
- You cannot update the list of repositories with access to synced secrets
  (`selected_repository_names`) after creating a secrets sync destination.

Sync secrets to GitHub organization to share those secrets across repositories
in the organizations. You choose to make secrets global to the organization,
limited to private/internal repos, or limited to specifically named repositories.

Refer to the [Secrets sync API docs](/vault/docs/sync/github#api) for detailed
configuration information.

<Warning>

  Organization secrets are
  [not visible to private repositories for GitHub Free accounts](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-an-organization).

</Warning>

Use `vault write` to configure an organization sync destination:

  ```shell-session
  $ vault write sys/sync/destinations/gh/DESTINATION_NAME \
      access_token="GITHUB_ACCESS_TOKEN"                  \
      secrets_location="GITHUB_SECRETS_LOCATION"          \
      organization_name="ORGANIZATION_NAME"               \
      organization_visibility="ORGANIZATION_VISIBILITY"
  ```

  For example:

  <CodeBlockConfig hideClipboard>

  ```
  $ vault write sys/sync/destinations/gh/hcrepo-sandbox       \
      access_token="github_pat_11ABC000000000000000000000DEF" \
      secrets_location="organization"                         \
      organization_name="hashicorp"                           \
      organization_visibility="selected"                      \
      selected_repository_names="hcrepo-1,hcrepo-2"

  Key                   Value
  ---                   -----
  connection_details    map[access_token:***** secrets_location:organization organization_name:hashicorp organization_visibility:all selected_repository_names:[hcrepo-1 hcrepo-2]]
  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.

  ```shell-session
  $ vault secrets enable -path=my-kv kv-v2
  ```

  **Output:**

  <CodeBlockConfig hideClipboard>

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

  </CodeBlockConfig>

1. Create secrets you wish to sync with a target GitHub repository for Actions.

  ```shell-session
  $ vault kv put -mount='my-kv' my-secret key1='val1' key2='val2'
  ```

  **Output:**

  <CodeBlockConfig hideClipboard>

  ```plaintext
  ==== Secret Path ====
  my-kv/data/my-secret

  ======= Metadata =======
  Key                Value
  ---                -----
  created_time       <timestamp>
  custom_metadata    <nil>
  deletion_time      n/a
  destroyed          false
  version            1
  ```

  </CodeBlockConfig>

1. Create an association between the destination and a secret to synchronize.

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

  **Output:**

  <CodeBlockConfig hideClipboard>

  ```plaintext
  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
  ```

  </CodeBlockConfig>

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 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.

## Security

<Note>

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. For example,
  `secrets.key1="val1"` and `secrets.key2="val2"`.

- `secret-path` granularity stores secrets as a single JSON string that contains
  all the associated key-value pairs. For example, `{"key1":"val1", "key2":"val2"}`.

Since GitHub limits secrets to single-value secrets, the sync granularity defaults to `secret-key`.

</Note>

If using the secret-path granularity, it is strongly advised to mask individual values for each sub-key to prevent the
unintended disclosure of secrets in any GitHub Action outputs. The following snippet illustrates how to mask each secret values:

```yaml
  name: Mask synced secret values

  on:
    workflow_dispatch

  jobs:
    synced-secret-examples:
      runs-on: ubuntu-latest
      steps:
        - name: ✓ Mask synced secret values
          run: |
            for v in $(echo '$' | jq -r '.[]'); do
              echo "::add-mask::$v"
            done
```

If the GitHub destination uses the default `secret-key` granularity, the values are masked by GitHub automatically.

## GitHub application

Instead of authenticating with a personal access token, you can choose to
authenticate with a
[custom GitHub application](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app).

Start by following the GitHub instructions for
[installing a GitHub app](https://docs.github.com/en/apps/using-github-apps/installing-your-own-github-app).
to install your GitHub application on a specified repository and note the
assigned installation ID.

<Tip title="Your installation ID is in the app URL">

  You can find your assigned installation ID in the URL path parameter:
  `https://github.com/settings/installations/<INSTALLATION_ID>`

</Tip>

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.

Callback, redirect URLs, and webhooks are not required at this time.

To configure the application in Vault, use `vault write` with the
`sys/sync/github-apps` endpoint to assign a unique name and set the relevant
information:

<CodeBlockConfig hideClipboard>

```shell-session
$ vault write sys/sync/github-apps/<APP_NAME> \
  app_id=<APP_ID> \
  private_key=@/path/to/private/key

Key            Value
---            -----
app_id         <app-id>
fingerprint    <fingerprint>
name           <app-name>
private_key    *****
```
</CodeBlockConfig>

<Tip title="Fingerprint verification">

Vault returns the fingerprint of the private_key provided to ensure that the
correct private key was configured and that it was not tampered with along the way.
You can compare the fingerprint to the one provided by GitHub.
For more information, see [Verifying private keys](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps#verifying-private-keys).

</Tip>

Next, use `vault write` with the `sys/sync/destinations/gh` endpoint to
configure a GitHub destination that references your new GitHub application:

<CodeBlockConfig hideClipboard>

```shell-session
$ vault write sys/sync/destinations/gh/<DESTINATION_NAME> \
installation_id=<INSTALLATION_ID>                         \
repository_owner=<GITHUB_USER>                            \
repository_name=<MY_REPO_NAME>                            \
app_name=<APP_NAME>

Key                   Value
---                   -----
connection_details    map[app_config:map[app_name:<app-name>] installation_id:<installation-id> repository_name:<repo-name> repository_owner:<repo-owner>]
name                  my-dest
options               map[custom_tags:map[] granularity_level:secret-key secret_name_template:VAULT___]
type                  gh
```
</CodeBlockConfig>

You can now [use your GitHub application to sync secrets with your GitHub repository](#usage).

## API

Please see the [secrets sync API](/vault/api-docs/system/secrets-sync) for more details.

layout  docs page title  Sync secrets from Vault to GitHub description       Automatically sync and unsync the secrets from Vault to GitHub to centralize visibility and control of secrets lifecycle management         Sync secrets from Vault to GitHub  The GitHub actions sync destination allows Vault to safely synchronize secrets as GitHub organization  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   Prerequisites    Ability to read or create KVv2 secrets   Ability to create GitHub fine grained or personal tokens  or a GitHub application  with access to modify organization and or 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  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    that has write permission on the target sync location in GitHub for  Secrets   The  Secrets  permissions in GitHub automatically includes read only  Metadata  access     Warning title  Pitfalls of using an access token      Access tokens are tied to a user account and can be revoked at any time  causing disruptions to the sync process    GitHub applications are long lived and do not expire  Using a GitHub application for authentication is preferred over using a personal access token       Warning       Repositories  Use  vault write  to configure a repository sync destination with an access token        shell session     vault write sys sync destinations gh DESTINATION NAME         access token  GITHUB ACCESS TOKEN                           secrets location  GITHUB SECRETS LOCATION                   repository owner  GITHUB OWNER NAME                         repository name  GITHUB REPO NAME           For example      CodeBlockConfig hideClipboard             vault write sys sync destinations gh hcrepo sandbox               access token  github pat 11ABC000000000000000000000DEF          secrets location  repository                                    repository owner  hashicorp                                     repository name  hcrepo     Key                   Value                                 connection details    map access token       secrets location repository repository owner hashicorp repository name hcrepo    name                  hcrepo sandbox   type                  gh            CodeBlockConfig       Environments  Use  vault write  to configure an environment sync destination        shell session     vault write sys sync destinations gh DESTINATION NAME         access token  GITHUB ACCESS TOKEN                           secrets location  GITHUB SECRETS LOCATION                   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          secrets location  repository                                    repository owner  hashicorp                                     repository name  hcrepo                                         environment name  sandbox     Key                   Value                                 connection details    map access token       secrets location repository environment name sandbox repository owner hashicorp repository name hcrepo    name                  hcrepo sandbox   type                  gh            CodeBlockConfig       Organizations   include  alerts beta mdx    Beta limitations     You cannot update visibility   organization visibility   after creating a   secrets sync destination    You cannot update the list of repositories with access to synced secrets     selected repository names   after creating a secrets sync destination   Sync secrets to GitHub organization to share those secrets across repositories  in the organizations  You choose to make secrets global to the organization  limited to private internal repos  or limited to specifically named repositories   Refer to the  Secrets sync API docs   vault docs sync github api  for detailed configuration information    Warning     Organization secrets are    not visible to private repositories for GitHub Free accounts  https   docs github com en actions security for github actions security guides using secrets in github actions creating secrets for an organization      Warning   Use  vault write  to configure an organization sync destination        shell session     vault write sys sync destinations gh DESTINATION NAME         access token  GITHUB ACCESS TOKEN                           secrets location  GITHUB SECRETS LOCATION                   organization name  ORGANIZATION NAME                        organization visibility  ORGANIZATION VISIBILITY           For example      CodeBlockConfig hideClipboard             vault write sys sync destinations gh hcrepo sandbox               access token  github pat 11ABC000000000000000000000DEF          secrets location  organization                                  organization name  hashicorp                                    organization visibility  selected                               selected repository names  hcrepo 1 hcrepo 2     Key                   Value                                 connection details    map access token       secrets location organization organization name hashicorp organization visibility all selected repository names  hcrepo 1 hcrepo 2     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        shell session     vault secrets enable  path my kv kv v2            Output        CodeBlockConfig hideClipboard           Success  Enabled the kv v2 secrets engine at  my kv             CodeBlockConfig   1  Create secrets you wish to sync with a target GitHub repository for Actions        shell session     vault kv put  mount  my kv  my secret key1  val1  key2  val2             Output        CodeBlockConfig hideClipboard        plaintext        Secret Path        my kv data my secret            Metadata           Key                Value                              created time        timestamp    custom metadata     nil    deletion time      n a   destroyed          false   version            1            CodeBlockConfig   1  Create an association between the destination and a secret to synchronize        shell session     vault write sys sync destinations gh my dest associations set         mount  my kv          secret name  my secret             Output        CodeBlockConfig hideClipboard        plaintext   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            CodeBlockConfig   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 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      Security   Note   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  For example     secrets key1  val1   and  secrets key2  val2        secret path  granularity stores secrets as a single JSON string that contains   all the associated key value pairs  For example     key1   val1    key2   val2      Since GitHub limits secrets to single value secrets  the sync granularity defaults to  secret key      Note   If using the secret path granularity  it is strongly advised to mask individual values for each sub key to prevent the unintended disclosure of secrets in any GitHub Action outputs  The following snippet illustrates how to mask each secret values      yaml   name  Mask synced secret values    on      workflow dispatch    jobs      synced secret examples        runs on  ubuntu latest       steps            name    Mask synced secret values           run                for v in   echo       jq  r         do               echo    add mask   v              done      If the GitHub destination uses the default  secret key  granularity  the values are masked by GitHub automatically      GitHub application  Instead of authenticating with a personal access token  you can choose to authenticate with a  custom GitHub application  https   docs github com en apps creating github apps registering a github app registering a github app    Start by following the GitHub instructions for  installing a GitHub app  https   docs github com en apps using github apps installing your own github app   to install your GitHub application on a specified repository and note the assigned installation ID    Tip title  Your installation ID is in the app URL      You can find your assigned installation ID in the URL path parameter     https   github com settings installations  INSTALLATION ID      Tip   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   Callback  redirect URLs  and webhooks are not required at this time   To configure the application in Vault  use  vault write  with the  sys sync github apps  endpoint to assign a unique name and set the relevant information    CodeBlockConfig hideClipboard      shell session   vault write sys sync github apps  APP NAME      app id  APP ID      private key   path to private key  Key            Value                      app id          app id  fingerprint     fingerprint  name            app name  private key                CodeBlockConfig    Tip title  Fingerprint verification    Vault returns the fingerprint of the private key provided to ensure that the correct private key was configured and that it was not tampered with along the way  You can compare the fingerprint to the one provided by GitHub  For more information  see  Verifying private keys  https   docs github com en apps creating github apps authenticating with a github app managing private keys for github apps verifying private keys      Tip    Next  use  vault write  with the  sys sync destinations gh  endpoint to configure a GitHub destination that references your new GitHub application    CodeBlockConfig hideClipboard      shell session   vault write sys sync destinations gh  DESTINATION NAME    installation id  INSTALLATION ID                            repository owner  GITHUB USER                               repository name  MY REPO NAME                               app name  APP NAME   Key                   Value                             connection details    map app config map app name  app name   installation id  installation id  repository name  repo name  repository owner  repo owner   name                  my dest options               map custom tags map   granularity level secret key secret name template VAULT     type                  gh       CodeBlockConfig   You can now  use your GitHub application to sync secrets with your GitHub repository   usage       API  Please see the  secrets sync API   vault api docs system secrets sync  for more details