Docs Navigation

Sharing build configurations across multiple projects

Every project can be configured with environment variables and configuration files. If you want to share environment variables and configuration files between two or more projects, your organization can set up a secret and attach it to multiple projects.

A secret is a collection of environment variables and configuration files in an organization that can be shared between projects.

An ideal workflow for secrets is for an admin in the organization to set up several configurations containing organization wide secrets necessary for building your projects. Once the shared configurations are set up, admins and owners can share it with their teams.

For example, if you have have a set of environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY) for accessing a your resources on AWS, you can create a secret called AWS Access Keys.

To use entries from the secret, you need to add it to your teams and to attach it to your project.

Creating a secret and adding it to your teams

Any admin or owner in your organization can create a secret, and fill it environment variables and configuration files. When created, the shared configuration is added to the owners team only.

Following this, admins and owners in the organization can add the shared configuration to their teams to allow non-admin users to use it on their projects.

Using a secret in your project

To use a secret in your project, you must be a member of a team that has the secret.

To use the entries from the secret in your projects, you need to attach the secret to your project, and select the environment variables you want to use from the secret.

Setting up a secret via API v2

First, you need to find your API credentials to access your organization via the API. You can find your API credentials at the bottom of your your users settings page. To learn more about API authentiacation read the API v2 authentiacation guide.

export AUTH_TOKEN=<token>

With the authorization token in place, let's continue by creating a secret in our organization. For this, you will need to be either an admin or an owner in your organization.

export ORG_USERNAME=<org_name>
export SECRET_NAME=<secret_name>

curl -X POST \
     -H "Authorization: Token ${AUTH_TOKEN}" \
     -d "{ \"name\" : \"${SECRET_NAME}\" }" \

# Store the returned `id` in an environment variable:

export SECRET_ID=<secret_id>

Adding entries to the secret

You can add environment variables and configuration files to your secret.

To add an environment variables to the secret:

export ENV_VAR_NAME=<name>
export ENV_VAR_CONTENT=<content>

curl -X POST \
     -H "Authorization: Token ${AUTH_TOKEN}" \
     -d "{ \"name\" : \"${ENV_VAR_NAME}\" , \"content\" : \"${ENV_VAR_CONTENT}\" }" \

To add a configuration file to the secret:

export FILE_PATH=<path>
export FILE_CONTENT=<content>

curl -X POST \
     -H "Authorization: Token ${AUTH_TOKEN}" \
     -d "{ \"path\" : \"${FILE_PATH}\" , \"content\" : \"${FILE_CONTENT}\" }' \

Adding secret to your teams

Before we can use the secret in projects, we need to add them to our teams so that our team members can use them.

Let's find the team's id, and connect the secret with the team:

# List teams in our organization

curl -X GET \
     -H "Authorization: Token ${AUTH_TOKEN}" \

# Connect the secret with our team

export TEAM_ID=<team_id>

curl \
 -X POST \
 -H "Authorization: Token ${AUTH_TOKEN}" \

Using secrets in projects

Continuing with the previous setup, any member of the team can add the secret to his projects. As a team member, you can attach the secret to a project and use the provided environment variables from secret:

# First, we find the id of the project

export PROJECT_NAME=<project_name>

curl \
 -X GET \
 -H "Authorization: Token ${AUTH_TOKEN}" \

# Store the id of the project

export PROJECT_ID=<project_id>

# Connect the secret to the project

curl \
 -X POST \
 -H "Authorization: Token ${AUTH_TOKEN}" \

After this step, you should see the attached environment variable on your project.

Shared Environment Variables

The next build on our project will include the connected environment variable.

Semaphore Docs are open source — Edit on GitHub


Occasional lightweight product and blog updates. Unsubscribe at any time.

2009-2017 © Rendered Text. All rights reserved. Terms of Service, Privacy policy, Security.