Skip to content

Builds

A build is an execution of a build plan, which is either

Containers and volumes are created as get steps, put steps, and task steps run. When a build completes successfully, these containers go away.

A failed build's containers and volumes are kept around so that you can debug the build via fly intercept. If the build belongs to a job, the containers will go away when the next build starts. If the build is a one-off, its containers will be removed immediately, so make sure you intercept while it's running, if you want to debug.

Rerunning a Build

Concourse supports build rerunning, which means to run a new build using the exact same set of input versions as the original build. There are two ways to rerun a build: through the web UI on the builds page and through the fly rerun-build.

When a build is rerun, it will create a new build using the name of the original build with the rerun number appended to it, e.g. 3.1 for the first rerun of build 3.

Rerun builds are ordered chronologically after the original build, rather than becoming a new "latest" build. Similarly, when the scheduler is resolving passed constraints that reference a job with rerun builds, those rerun builds are processed in this same order. This ensures that the versions, which made it through a rerun build, do not become the new "latest versions". Instead, they act as if the original build had succeeded at its point in the build history.

This may sound a little confusing, but the summary is that reruns should behave as if they replace the original failed build.

Current caveats with rerunning

The current implementation of rerunning is an early iteration with one key limitation: a rerun build will use the current state of the job config, instead of running the exact build plan the original build ran with.

This means that if the job.plan has changed in a way that is backwards-incompatible, the rerun build may error. For example, if a new input is added, its version will not be available as the original build did not use it.

fly builds

To list the most recent builds, run:

fly -t example builds

To list the builds of a job, run:

fly -t example builds -j pipeline-name/job-name

This can be useful for periodically monitoring the state of a job. The output also works well with tools like awk and grep.

By default, the most recent 50 builds are shown. To see more builds, use the -c flag, like so:

fly -t example builds -c 100

To see builds within a certain time range, you can use --since and --until. You can use one or both flags to filter builds. The flags accept a time format of yyyy-mm-dd HH:mm:ss.

fly -t example builds --since '2006-02-06 00:00:00'

fly intercept

Sometimes it's helpful to connect to the machine where tasks run. This way you can either profile or inspect tasks, or see the state of the machine at the end of a run. Due to Concourse running tasks in containers on remote machines this would typically be hard to access.

To this end, there is a fly intercept command that will give you an interactive shell inside the specified container. Containers are identified by a few things, so you may need to specify a few flags to hone down the results. If there are multiple containers that the flags could refer to, an interactive prompt will show up allowing you to disambiguate.

For example, running the following will run a task and then enter the finished task's container:

fly -t example execute
fly -t example intercept --step build

Windows Workers

When intercepting a task running on a Windows worker, you will need to specifically tell fly to run powershell:

fly -t example intercept powershell

Containers are around for a short time after a build finishes in order to allow people to intercept them.

You can also intercept builds that were run in your pipeline. By using --job, --build, and --step you can intercept a specific step from a build of a job in your pipeline. These flags also have short forms, like so:

fly -t example intercept -j some-pipeline/some-job -b some-build -s some-step

Note that --build can be omitted, and will default to the most recent build of the job. One-off builds can be reached by passing in their build ID to --build which can be found on the build list page.

The --step flag can also be omitted; this will let you pick the step interactively, if you don't know the exact name.

Resource checking containers can also be intercepted with --check or -c:

fly -t example intercept --check some-pipeline/some-resource

A specific command can also be given, e.g. fly intercept ps auxf or fly intercept htop. This allows for patterns such as watch fly intercept ps auxf, which will continuously show the process tree of the current build's task, even as the "current build" changes.

The working directory and any relevant environment variables (e.g. those having come from task step params) used by the original process will also be used for the process run by intercept.

fly abort-build

To abort a build of a job, run:

fly -t example abort-build --job my-pipeline/my-job --build 3

This will cancel build 3 of the my-job job in the my-pipeline pipeline.

fly watch

Concourse emits streaming colored logs on the website, but it can be helpful to have the logs available to the command line (e.g. so that they can be processed by other commands).

The watch command can be used to do just this. You can also view builds that are running in your pipeline, or builds that have already finished.

Note that unlike fly execute, killing fly watch via SIGINT or SIGTERM will not abort the build.

To watch the most recent one-off build, just run fly watch with no arguments. To watch a specific build (one-off or not), pass --build with the ID of the build to watch. This ID is available at the start of fly execute's output or by browsing to the builds list in the web UI.

By using the --job and --build flags you can pick out a specific build of a job to watch. For example, the following command will either show the archived logs for an old build, if it has finished running, or it will stream the current logs, if the build is still in progress.

fly -t example watch --job my-pipeline/tests --build 52

If the --job flag is specified and --build is omitted, the most recent build of the specified job will be selected.

If there is a mismatch between the fly and web versions, it is possible to run into failed to parse next event: unknown event type error. The --ignore-event-parsing-errors flag can be passed to ignore such errors.