Domain Model

Note: Matrix has not been implemented yet.

Definition Runtime

Source Code

Source Code is a specified SCM repository and branch that contains a screwdriver.yaml and the code required to build, test, and publish your application.


A step is a named action that needs to be performed, usually a single shell command. In essence, Screwdriver runs /bin/sh in your terminal then executes all the steps; in rare cases, different terminal/shell setups may have unexpected behavior. If the command finishes with a non-zero exit code, the step is considered a failure. Environment variables will be passed between steps, within the same job.


A container runs steps in an isolated environment. This is done in order to test the compatibility of code running in different environments with different versions, without affecting other builds that may be running at the same time. This is implemented using Docker containers.


A job consists of executing multiple sequential steps inside a specified container. If any step in the series fails, then the entire job is considered failed and subsequent steps will be skipped (unless configured otherwise).

Jobs work by checking out the source code to a specified commit, setting the desired environment variables, and executing the specified steps.

During the job, the executing steps share three pieces of context:

Jobs can be started automatically by changes made in the source code or triggered through the workflow. Jobs can also be started manually through the UI.

Pull Requests

Pull requests are run separately from existing pipeline jobs. They will only execute steps from the main job in the Screwdriver configuration.


A build is an instance of a running job. All builds are assigned a unique build number. Each build is associated with an event. With a basic job configuration, only one build of a job will be running at any given time. If a job matrix is configured, then there can be multiple builds running in parallel.

A build can be in one of five different states:


An event represents a commit or a manual restart of a pipeline. There are 2 types of events:


Metadata is a structured key/value storage of relevant information about a build. Metadata will be shared with subsequent builds in the same workflow. It can be updated or retrieved throughout the build by using the built-in meta CLI in the steps.


$ meta set example.coverage 99.95
$ meta get example.coverage
$ meta get example

See the metadata page for more information.


Workflow is the order that jobs will execute in after a successful build of the first job. Jobs can be executed in parallel, series, or a combination of the two to allow for all possibilities. Order is determined by the requires keyword.

All jobs executed in a given workflow share:

In the following example of an abbreviated workflow section, this is the flow:

    requires: [~pr]
    requires: [main]
    requires: [publish]
    requires: [publish]
    requires: [deploy-west]
    requires: [deploy-east]

After the merge of a pull-request to base branch:


A pipeline represents a collection of jobs that share the same source code. These jobs are executed in the order defined by the workflow.