app logs command

What are Secrets?

Secrets are sensitive bits of information like OAuth tokens, secret keys or API keys - information that you need in your service code, but shouldn't commit to your source code. In the Copilot CLI, secrets are passed in as environment variables (read more about developing with environment variables) but they're treated differently, due to their sensitive nature.

How do I add Secrets?

Adding secrets currently requires you to store your secret as a secure string in AWS Systems Manager Parameter Store (SSM), then add a reference to the SSM parameter to your manifest.

We'll walk through an example where we want to store a secret called GH_WEBHOOK_SECRET with the value secretvalue1234 for the application kudos-app and the environment test. First, store the secret in SSM like so:

aws ssm put-parameter --name GH_WEBHOOK_SECRET --value secretvalue1234 --type SecureString\
                      --tags Key=copilot-application,Value=kudos-app Key=copilot-environment,Value=test

This will store the value secretvalue1234 into the SSM parameter GH_WEBHOOK_SECRET. It's important to tag this parameter with your Copilot app name and environment, otherwise your service won't have access to it. Next, we'll modify our manifest file to pass in this value:

secrets:                      
  GITHUB_WEBHOOK_SECRET: GH_WEBHOOK_SECRET  

Once we deploy this update to our manifest, we'll be able to access the environment variable GITHUB_WEBHOOK_SECRET which will have the value of the SSM parameter GH_WEBHOOK_SECRET, secretvalue1234.

This works because ECS Agent will resolve the SSM parameter when it starts up your task, and set the environment variable for you.

❇️ We're going to make this easier!

There are a couple of caveats - you have to store the secret in the same environment as your service. Some of our next works is to add a secrets command that lets you add a secret without having to worry about which environment you're in or how SSM works.