The wercker.yml file must be placed in the root directory of your repository. This file tells Wercker how to build your application.

Wercker allows you to define a set of “pipelines” to build, test and deploy your application. You may choose to have a single pipeline, or you may wish to have seperate pipelines for different parts of your process. Pipelines can be joined together into “workflows” in the Wercker web interface. When you create a workflow, you can set rules about which pipelines are triggered under what circumstances and on which branches.

Each pipeline is made up of a number of “steps.” Steps define the actual logic that is executed. There are a number of “internal” steps, along with a large set of steps contributed by the Wercker community, which are available in the Steps Store.

There are some top level configuration options:

command-timeout: 25
no-response-timeout: 5
source-dir: .
ignore-file: .werckerignore
Name Required Type Description
command-timeout N Integer Timeout if command does not complete in this many minutes (default: 25)
no-response-timeout N Integer Timeout if no script output is received in this many minutes (default: 5)
source-dir N String Source path relative to checkout root
ignore-file N String File with file patterns to ignore when copying files. (default: .werckerignore)


Each pipeline that you define in the wercker.yml is executed in a Docker container which is created from the image named in the box statement. You must include a box statement at the top level, and you may also (optionally) include additional box statements inside one or more pipeline definitions. If a box statement is included in a pipeline, it takes precedence over the top-level box statement.

  id: alpine
  cmd: /bin/sh
  aws-access-key: $AWS_ACCESS_KEY_ID
  aws-secret-key: $AWS_SECRET_ACCESS_KEY
  aws-region: us-east-1
  aws-registry-id: $AWS_REGISTRY_ID
Name Required Type Description
id Y String Docker image of the format [registry[:port]/]repository[:tag]
name N String Logical name for the box
tag N String The tag portion of the docker image, overrides value specified as part of id.
cmd N String Overrides the cmd to use for the box.
env N Map A map of key/value pairs passed as environment variable to the box. See Environment.
ports N List A list of Docker port bindings for the box. Format: ip:hostPort:containerPort or ip::containerPort or hostPort:containerPort or containerPort; containerPort can be a range of ports. See description in the expose incoming ports arguments to the docker run command.
entrypoint N String Overrides the entrypoint specified in the image for the box.
url N String TODO: something about file:/// vs. not file
volumes N String A comma or space separated list of Docker volumes specified as [hostpath:]containerpath.
username N String Username used when accessing a private registry.
password N String Password used when accessing a private registry.
registry N String TODO: gives a warning but seems to ignore the value.
aws-registry-id N String The aws_account_id whose default registry should be used.
aws-region N String The AWS region code for the region the registry is located in.
aws-access-key N String The AWS access key id for an AWS root account or IAM account.
aws-secret-key N String The AWS secret access key for the AWS root account or IAM account.
aws-strict-auth N Bool If true, checks IAM policies before accessing a repository, if false simply retieves an access token.
azure-login-server N String The ACR login server name
azure-registry-name N String The ACR unique registry name
azure-client-id N String The appId of an Azure service principal
azure-client-secret N String Key for the appId specified in azure-client-id
azure-subscription-id N String Azure subscription id.
azure-tenant-id N String Tenant of an Azure service principal
azure-resource-group N String Resource group the registry is in


You can set environment variables inside the docker container using the env statement inside the box statement as shown in this example:

  id: alpine
    KEY1: value1
    KEY2: value2


The services statement allows you to start additional Docker containers and have them available (on the same Docker network) for your main container, i.e. the one that is running your pipeline.

Services may be specified at the top level, in which case they will be available to all pipelines defined in the wercker.yml, or you can define them inside a particular pipeline statement.

Each entry in the list follows the same syntax as the box statement.

  - mongo:2.2.7
  - name: red1
    id: sutoiku/redis
    cmd: redis-server
  - name: red2
    id: sutoiku/redis
    cmd: redis-server
Name Required Type Description
services N String A list of boxes that should be started as separate containers alongside the pipelines. See box for syntax.


You can define as many pipelines as you wish, and they may have any name that is not the same as any of the other top level statements.

By convention, the “main” pipeline is called build. This is the pipeline that would typically be triggered by a commit to your source code repository.

The example below defines two simple pipelines called build and hello-again:

    - script:
        code: echo "hello, world!"

  box: ubuntu
    - mongo:2.2.7
    - script:
        code: echo "hello, again world!"
Name Required Type Description
box N String The box that should be used for this pipeline, overrides main box. See box for syntax.
steps Y List List of steps to execute in this pipeline.
after-steps N List List of steps to execute after a pipeline whether it has failed or passed. After-steps status do not affect the pipeline status.
services N List A list of boxes that should be started as separate containers alongside the pipelines. See box for syntax.
base-path N String Resets the current working directory and value of $WERCKER_SOURCE_DIR


Steps define the logic that is executed in a pipeline. The steps are executed in the order they are listed. All of the steps are executed in the same Docker container. Note that each pipeline runs in a separate Docker container.

    - script:
        code: echo "hello, world!"
Name Required Type Description
id Y String The ID of the step of the form name[@version]
cwd N String The path of the working directory the step should be executed from
name N String Descriptive name of the step usd in output
checkpoint N String Sets a named checkpoint causing the container to get locally committed after this step. Can be continued from this point by passing flag –checkpoint on the wercker CLI.
data N Map The parameters for the step

Important environment variables

There are some important environment variables that are defined inside the Docker container where your pipeline is executed which you should be aware of.

Name Description
WERCKER_SOURCE_DIR The directory where your application source code repository has been cloned.
WERCKER_CACHE_DIR The Wercker “cache” directory, any files you place in this directory will be available in the same location to any future executions of the same pipeline. This is a useful place to put things like Maven or Gradle repositories so that your build does not need to download the same set of dependencies every time.
WERCKER_OUTPUT_DIR Any files you put in this directory will be saved as the “output” of your pipeline and will be available in the WERCKER_SOURCE_DIR for any pipeline that is executed immediately after this pipeline in the same workflow instance.
WERCKER_REPORT_DIR Any files you put in this directory will be made available to download from the Wercker web UI after the step has completed executing. This is useful for making reports, images, etc., available for easy download.