execute: Submitting Local Tasks

One of the most common use cases of fly is taking a local project on your computer and submitting it up with a task configuration to be run inside a container in Concourse. This is useful to build Linux projects on OS X or to avoid all of those debugging commits when something is configured differently between your local and remote setup.

You can execute a task like this:

$ fly -t example execute --config tests.yml

Your files will be uploaded and the task will be executed with them. The working directory name will be used as the input name. If they do not match, you must specify -i name=. instead, where name is the input name from the task configuration.

Fly will automatically capture SIGINT and SIGTERM and abort the build when received. This allows it to be transparently composed with other toolchains.

If you have many extra files or large files in your current directory that would normally be ignored by your version control system, then you can use the -x or --exclude-ignored flags in order to limit the files that you send to Concourse to just those that are not ignored.

If your task needs to run as root then you can specify the -p or --privileged flag.

Providing multiple inputs

Tasks in Concourse can take multiple inputs. Up until now we've just been submitting a single input (our current working directory) that has the same name as the directory.

Tasks must specify the inputs that they require (for more information, refer to the configuring tasks documentation). For fly to upload these inputs you can use the -i or --input arguments with name and path pairs. For example:

$ fly -t example execute --input code=. --input stemcells=../stemcells

This would work together with a task.yml if its inputs: section was as follows:

inputs:
- name: code
- name: stemcells

If you specify an input then the default input will no longer be added automatically and you will need to explicitly list it (as with the code input above).

This feature can be used to mimic other resources and try out combinations of input that would normally not be possible in a pipeline.

Basing inputs on a job in your pipeline with --inputs-from

If the --inputs-from flag is given, the specified job will be looked up in the pipeline, and the one-off build will base its inputs on those currently configured for the job.

If any --input flags are given (see above), they will override the base set of inputs.

For example:

$ fly -t example execute --config task.yml --inputs-from main/integration --input foo=./foo

This will trigger a one-off-build using the task.yml task config, basing its inputs on the latest candidates for the integration job in the main pipeline, with the foo input overridden to specify local code to run.

This can be used to more closely replicate the state in CI when weeding out flakiness, or as a shortcut for local development so that you don't have to upload every single resource from your local machine.

Taking artifacts from the build with --output

If a task specifies outputs then you're able to extract these back out of the build and back to your local system. For example:

$ fly -t example execute --input code=. --config build-stemcell.yml --output stemcell=/tmp/stemcell

This would work together with a task.yml if its outputs: section was as follows:

outputs:
- name: stemcell

This feature is useful to farm work out to your Concourse server to build things in a repeatable manner.

Providing values for params

Any params listed in the task configuration can be specified by using environment variables.

So, if you have a task with the following params:

params:
  FOO: fizzbuzz
  BAR:

...and you run:

BAR=hello fly execute

The task would then run with BAR as "hello", and FOO as "fizzbuzz" (its default value).

Targeting a specific worker with --tag

If you want to execute a task on a worker that has a specific tag, you can do so by passing --tag:

fly -t example execute --config task.yml --tag bar

This will execute the task specified by task.yml on a worker that has been tagged bar.