Domain Model

Note: Parallel, series, and matrix have not been implemented yet. Everything will run in series by default.

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.

Step

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.

Container

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.

Job

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.

Parallelization

It is possible to parallelize a job by defining a matrix of environment variables. These are usually used for testing against multiple containers or test types.

In this example job definition, 4 builds will run in parallel:

image: node:
steps:
    test: npm run test-${TEST_TYPE}
matrix:
    NODE_VERSION:
        - 4
        - 6
    TEST_TYPE:
        - unit
        - functional

Build

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:

Event

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

Metadata

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.

Example:

$ meta set example.coverage 99.95
$ meta get example.coverage
99.95
$ meta get example
{"coverage":99.95}

See the metadata page for more information.

Workflow

Workflow is the order that jobs will execute in after a successful build of the main job. The main job will always run first. Jobs can be executed in parallel, series, or a combination of the two to allow for all possibilities. Workflow must contain all defined jobs in the pipeline.

All jobs executed in a given workflow share:

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

workflow:
    - publish
    - parallel:
        - series:
            - deploy-west
            - validate-west
        - series:
            - deploy-east
            - validate-east

After the merge of a pull-request to master:

Pipeline

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

The main job is required to be defined in every pipeline as it is the one that builds for each change made to the source code (and proposed changes).