1.8.1 Running 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.

fly execute

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.

By default, Fly will not send extra files or large files in your current directory that would normally be ignored by your version control system. You can use the --include-ignored flags in order to send ignored files to Concourse along with 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 as inputs. 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 \
    --config build-stemcell.yml \
    --input code=. \
    --input stemcells=../stemcells

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

- 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.

Using an image from a job in your pipeline with --image

When using --inputs-from as above, you can additionally specify which input to use as the task's image by passing --image input-name.

For example, the following pipeline fetches an image via a get step and uses it for image:

- name: my-repo
  type: git
  source: {uri: https://example.com}

- name: some-image
  type: registry-image
  source: {repository: ubuntu}

- name: integration
  - get: my-repo
  - get: some-image
  - task: my-task
    file: my-repo/task.yml
    image: some-image

...so to run the same task with the same image in a one-off build, you would run:

$ fly -t example execute \
    --config task.yml \
    --inputs-from main/integration \
    --image some-image

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 \
    --config build-stemcell.yml \
    --input code=. \
    --output stemcell=/tmp/stemcell

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

- 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:

  FOO: fizzbuzz

...and you run:

BAR=hello fly execute

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

Providing values for ((vars))

Task config files can contain template variables in the form of ((foo-bar)), the same as pipeline ((vars)).

These vars can be set during fly execute by using the -v, -y and -l flags, the same as fly set-pipeline:

fly -t example execute --config tests.yml \
  -l vars.yml \
  -v some_string="Hello World!" \
  -y some_bool=true

Any variables not satisfied via the above flags will be deferred to the configured credential manager.

To satisfy these vars when running the task in a pipeline, see vars.

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.