Creating a Workflow

Before you create a workflow, you need to select the Wercker application to which the workflow will apply, then click on the Workflows tab.

Workflow 1

The Workflows Tab

The Workflow tab is divided into two sections. At the top is the editor, where you create and edit workflows. Below that is the Pipelines section, where you create and edit workflow pipelines.

Workflow 2

Workflow pipelines represent the pipelines in your wercker.yml document, but they include some added properties which are used within the workflow. It is for this reason that you must create and edit pipelines in the Workflows tab. Since a workflow is made up of pipelines, you need to create the pipelines that it will use before you create the workflow.

Creating Workflow Pipelines

Before you create workflow pipelines, you should create the corresponding pipelines in your project’s wercker.yml document, since each workflow pipeline will reference a wercker.yml pipeline.

To create a workflow pipeline, click on the Add new pipeline button in the Workflows tab—This will bring up the Create new pipeline screen.

Workflow 3

Create New Pipeline

In the Create new pipeline screen, enter the following information:


This is the name that will appear in the Pipelines list, and in the workflow diagram. It does not need to be identical to the name of the wercker.yml pipeline which it references, but it should clearly indicate the pipeline’s function.

YML Pipeline Name

This is the name of the pipeline in your project’s wercker.yml document. It needs to be exactly the same as the name in wercker.yml. When the workflow pipeline is triggered, it will cause the wercker.yml pipeline to execute. Note that a wercker.yml pipeline can be referenced by more than one workflow pipeline.

Hook Type

The hook is the action which triggers the workflow pipeline.

The default option sets the pipeline to be triggered by another pipeline in the workflow. You can place a pipeline with the default hook anywhere in the workflow.

The Git push hook sets the pipeline to be triggered by a push from Git. This means that the pipeline will be the first one in a workflow. When you create a pipeline with a Git push hook, it is automatically listed as the start of a new workflow in the Editor.

Workflow 4

After you have entered the pipeline names and hook type, click on the Create button to bring up the pipeline details screen.

Pipeline Details

The pipeline details screen allows you to enter or edit detailed information regarding the pipeline.

Pipeline Environment Variables

These are optional environment variables which will be available only within the scope of the workflow pipeline. They can be used to represent such things as device addresses, passwords, and SSH keys, as well as any other environment variable which is relevant to the pipeline. To create an environment variable, you must enter the name of the variable in the Key field, and the value in the Value field. Each variable must have both a Key and a Value.

Workflow 5

After you have entered both a Key and Value, you can click on the Add button to create the variable. The Add button then changes to a Delete button. If you make any changes to the Key or Value fields after you have created the variable, the Delete button changes to a Save button.

If you click on the Protected checkbox, the contents of the Value field will be hidden from view after you click on Add. You can, however, overwrite a protected value—The new value will also be protected from view after you save the changes.

SSH Keys

Generating SSH Keys

Workflow 6

Click on Generate SSH Keys to generate a pair of SSH keys. When you do this, you will see a dialog box allowing you to enter an SSH key name, select the size of the key (2048 or 4096 bit), and generate the key.

Workflow 7

Generate New SSH Key Dialog Box

Generating the key automatically creates two keys, one public, and one private (designated by the name that you entered, with _PUBLIC and _PRIVATE appended as required).

Workflow 8

The value field for the public key contains the string “ssh-rsa” followed by the key itself. You can expand the field to view the entire key. The private key is protected, and is thus hidden from view. Note, however, that either key can be overwritten or deleted.


The Settings section of the pipeline details page allows you to change the Name and YML Pipeline name for the pipeline. You can also click on the Report to SCM checkbox if you want the Software Configuration Management role to be notified when the pipeline is triggered.

Workflow 9

If you make any changes to this section, click on the Update button to apply them.

Permission Level

In the Permission level section, you can set the minimum permission level required to execute the pipeline. The permission levels are public, Execute pipelines, Execute & Manage pipelines, and admin. Public is the most permissive level; the other three levels correspond to the Permission levels which you can grant in the Wercker Access tab.

Workflow 10

For more information, see Roles and Permissions.

Editing and Creating Workflows

By default, each project will have a Build workflow (based on the Build pipeline in wercker.yml), consisting only of the build pipeline itself. If you have created any other workflow pipelines that use the Git push hook, they will also be listed as separate workflows.

Workflow 11

A workflow typically consists of a set of pipelines chained together, so that they execute in sequence, with each pipeline triggering the next. Workflows can fork, allowing parallel pipelines to execute, and they can include conditional execution, based on the branches involved in the build.

Workflow 12

To add a pipeline to a workflow, click on any of the available nodes in the workflow (indicated by a white plus sign in a blue circle). The pipeline will execute at the node which you select; the node represents the completion of the previous pipeline. You can create a strictly sequential workflow, or one that forks, depending on the nodes that you select for connecting new pipelines.

Note: You cannot currently add more than ten sequential pipelines to a single workflow.

When you click a node, you will bring up the Add Pipeline dialog box:

Add Pipeline

The Add Pipeline dialog box enables you to select a pipeline that will execute after the current pipeline.

Branch filtering

When you add a pipeline, you can include and/or exclude the branches of your Git project to trigger the pipeline. Branch filtering is applied when you commit your code to the SCM repository.

Tag filtering

You can also use tag filtering to run workflows. Unlike branch filtering, you must explicitly specify the tag filters that you want to apply to a pipeline. Tag filtering is applied when you push a tag to a repository.

Note: Tag filtering is available only for GitHub.

By default, the filter type (branch or tag) that you specify for the first pipeline applies to other pipelines in the workflow. However, you can override the filters for the subsequent pipelines, if required.

Add pipeline

To add a pipeline:

  1. Select the branches on which you want to trigger the pipeline. You can make multiple entries (separated by spaces) and use wildcard matching to select the branches. Use of regular expressions is not mandatory. By default, execution is triggered by all branches (indicated by *).
  2. Select the branches you want to exclude from triggering the pipeline. By default, the value is blank indicating that execution is not excluded for any branch.
  3. Specify the tags you want to apply to pipelines in the workflow. You can make multiple entries (separated by spaces) and use wildcard (*) matching to select the tags. By default, the value is blank indicating that no tags are applied.
  4. Select the tags you want to exclude from triggering the pipeline. By default, all tags are excluded (indicated by *).
  5. Select the pipeline from the Execute pipeline dropdown menu. The list includes only those pipelines that are not currently used in any workflow.
  6. Click Add.


  1. You can apply both types of filters to a workflow. However, only one set of filters (branch or tag) will work at a time. SCM repositories send separate notifications to Wercker for a tag or a branch push, even if they are pushed together. A tag push notification uses tag filters and a branch push notification uses branch filters.
  2. Wercker triggers builds automatically on a tag push only if you explicitly specify a tag filter.

Create a New Workflow

You can also create a new workflow by clicking Start new Workflow.

Start new workflow

When you click Start new Workflow, the Add Workflow dialog box is displayed. This dialog box functions like the Add Pipeline dialog box, with one exception. It allows you to select the preceding pipeline in the workflow. You have to select this pipeline from the When pipeline finishes dropdown list. The list includes only those pipelines that are not currently used in any workflow.