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.

workflow1.png

The Workflow 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.

workflow2.png

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.

workflow3.png

 

Create New Pipeline

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

Name

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.

workflow4.png

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.

workflow5.png

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

workflow6.png

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.

workflow7.png

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).

workflow8.png

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.

Settings

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.

workflow9.png

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.

workflow10.png

For more information, see http://devcenter.wercker.com/docs/web-interface/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.

workflow11.png

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.

workflow12.png

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 on a node, you will bring up the Add Pipeline dialog box:

Add Pipeline

The Add Pipeline dialog box allows you to select a pipeline which will execute when the current pipeline finishes executing. You can choose which branches of your Git project will trigger execution of your pipeline, and which branches will not trigger execution.

workflow13.png

Both the On branch(es) and Not on branch(es) fields allow multiple entries (separated by spaces) and * wildcards. The default setting is On branch(es) = * (execution is triggered by all branches) and Not on branch(es) = blank (execution is not excluded for any branch).

workflow14.png

Select the pipeline to be executed from the Execute pipeline dropdown menu. it includes only those pipelines which are not currently being used in a workflow. Click on the Add button to add the pipeline to the workflow.

Creating a New Workflow

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

workflow15.png

This will bring up the Add Workflow dialog box, which functions exactly like the Add Pipeline dialog box, with one exception. It allows you to select the initial pipeline in the workflow. You do this by means of the When pipeline finishes dropdown menu at the top of the dialog box. Like the Execute pipeline menu, it lists only those pipelines not already used in a workflow.