Workflows

A workflow is a series of steps to build, test, release, or deploy your application. This page explains workflows, how they are triggered, and their settings.

tip

If this is your first time using Semaphore, check out Guided Tour.

Overview

In the context of Continuous Integration and Delivery (CI/CD) a workflow implements automation to manage the development cycle from code to deployment.

Workflows in Semaphore consist of one or more pipelines. A pipeline defines the sequence of tasks to achieve goals like build, release, or deploy to production.

Before you can run a workflow in Semaphore you need:

• A Semaphore account
• A repository on GitHub or BitBucket
• A Semaphore project linked to the repository
• One or more pipelines

The project page shows all the recent workflows for the project.

Visual workflow editor

Video Tutorial: How to use the worflow builder

You can define most aspects of your workflows using the visual editor.

To access the editor, open one of your projects on and press Edit Workflow. All your changes are stored as YAML pipeline definitions on your Git repository. You can make changes using the visual editor, or edit the YAML directly by clicking on the pipeline YAML file.

See the jobs page to learn how to define jobs and blocks.

Workflow triggers

The following events or actions trigger workflows by default:

• Pushing commits into any branch
• Pushing Git tags
• Changing any pipelines
• Manually re-running workflows
• Running pipelines using Tasks

Additionally, you can configure workflows to be triggered by:

• Pull requests
• Pull request on forked repositories

The reason for the trigger can be determined at runtime by examining the Semaphore environment variables in the job. See the environment variable reference page for more details.

How pull requests are handled

Semaphore starts a workflow for every push to a pull request originating from a forked repository. For security reasons, secrets are disabled in jobs triggered in this way. You can create an allow list with the secrets you want to expose in the project settings.

note

Instead of pushing the HEAD commit to the pull request, Semaphore uses the MERGE commit between the source and the upstream branch. You can find the SHA of the HEAD commit of the Pull Request in the SEMAPHORE_GIT_PR_SHA environment variable.

How to customize triggers

Triggers are configured in the project settings. To change what actions can trigger a workflow, follow these steps:

1. Open your project on Semaphore

2. Go to the Settings tab

   

3. In the General section scroll down to What to build

4. Change the settings and press Save

Selecting Do not run on any events disables all triggers, effectively pausing the project. You can, however, still run workflows manually or with tasks.

Selecting Run on allows you to configure what triggers are enabled for the project.

• The Branches option allows you to run workflows on all branches or configure an allow list with branch names. Regular expressions are supported
• The Tags options work the same but for Git tags

• Enabling Pull requests option allows Semaphore to run workflows on pull requests originating in the same repository
• The Forked pull request works the same for pull requests originating from forked pull requests. To prevent security leaks, you can configure a list of allowed secrets and GitHub/BitBucket usernames that can trigger workflows in this way

How to skip commits

If you don't want to start a workflow, type one of the following strings in the commit message.

• [ci skip]
• [skip ci]

For example, this push does not trigger a Semaphore pipeline execution, it is completely ignored:

Skipping a commit

git add -A
git commit -m "[skip ci] Initial commit"
git push origin main

notes

• Skip doesn't work when pushing tags
• Be careful when squashing commits as they can contain skip messages