# Managing Secrets

When using secrets in your pipelines it is strongly recommended that you store them in your Agent environment hook. This means that only people with access to your Agent infrastructure will ever see these secrets, and they won't leak into your build environment variables or logs. 

If you're using the AWS Elastic Stack, the Agent environment hook is stored in an automatically created S3 bucket.

<%= toc %>

## Storing secrets in Agent hooks

You can store secrets in your agent evironment hook using environment variables. These variables should never be exported anywhere else, like inside a script or as variables in other places in the pipeline. See section 3 for further information about places not to store secrets. 

The following example Agent environment hook stores AWS S3 credentials for artifact access:

```bash
set -eu

export BUILDKITE_S3_DEFAULT_REGION="eu-central-1"
export BUILDKITE_S3_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
export BUILDKITE_S3_SECRET_ACCESS_KEY='wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY'
export BUILDKITE_S3_ACL="private"
export BUILDKITE_S3_ACCESS_URL="https://buildkite-artifacts.example.com/"
export BUILDKITE_ARTIFACT_UPLOAD_DESTINATION="s3://name-of-your-s3-bucket/$BUILDKITE_JOB_ID"
```

You can reference these environment variables in your command step scripts and the agent will be able to interpolate them at runtime. 

For example, in the following script the `buildkite-agent artifact upload` command uses the defined variables to upload to your custom S3 bucket:

```bash

```

Custom environment variables work in the same way. In the following example hook, the new variable 'SERVICE_ACCESS_PASSWORD' is exported:

``` bash
set -eu

export SERVICE_ACCESS_PASSWORD="fish-are-cool"
```

The 'SERVICE_ACCESS_PASSWORD' variable can then be used in any command step scripts.

## Setting AWS Elastic Stack secrets 

Using Agent environment hooks with the AWS Elastic Stack is different to configuring environment hooks on other platforms. The evironment hooks is loaded into the agent on a per-pipeline basis from the stack's S3 bucket.   

Save your secrets in an environment file in the S3 bucket. The following shell code creates a file containing a docker password variable, uploads it to the S3 secrets bucket, and encrypts it with KMS:

```shell
# Create the file
echo "export DOCKER_LOGIN_USERNAME=the-user-name
export DOCKER_LOGIN_PASSWORD=the-password" > myenv
# Upload to S3 and encrypt
aws s3 cp --acl private --sse aws:kms myenv "s3://${SecretsBucket}/env"
# Remove the original file
rm myenv
```

Setting these particular variables in the Agent environment hook will perform a docker login before each pipeline step is run, allowing you to docker push to them from within your build scripts.

## Storage locations for secrets

No:
- pipeline settings environment variables text box
- inside a script
- in a docker image

Yes:
- in a secret store
- in your agent's environment hook
- in an s3 env file
Add outline for secrets page
Add outline for secrets page
