Skip to main content

Promotions

Video Tutorial: How to use promotions

Promotions connect pipelines to implement continuous delivery and deployment, or other types of automation, such as blue-green deployments and canary deployments.

This page explains promotions, how to use them to connect pipelines, and what settings are available.

Connecting pipelines​

If your project contains multiple pipelines, you can use promotions to chain them.

Using promotions, we can create a tree-like structure where pipelines branch off from other pipelines. The root of the tree is the default pipeline located at .semaphore/semaphore.yml.

Promoted pipelines are typically used for continuous delivery and continuous deployment. The following example shows the default pipeline branching into two continuous delivery pipelines: production and development. In each of these, we define the sequence of jobs needed to deploy the application in the respective environment.

A workflow with 3 pipelines

Promotion triggers​

Triggering a promotion means starting the next pipeline in the chain. There are three ways of triggering a promotion:

  • Manual promotions: this is the default. Start the next pipeline manually
  • Auto promotions: automatically start a promotion based on predefined conditions
  • Parameterized promotions: allow you to pass values as environment variables into the next pipelines, enabling pipeline reuse for different tasks

How to add promotions​

Promotions are defined as pointers to the next pipelines in the chain. You can create multiple promotions and nest pipelines as needed.

  1. Press +Add Promotion
  2. Set a descriptive name for the promotion
  3. Configure the new pipeline and add jobs as needed

Adding a manual promotion

Press Delete Promotion to completely delete the promotion along with all its child pipelines.

Automatic promotions​

Automatic promotions start a pipeline based on user-defined conditions.

After adding a promotion, you can set automatic conditions. Whenever Semaphore detects that these conditions are met, the child pipeline automatically starts.

  1. Open the promotion you want to autostart
  2. Enable the checkbox Enable automatic promotion
  3. Type in the start conditions

Setting autostart conditions on a promotion

Tagged promotions​

Many teams use Git tags to manage their release cycles. To auto-trigger a promotion with tags, you can use Perl Compatible Regular Expressions.

For example:

  • tag =~ '.*' matches all tags. The presence of any Git tag alone is enough to match the condition
  • tag =~ '^v1\.' matches any tag starting with "v1"

You can mix tags and other conditions to trigger promotions with a high level of control.

The following example shows how to trigger a deployment promotion when all tests have passed and there is a Git tag starting with "v1".

Using tags for promotions

Parameterized promotions​

Parameterized promotions allow you to propagate environment variables across all jobs in the next pipeline.

Use parameters to reduce pipeline duplication. For example, if you create a parameterized pipeline that reads the target environment from a variable, you can reuse it to deploy an application to both production and testing environments. Parameters work with both manual and automatic promotions.

note

Parameterized promotions cause Semaphore to run an initialization job before the pipeline starts.

How to add parameters​

To add parameters to a promotion with the workflow editor, follow these steps:

  1. Select the promotion to which you want to add parameters

  2. Click +Add Environment Variable

    Add parameter to promotion

  3. Set the variable name

  4. Set an optional description

  5. Set optional valid options. Leave blank to input value as freeform text

  6. Enable the "This is a required parameter" checkbox if the parameter is mandatory

  7. Set a default value (only when the parameter is mandatory)

  8. Add more parameters as needed

    Setting up parameters

info

When a pipeline is triggered with automatic promotions the parameter values are automatically filled following these rules:

  • Mandatory parameters use the default value
  • Optional parameters are left blank

Promoting with the UI​

Once you have added a parameter, you can select its value from the Semaphore UI.

  1. Press the promotion button
  2. Select or type in the value. Optional parameters can be left blank
  3. Press Start promotion

Selecting a parameter value from options

Promoting with the API​

You can pass parameter values to the promotion when it's triggered using Semaphore API the to trigger promotions. If a promotion is forbidden by the environment, you will receive an HTTP 400 Bad Request response with a reason in the body.

The following is an example of a curl call that includes parameters:

curl -H "Authorization: Token {api_token}" \
 -d "name={promotion_name}&pipeline_id={parent_pipeline_id}&{param_1_name}={param_1_value}&{param_2_name}={param_2_value}" \
 -X POST "https://{org_name}.semaphoreci.com/api/v1alpha/promotions"

Accessing values in jobs​

Parameters are exported as environment variables in all the jobs contained in the promoted pipeline.

You can access the parameter value by directly using the environment variable in your commands.

Using parameters a environment variables in jobs

Accessing values in pipelines​

You can access parameter values in pipeline elements like the pipeline name.

Parameters can be accessed in the pipeline configuration using the ${{parameters}} namespace. For example, if you defined a parameter called ENVIRONMENT, you can read its value in the pipeline config as:

${{parameters.ENVIRONMENT}}

Parameters are available in the following places:

Parameter value is expanded in the pipeline name

Deployment targets​

Video Tutorial: How to Use Environments

Deployment targets (also known as Environments) provide additional controls over pipelines. You can limit who can trigger a pipeline and when, or define fine-grained secrets and environment variables.

note

Environments were formerly known as "Deployment Targets".

Overview​

Environments allow you to tightly control promotions, preventing unauthorized users from starting a critical pipeline. Additionally, deployment targets can restrict branches, and pull requests, and protect secrets.

Environments also provide a convenient way to view the history of your deployments.

Configuring a deployment target is a two-step process:

  1. Create a deployment target
  2. Associate the target with a promotion

How to create an environment​

Environments can be defined once and used in multiple promotions in a project.

To create an environment, navigate to your Semaphore project and:

  1. Go to the Deployment Targets tab

  2. Press Create your first Deployment Target

    Creating a deployment target

  3. Fill in the deployment details:

    • Name of the deployment
    • Optional description
    • Optional URL of the deployed application
    • Optional bookmarks

  4. Press Next

    Example deployment target

The bookmarks are useful when using parameterized promotions. You can add up to three bookmarks matching the names of the parameters in the promotions. Think of the bookmarks as additional filters available in the deployment history view.

Credentials and secrets​

Credentials are a restricted type of secrets that are only accessible to authorized members of your organization.

In the second part, you can define environment variables and upload files that will be accessible to the promoted pipelines. All information will be encrypted once saved.

Credentials are optional. Go to the next step if you don't need them.

  1. Set the environment variable name and value

  2. Add more variables as needed

  3. Upload a file and set where to put it in the agent

  4. Add more files as needed

  5. Press Next

    Show me

    Setting up credentials for the deployment target

Granular permissions​

Available On
PlansScaleup

In the "Who can deploy?" section, you can define the users and roles that can manually start the promotion. Granular permissions are optional. You can go to the next section if you don't need to restrict access to the promotion.

By default, everyone can start the promotion linked to this environment. To restrict access:

  1. Select Allow only particular users to deploy

  2. Optionally, select the roles that can deploy from the list

  3. Optionally, select the members of your organization that can deploy

  4. Uncheck the Allow automatic promotions from target option to disallow automatic promotions

  5. Press Next

    Show me

    Configuring granular access permissions for the deployment target

Git-based permissions​

In the fourth part, you can restrict which Git branches and tags are allowed to start a promotion. Here, you can also block promotions coming from pull requests. This section is optional.

To restrict Git-based access:

  1. Select which branches are enabled for promotions: all, none, or a list of allowed branches

  2. Select which Git tags are enabled: all, none, or a list of allowed tags

  3. Enable or disable pull requests from triggering promotions

  4. Press Next

  5. Press Create

    Show me

    Setting up Git-based permissions

Once done, you can see the created environment in the Deployments tab.

Exact match or regular expressions?

Branches and tags can be matched in two ways:

  • Exact match: strings must match exactly
  • Regex match: strings are matched using Perl-compatible regular expressions. See the Erlang re module documentation to see more details on the syntax

How to view deployment history​

The Deployment tab allows you to track your previous deployments. In this tab, you can see:

  • Who started the last deployment
  • Which commit was used
  • Which workflow the deployment belongs to

You can also stop a running pipeline or rerun a promotion if you have the rights to do so.

Deployment history

Press View full history to see the latest deployments in reverse chronological order.

Deployment history details

Use Newer and Older buttons to navigate to other pages. You can also jump to a specific date.

You can also filter deployments by:

  • Type: View branches, tags, pull requests, or everything
  • Author: Everyone or just you
  • Origin: Branch, tag, or pull request
  • Promotion parameters: These are the bookmarks added to the environment target

To filter using promotion parameters, type the value of the parameter and press Enter. This feature is useful when you have parameterized promotions.

Deployment history filtered by parameters

How to target promotions​

Once you have created at least one environment, you can associate it with a promotion. This creates a targeted promotion.

Deployment target created

Press Edit workflow to open the visual editor and:

  1. Select or create a promotion
  2. In Deployment target, select the target from the dropdown list

Select No target to remove the association between the deployment target and the promotion. Associating a deployment target with a promotion

Promoting environments​

Promotions with attached environments show a lock icon next to the promotion button. The icon will be unlocked if you have permission to start the promotion or locked if you don't.

The promotion is unlocked. Press the promotion button to start the next pipeline. Promotion is unlocked

warning

Anyone with write access to the repository can edit the pipeline file and remove the environment in the promotion.

Help! I can't start a promotion​

Once a promotion is targeted, you may be locked out from starting it. The most common reasons that a promotion appears as blocked are:

  • You don't have the correct permissions to deploy to the bound environment
  • You are on a Git branch, tag, or pull request that isn't allowed
  • You are not logged in, or you are viewing a build of a public project
  • The environment is deactivated or deleted

Promoting environments via API​

You can also use the Semaphore API to trigger promotions. If a promotion is forbidden by the environment, you will receive an HTTP 400 Bad Request response with a reason in the body.

See also​