The enterprise edition supports loading secrets from vault. Note that vault credentials must be globally configured by an administrator. Vault secrets are declared in your yaml configuration file and loaded at runtime.

Example configuration with vault secrets:

pipeline:
  build:
    image: golang
    commands:
      - go test
      - go build
  publish:
    image: plugins/docker
    repo: octocat/app
    secrets: [ docker_username, docker_password ]

secrets:
  docker_username:
    path: secret/docker_username
  docker_password:
    path: secret/docker_password

Secrets are added to vault using the vault command line utility. Secrets can be written to any valid path. See the below example:

vault write secret/docker_username value=...
vault write secret/docker_password value=...

The secrets paths can then be included in your yaml configuration:

secrets:
  docker_username:
    path: secret/docker_username
  docker_password:
    path: secret/docker_password

The vault secrets are passed to your pipeline steps by name. The below example requests the named secrets are passed to the pipeline step:

pipeline:
  build:
    image: golang
    commands:
      - go test
      - go build
  publish:
    image: plugins/docker
    repo: octocat/app
+   secrets: [ docker_username, docker_password ]

secrets:
  docker_username:
    path: secret/docker_username
  docker_password:
    path: secret/docker_password

Alternate Names

In some cases the secret names in your vault instance may not match the names expected by the secrets. The secret names can be mapped to the correct values using the below syntax.

pipeline:
  build:
    image: golang
    commands:
      - go test
      - go build
  publish:
    image: plugins/docker
    repo: octocat/app
    secrets:
+     - source: username
+       target: docker_username
+     - source: password
+       target: docker_password

secrets:
  docker_username:
    path: secret/docker_username
  docker_password:
    path: secret/docker_password

Restricting Access

You can restrict access to vault secrets based on repository name using the repo attribute. This is a comma-separated list with glob support.

vault write secret/password value=<value> repo=octocat/spoon-knife,octocat/hello-world
vault write secret/password value=<value> repo=octocat/hello-world
vault write secret/password value=<value> repo=octocat/*

Restricting Events

You can restrict access to vault secrets based on hook event using the event attribute. This may be a string or comma-separated list:

vault write secret/password value=<value> event=push
vault write secret/password value=<value> event=push,tag
vault write secret/password value=<value> event=push,pull_request

Restricting Images

You can restrict access to vault secrets to specific docker images using the image attribute. This may be a string or comma-separated list:

vault write secret/password value=<value> image=plugins/docker
vault write secret/password value=<value> image=plugins/ecr,plugins/s3

Questions?

We are always happy to help with questions you might have. Search our documentation or check out answers to common questions. You can also post questions or comments to our community forum.