Skip to main content

Add Secrets

Shipyard allows you to define secrets (plaintext or hidden) that are injected into your Environments. This keeps your projects secure so you won't need to worry about storing this data in any of your repositories.

Shipyard injects secrets at:

  1. Build time (called build arguments) OR
  2. Runtime (called environment variables)

User-defined​

You can add secrets individually:

Add application secrets to Shipyard individually

Or use Batch Upload to set multiple secrets at once:

Batch upload multiple secrets to Shipyard

When batch uploading, copy the contents of your .env file and paste them into the modal.

If you're not using an .env file to store your variables, run something like the following command to output your secrets to your terminal:

env | grep 'DEV'
note

This returns all env vars whose key matches DEV. Adjust your search term accordingly.

note

You can also combine different secrets in the Docker Compose.

compose.yml
environment:
    - STRING_INTERPOLATION=https://${MY_CUSTOM_DOMAIN} # MY_CUSTOM_DOMAIN is defined in Shipyard UI
    - PREFIX=https://
    - ENV_VARS_INTERPOLATION=${PREFIX}${MY_CUSTOM_DOMAIN}

Build arguments​

Build arguments are secrets accessible only during the build process.

Shipyard only passes build args which are defined in the Docker Compose file, and must use the same name as they do in your .env file, in this case APP_ID:

.env
APP_ID=124abc

compose.yml
build:
  context: .
  args:
    - APPLICATION_ID: ${APP_ID}

So if you add another build time arg in the Shipyard UI, like API_KEY, you must add it to your Compose file too:

.env
  APPLICATION_ID=124abc
+ API_KEY=asdAakl344kl4l

compose.yml
  build:
    context: .
    args:
      - APPLICATION_ID: ${APP_ID}
+     - MY_API_KEY: ${API_KEY}
Manage application secrets in Shipyard

For illustration purposes, differently named vars and args above. You can use the same name for the env var as the arg, i.e. APPLICATION_ID=124abc and APPLICATION_ID: ${APPLICATION_ID}.

Learn more: Docker Compose docs on Build Arguments.

Secrets inheritance​

There is an inheritance scheme when setting secrets for Environments. There is a top-level Base Environment, which can have many child PR Environments. Secrets defined in the Base Environment are inherited by the PR Environments by default.

React Flow

Override secrets​

It is also possible to override secrets from the Base Environment in the PR Environments, for example, if you are rotating API keys for some external service and want to try them out. It is also possible to add additional new secrets to the PR Environments.

React Flow

Any secrets you add or update in a PR Environment also need to be added to the Base Environment before merging the PR.


Base Environment secrets in Shipyard

The Env Vars button at the top of a Shipyard Base Environment is used to modify secrets across all Environments. To override secrets for an individual Environment, select the Env Vars option in that respective Environment's kebab menu.

Per-service secrets​

You can also set secrets per service, for example, to limit access to certain secrets, or if two different services use a secret with the same name but need different values (ex: service-a and service-b both expect API_KEY but with different values).


Set per service secrets in Shipyard

Shipyard-injected​

In addition to allowing users to set custom secrets, Shipyard injects the following secrets into projects by default:

  • SHIPYARD_DOMAIN: The active domain of the project. If the project is a remote deploy and has a custom domain, this is its value. Otherwise, the active domain of the project is injected.
  • SHIPYARD_DOMAIN_<SERVICE_NAME>: The active domain of each service will also be injected into each container. If you have no services on a unique domain, these will all match SHIPYARD_DOMAIN.
  • SHIPYARD_EPHEMERAL: true if the project is ephemeral, false if it is a remote deploy.
  • SHIPYARD_COMMIT: The running project's latest commit hash.
Default Shipyard-injected application secrets