can be used to automate the deployment of websites, signing of packages, and more, through the use of build secrets. You can upload the secret keys necessary to run your automation on the web, then make these secrets available to CI jobs.

#Our example build manifest

Let's say we have a git repo with static HTML files that we'd like to deploy by sending them to our web server. A simple build manifest might look like this:

image: alpine/edge
- rsync
- upload: |
    rsync -r*

This is straightforward enough — but it won't work because the build won't have authorization to log into

#Generating the secrets & preparing our server

This step will naturally be somewhat different depending on your particular server configuration. You should start by creating a deploy user:

useradd -m deploy

Let's also give this user permission to update /var/www:

usermod -aG www-data deploy
chgrp www-data /var/www
chmod g+rwx /var/www

And finally, let's log in as "deploy" and generate an SSH key:

sudo su deploy
# accept the defaults
cat .ssh/ >> .ssh/authorized_keys
cat .ssh/id_rsa

This will print out the new SSH private key. Copy this to your clipboard for the next step.

#Adding your secret to

Go to the secret management dashboard and select "SSH key" for secret type, then paste your key into the text box. Click "submit" — and your new secret should show up on the right, along with its UUID.

This UUID is used to uniquely identify this secret in build manifests. Copy this UUID for the next step.

#Adding secrets to your build manifest

This part is easy. We can simply add a list of secret UUIDs we want to be available in this build.

image: alpine/edge
- c262b238-41de-4b43-a2f9-460424dd7896
- rsync
- upload: |
    rsync -r*

It's as easy as that! will install this SSH key into your build environment when you submit this build manifest. However, it will only work for builds submitted with your user — if someone else copies and pastes this build manifest, the SSH key will not be added to their build VM.

#Controlling the use of secrets

The easiest way to control whether or not secrets work in your build is by turning them off via the API: if you set secrets=false in POST /api/jobs, the secrets will not be resolved. This is automatically done in many places where the build manifest could be modified by an untrusted party — for example, disables secrets when submitting build manifests from GitHub pull requests.

However, some degree of responsibility lies with you for keeping your secrets secure. Avoid writing build manifests that would print your secrets to the logs, particularly if using file secrets. If a secret is ever leaked in this manner, you should consider that secret compromised — revoke it and generate a new one.

Want to learn more about Check out all of our tutorials.

Other resources:

About this wiki

commit b345d3de11bc0e7dbf344de75c30cf7e3620fa7b
Author: Conrad Hoffmann <>
Date:   2022-05-12T10:04:02+02:00

Add link to package installation instructions

Besides being a bit more convenient, it also adds a little emphasis to
this specific bullet point :)
Clone this wiki (read-only) (read/write)