This page explains how to include sensitive information such as passwords andAPI keys in Cloud Build.

Secret Manager is a Google Cloudservice that securely stores API keys, passwords, and other sensitive data. Toinclude sensitive information in your builds, you can store the information inSecret Manager and then configure your build to access the informationfrom Secret Manager.

Before you begin

• Enable the Cloud Build and Secret Manager APIs.

  Roles required to enable APIs

  To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

  Enable the APIs

• To use the command-line examples in this guide, install andconfigure theGoogle Cloud CLI.

  Note: If you've installed gcloud CLI previously, make sure you have thelatest available version by runninggcloud components update.

• Make sure you've stored the secret in Secret Manager. For instructions,seeCreating a secret.

  • Note down the secret name and secret version of your secret. You'll need thisinformation to configure Cloud Build to access the secret.

Required IAM permissions

Grant theSecret Manager Secret Accessor(roles/secretmanager.secretAccessor) IAM rolefor the secret to the service account you are using for the build:

1. Open the Secret Manager page in the Google Cloud console:

   Go to the Secret Manager page

2. Select the checkbox of the secret you wish to use in your build.

3. If it is not already open, clickShow info panel to open the panel.

4. In the panel, underPermissions, clickAdd principal.

5. In theNew principals field, enter the email address of your serviceaccount.

6. In theSelect a role drop-down box, selectSecret Manager Secret Accessor.

7. ClickSave.

Configuring builds to access UTF-8 secrets from Secret Manager

1. In your project root directory, create a Cloud Build configfile namedcloudbuild.yaml orcloudbuild.json.

2. In the build config file:

   • After all the buildsteps, add anavailableSecrets field to specify thesecret version and environment variables to use for your secret. You canincludesubstitution variablesin the value of thesecretVersion field. You can specify more than one secretin a build.
   • In the build step where you want to specify the secret:
     • Add anentrypoint field pointing tobash to use the bash tool in thebuild step. This isrequired to refer to the environment variable for thesecret.
     • Add asecretEnv field specifying the environment variable.
     • In theargs field, add a-c flag as the first argument. Any stringyou pass after-c is treated as a command. For more information on runningbash commands with-c, see thebash documentation.
     • When specifying the secret in theargs field, specify it using theenvironment variable prefixed with$$.
   Note: You can refer to secrets only in theargs field of a build step.

   The following example build config file shows how to login to Docker using theDocker username and password stored in Secret Manager.

   YAML

   steps:-name:'gcr.io/cloud-builders/docker'entrypoint:'bash'args:['-c','dockerlogin--username=$$USERNAME--password=$$PASSWORD']secretEnv:['USERNAME','PASSWORD']availableSecrets:secretManager:-versionName:projects/PROJECT_ID/secrets/DOCKER_PASSWORD_SECRET_NAME/versions/DOCKER_PASSWORD_SECRET_VERSIONenv:'PASSWORD'-versionName:projects/PROJECT_ID/secrets/DOCKER_USERNAME_SECRET_NAME/versions/DOCKER_USERNAME_SECRET_VERSIONenv:'USERNAME'

   JSON

   {"steps":[{"name":"gcr.io/cloud-builders/docker","entrypoint":"bash","args":["-c","docker login --username=$$USERNAME --password=$$PASSWORD"],"secretEnv":["USERNAME","PASSWORD"]}],"availableSecrets":{"secretManager":[{"versionName":"projects/PROJECT_ID/secrets/DOCKER_PASSWORD_SECRET_NAME/versions/DOCKER_PASSWORD_SECRET_VERSION","env":"PASSWORD"},{"versionName":"projects/PROJECT_ID/secrets/DOCKER_USERNAME_SECRET_NAME/versions/DOCKER_USERNAME_SECRET_VERSION","env":"USERNAME"}]}}

   Replace the placeholder values in the preceding commands with the following:

   • PROJECT_ID: Theproject ID or project number of theGoogle Cloud project where you've stored your secrets.
   • DOCKER_USERNAME_SECRET_NAME: The secret namecorresponding to your Docker username. You can get the secret name fromtheSecret Manager pagein the Google Cloud console.
   • DOCKER_USERNAME_SECRET_VERSION: The secret versionof your Docker username. You can get the secret version by clicking on asecret name on theSecret Manager page in the Google Cloud console.
   • DOCKER_PASSWORD_SECRET_NAME: The secret name correspondingto your Docker password. You can get the secret name from theSecret Manager page in the Google Cloud console.
   • DOCKER_PASSWORD_SECRET_VERSION: The secret versionof your Docker password. You can get the secret version by clicking on asecret name on theSecret Manager page in the Google Cloud console.

3. Use the build config file tostart a build using the command lineor toautomate builds using triggers.

Example: Accessing secrets from scripts and processes

secretEnv field adds the value of the secret to the environment and you canaccess this value via environment variable from scripts or processes:

steps:-name:python:slimentrypoint:pythonargs:['main.py']secretEnv:['MYSECRET']availableSecrets:secretManager:-versionName:projects/$PROJECT_ID/secrets/mySecret/versions/latestenv:'MYSECRET'

{"steps":[{"name":"python:slim","entrypoint":"python","args":["main.py"],"secretEnv":["MYSECRET"]}],"availableSecrets":{"secretManager":[{"versionName":"projects/$PROJECT_ID/secrets/mySecret/versions/latest","env":"MYSECRET"}]}}

The following contents ofmain.py prints the first five characters of the secret:

importosprint(os.environ.get("MYSECRET","Not Found")[:5],"...")

Example: authenticating to Docker

In some situations, before interacting with Docker images, your build would needto authenticate to Docker. For example, Docker authentication is required forbuilds to pull private images and push private or public images to Docker Hub.In these cases, you can store your Docker username and password in Secret Managerand then configure Cloud Build to access the username and passwordfrom Secret Manager. For instructions on doing this seeInteracting with Docker Hub images.

Example: GitHub pull request creation

Another example where you might want to configure your build to access a sensitiveinformation from Secret Manager is for creating a GitHub pull requestin response to builds. To do this:

• Create aGitHub token.
• Store the GitHub token in Secret Manager.
• In your build config file:
  • After all the buildsteps, add anavailableSecrets field to specify thesecret version and the environment variable to use for the GitHub token.
  • Add a build step to invoke thecommand to create a GitHub pull request.
• Create aGitHub app triggerand use the build config file to invoke the trigger.

The following example config file shows how to create a GitHub pull request usingthe GitHub token:

steps:-name:'launcher.gcr.io/google/ubuntu1604'id:Create GitHub pull requestentrypoint:bashargs:--c-curl -X POST -H "Authorization:Bearer $$GH_TOKEN" -H 'Accept:application/vnd.github.v3+json' https://api.github.com/repos/GITHUB_USERNAME/REPO_NAME/pulls -d '{"head":"HEAD_BRANCH","base":"BASE_BRANCH", "title":"NEW_PR"}'secretEnv:['GH_TOKEN']availableSecrets:secretManager:-versionName:projects/PROJECT_ID/secrets/GH_TOKEN_SECRET_NAME/versions/latestenv:GH_TOKEN

{"steps":[{"name":"launcher.gcr.io/google/ubuntu1604","id":"Create GitHub pull request","entrypoint":"bash","args":["-c","curl -X POST -H \"Authorization:Bearer $$GH_TOKEN\" -H 'Accept:application/vnd.github.v3+json' https://api.github.com/repos/GITHUB_USERNAME/REPO_NAME -d '{\"head\":\"HEAD_BRANCH\",\"base\":\"BASE_BRANCH\", \"title\":\"NEW_PR\"}'    ],    "secretEnv": ['GH_TOKEN']}],"availableSecrets": {  "secretManager": [  {    "versionName": "projects/PROJECT_ID/secrets/GH_TOKEN_SECRET_NAME/versions/latest",    "env": "GH_TOKEN"  }  ]}}

Replace the placeholder values in the preceding commands with the following:

• PROJECT_ID: Theproject ID or project number of theGoogle Cloud project where you've stored your secrets.
• GITHUB_USERNAME: The GitHub username of the repositoryowner.
• REPO_NAME: The name of the GitHub repository.
• HEAD_BRANCH: The name of the branch where the changesare implemented. For cross-repository pull requests in the same network, namespacehead with a user like this:username:branch.
• BASE_BRANCH: The name of the branch you want the changespulled into. This should be an existing branch on the current repository. Youcannot submit a pull request to one repository that requests a merge to a baseof another repository.
• GH_TOKEN_SECRET_NAME: The secret name correspondingto your GitHub token.
• NEW_PR: The new pull request you want to create.

Configuring builds to access non-UTF-8 secrets from Secret Manager

1. In your build config file, add a build step to access the secret version in Secret Managerand store it in a file. The following build step accessessecret-nameand stores it in a file nameddecrypted-data.txt:

   YAML

   steps:-name:gcr.io/cloud-builders/gcloudentrypoint:'bash'args:['-c',"gcloudsecretsversionsaccesslatest--secret=secret-name--format='get(payload.data)'|tr'_-''/+'|base64-d >decrypted-data.txt"]

   JSON

   {"steps":[{"name":"gcr.io/cloud-builders/gcloud","entrypoint":"bash","args":["-c","gcloud secrets versions access latest --secret=secret-name --format='get(payload.data)' | tr '_-' '/+' | base64 -d >decrypted-data.txt"]}]}

2. Use the file with the decrypted data in a build step. The followingcode snippet usesdecrypted-data.txt to login to a privateDocker registry:

   YAML

   steps:-name:gcr.io/cloud-builders/gcloudentrypoint:'bash'args:['-c',"gcloudsecretsversionsaccesslatest--secret=secret-name--format='get(payload.data)'|tr'_-''/+'|base64-d >decrypted-data.txt"]-name:gcr.io/cloud-builders/dockerentrypoint:'bash'args:['-c','dockerlogin--username=my-user--password-stdin <decrypted-data.txt']

   JSON

   {"steps":[{"name":"gcr.io/cloud-builders/gcloud","entrypoint":"bash","args":["-c","gcloud secrets versions access latest --secret=secret-name --format='get(payload.data)' | tr '_-' '/+' | base64 -d > password.txt"]},{"name":"gcr.io/cloud-builders/docker","entrypoint":"bash","args":["-c","docker login --username=my-user --password-stdin <decrypted-data.txt"]}]}

   Note: To use the secret in an environment variable, you must prefix the variablename with an underscore "_" and escape the value using '\('. For example:_VARIABLE_NAME=$(cat password.txt) && echo -n \)_VARIABLE_NAME.

3. Use the build config file tostart a build using the command lineor toautomate builds using triggers.

What's next

• Learn how to useencrypted credentials in builds.
• Learn how toaccess private GitHub repositories.