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
|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
You must include a
box statement at the top level, and you may also (optionally)
box statements inside one or more pipeline definitions.
box statement is included in a pipeline, it takes precedence over the
box: 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
|id||Y||String||Docker image of the format
|name||N||String||Logical name for the box|
|tag||N||String||The tag portion of the docker image, overrides value specified as part of
|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:
|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
|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-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
statement inside the
box statement as shown in this example:
box: id: alpine env: - 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
services: - mongo:2.2.7 - name: red1 id: sutoiku/redis cmd: redis-server - name: red2 id: sutoiku/redis cmd: redis-server
|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: steps: - script: code: echo "hello, world!" hello-again: box: ubuntu services: - mongo:2.2.7 steps: - script: code: echo "hello, again world!"
|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.
build: steps: - script: code: echo "hello, world!"
|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|
There are some important environment variables that are defined inside the Docker container where your pipeline is executed which you should be aware of.
|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.|