The first and most important thing that you need to understand about Wercker Pipelines is what they are, and what they are not.
A Pipeline in Wercker is a structured script that controls the development-build-deployment cycle for a project.
A Pipeline is not a stand-alone file, however. All of the Pipelines in a Wercker project are contained in a file named wercker.yml. It serves as the control file for the project, and is made up largely of Pipelines, along with some control and environment commands. This means that each Pipeline is a formally defined section of wercker.yml.
How to Build a Pipeline from the Wercker NodeJS Sample Project
Note: Wercker.yml is written in YAML, a structured, text-based language which is often used for configuration files. If you are not familiar with YAML, see YAML syntax (http://devcenter.wercker.com/docs/wercker-yml/yaml-syntax), or the official YAML reference card (http://www.yaml.org/refcard.html).
Pipelines themselves consist for the most part of sets of steps, which control the development-build-deployment cycle, along with a few environment and control commands. A step can be a file (either shell script or compiled executable), or it can be made up of inline script commands.
Where Can You Find Steps?
There are three basic sources for steps:
- The Wercker Steps Registry (https://app.wercker.com/explore/steps) includes a large number of steps available for general use, some of which perform key functions in the build-and-deploy process. You can click on a step listing in the Registry for instructions on its use, including required and optional arguments.
- If you do not find a suitable step in the registry, you can create one (http://devcenter.wercker.com/docs/steps/creating-steps), and optionally add it to the Registry.
- You can also create an inline script made up of shell commands (preferably Bash). The process of creating in-line script steps is described below.
Adding a Step: the Basics
The basic process of adding a step to a Pipeline is simple. You enter it as a YAML-format command (or set of commands) in the steps: section of the Pipeline's definition in wercker.yml.
The basic structure of step entries in a Pipeline definition looks like this:
In practice, steps can be a little more complicated. File-based steps can take parameters, and inline script steps require the script in the form of a code: argument (which can include multiple lines).
While not all steps require parameters, many do, and even those that do not require them may allow optional parameters (the optional name: parameter is available for every step).
Parameters follow the basic label: value format. Each parameter occupies a single line below the step entry, as in this example:
In this case, install-packages only requires one parameter (package:). The package: parameter can itself take multiple arguments, separated by a space, as well as version specifications (using = ) :
package: git subversion apache2=2.2.20-1ubuntu1
This will install Git, Subversion, and the specified version of Apache.
It is important to note that each step in the registry has its own set of parameters, and the conventions for entering parameter arguments may depend on the individual step. To find out how to use a specific step, you should consult its details page in the Step Registry.
Script steps allow you to execute shell commands inline, rather than from a step stored in the Registry.
The basic format for a script step is:
code: some code
The code: parameter is required, and its arguments will typically consist of Bash shell commands.
To enter multi-line code, start the code: parameter with the | character. This is standard YAML syntax, indicating that a multi-line string (with newlines included) follows.
For example, consider this step (from the NodeJS sample project's wercker.yml file):
name: echo nodejs information
echo "node version $(node -v) running"
echo "npm version $(npm -v) running"
The name: parameter is optional, and can be used to identify the step.
The argument for the code: parameter starts with the | "pipeline" character, with the actual script commands on the following lines. As always, the lines of the code: argument follow the very strict YAML rules for indentation.
The script commands used in a code: argument can reference Wercker environment variables, as in this example:
WERCKER_OUTPUT_DIR is a standard environment variable. For more on Wercker environment variables, see Environment Variables (http://devcenter.wercker.com/docs/environment-variables) in the Wercker development documentation.