1.7 Jobs

Jobs determine the actions of your pipeline. They determine how resources progress through it, and how the pipeline is visualized.

The most important attribute of a job is its build plan, configured as plan. This determines the sequence of Steps to execute in any builds of the job.

Jobs are listed under the jobs: key in the pipeline configuration. Each configured job consists of the following fields:

name: string

Required. The name of the job. This should be short; it will show up in URLs.

old_name: string

Optional. The old name of the job. If configured, the history of old job will be inherited to the new one. Once the pipeline is set, this field can be removed as the builds have been transfered.

This can be used to rename a job without losing its history, like so:

jobs:
- name: new-name
  old_name: current-name
  plan: [get: 10m]

After the pipeline is set, because the builds have been inherited, the job can have the field removed:

jobs:
- name: new-name
  plan: [get: 10m]
plan: [step]

Required. The sequence of steps to execute.

serial: boolean

Optional. Default false. If set to true, builds will queue up and execute one-by-one, rather than executing in parallel.

build_log_retention: retention_config

Optional. Configures the retention policy for build logs. This is useful if you have a job that runs often but after some amount of time the logs aren't worth keeping around.

The following fields may be specified in retention_config:

days: number

Optional. Keep logs for builds which have finished within the specified number of days.

builds: number

Optional. Keep logs for the last specified number of builds.

Builds which are not retained by one of the above configurations will have their logs reaped.

The following example will keep logs for any builds that have completed in the last 2 days, while also keeping the last 1000 builds.

jobs:
- name: smoke-tests
  build_log_retention:
    days: 2
    builds: 1000
  plan:
  - get: 10m
  - task: smoke-tests
    # ...

Note: if more than 1000 builds finish in the past 2 days, all of them will be retained thanks to the build_log_retention.days configuration. Similarly, if there are 1000 builds spanning more than 2 days, they will also be kept thanks to the build_log_retention.builds configuration. Both policies operate independently.

Optional. Deprecated in favor of build_log_retention.

Equivalent to the following:

build_log_retention:
  builds: number
serial_groups: [string]

Optional. Default []. When set to an array of arbitrary tag-like strings, builds of this job and other jobs referencing the same tags will be serialized.

This can be used to ensure that certain jobs do not run at the same time, like so:

jobs:
- name: job-a
  serial_groups: [some-tag]
- name: job-b
  serial_groups: [some-tag, some-other-tag]
- name: job-c
  serial_groups: [some-other-tag]

In this example, job-a and job-c can run concurrently, but neither job can run builds at the same time as job-b.

The builds are executed in their order of creation, across all jobs with common tags.

max_in_flight: integer

Optional. If set, specifies a maximum number of builds to run at a time. If serial or serial_groups are set, they take precedence and force this value to be 1.

public: boolean

Optional. Default false. If set to true, the build log of this job will be viewable by unauthenticated users. Unauthenticated users will always be able to see the inputs, outputs, and build status history of a job. This is useful if you would like to expose your pipeline publicly without showing sensitive information in the build log.

Note: when this is set to true, any get step and put steps will show the metadata for their resource version, regardless of whether the resource itself has set public to true.

Optional. Default false. If set to true, manual triggering of the job (via the web UI or fly trigger-job) will be disabled.

interruptible: boolean

Optional. Default false. Normally, when a worker is shutting down it will wait for builds with containers running on that worker to finish before exiting. If this value is set to true, the worker will not wait on the builds of this job. You may want this if e.g. you have a self-deploying Concourse or long-running-but-low-importance jobs.

on_success: step

Optional. Step to execute when the job succeeds. Equivalent to the on_success step attribute.

on_failure: step

Optional. Step to execute when the job fails. Equivalent to the on_failure step attribute.

on_abort: step

Optional. Step to execute when the job aborts. Equivalent to the on_abort step attribute.

ensure: step

Optional. Step to execute regardless of whether the job succeeds, fails, errors, or aborts. Equivalent to the ensure step attribute.