On this page:
# resource schema
# resource.name
# resource.type
# resource.source
# resource.old_name
# resource.icon
# resource.version
# resource.check_every
# resource.check_timeout
# resource.expose_build_created_by
# resource.tags
# resource.public
# resource.webhook_token

1.8 Resources

Resources are the heart and soul of Concourse. They represent all external inputs to and outputs of jobs in the pipeline.

Each resource represents a versioned artifact with an external source of truth. Configuring the same resource in any pipeline on any Concourse cluster will behave the exact same way. Concourse will continuously check each configured resource to discover new versions. These versions then flow through the pipeline via get steps configured on Jobs.

A pipeline's resources are listed under pipeline.resources with the following schema.

resource schema

The name of the resource. This should be short and simple. This name will be referenced by build plans of jobs in the pipeline.

The resource type implementing the resource.

The configuration for the resource. This varies by resource type, and is a black box to Concourse; it is blindly passed to the resource at runtime.

To use git as an example, the source may contain the repo URI, the branch of the repo to track, and a private key to use when pushing/pulling.

By convention, documentation for each resource type's configuration is in each implementation's README.

You can find the source for the resource types provided with Concourse at the Concourse GitHub organization.

The old name of the resource. If configured, the history of the old resource will be inherited to the new one. Once the pipeline is set, this field can be removed as the history has been transferred.

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

resources:
- name: new-name
  old_name: current-name
  type: git
  source: uri: "https://github.com/vito/booklit"

After the pipeline is set, the resource was successfully renamed, so the `old_name` field can be removed from the resource:

resources:
- name: new-name
  type: git
  source: uri: "https://github.com/vito/booklit"

The name of a Material Design icon to show next to the resource name in the web UI. For example, github.

A version to pin the resource to across the pipeline. This has the same effect as setting get step version on every get step referencing the resource.

Resources can also be temporarily pinned to a version via the API and web UI. However this functionality is disabled if the resource is pinned via configuration, and if a pipeline is configured to have a version pinned while also pinned in the web UI, the configuration takes precedence and will clear out the temporary pin.

Default 1m. The interval on which to check for new versions of the resource. Acceptable interval options are defined by the time.ParseDuration function.

If set to never the resource will not be automatically checked. The resource can still be checked manually via the web UI, fly, or webhooks.

Default 1h. The time limit on checking new versions of resources. Acceptable interval options are defined by the time.ParseDuration function.

Default false. If set to true, environment variable BUILD_CREATED_BY will be available in the metadata of a put step. This field is not made available to the get step.

Default []. A list of tags to determine which workers the checks will be performed on. You'll want to specify this if the source is internal to a worker's network, for example.

This does not apply tags to all get steps or put steps that use the resource. If you want these steps to use tags, you must set tags for each step.

Default false. If set to true, the metadata for each version of the resource will be viewable by unauthenticated users (assuming the pipeline has been exposed).

Resource metadata should never contain credentials or secret information, but this is off by default just to be safe in case users don't want to show things like commit messages and authors to the public.

Note: even when set to false, the versions identifiers will be visible. In addition, if a resource is fetched in a build whose job is marked job.public, metadata will be visible in the build output.

If specified, web hooks can be sent to trigger an immediate check of the resource, specifying this value as a primitive form of authentication via query params.

After configuring this value, you would then configure your hook sender with the following painfully long path appended to your external URL:

/api/v1/teams/TEAM_NAME/pipelines/PIPELINE_NAME/resources/RESOURCE_NAME/check/webhook?webhook_token=WEBHOOK_TOKEN

For instance pipelines you will need to include the pipeline vars for a single pipeline instance. Currently you can not have webhooks for all instances of a pipeline.

The pipeline vars should be added to the webhook URL as URL parameters with the format vars.MY-VAR="SOME-VALUE". A webhook URL for a pipeline instance may look like this:

/api/v1/teams/TEAM_NAME/pipelines/PIPELINE_NAME/resources/RESOURCE_NAME/check/webhook?webhook_token=WEBHOOK_TOKEN&vars.my-var="some-value"&vars.second-var="two"

Note that the request payload sent to this API endpoint is entirely ignored. You should configure the resource as if you're not using web hooks, as the resource config is still the "source of truth."

Table of contents:
  1. 1.8.1 Resource Versions
    1. 1.8.1.1 Where do they come from and what are they used for?
    2. 1.8.1.2 Version Pinning
      1. 1.8.1.2.1 Unpinning
    3. 1.8.1.3 Disabling a Version
  2. 1.8.2 Managing Resources
    1. 1.8.2.1 fly check-resource
    2. 1.8.2.2 fly pin-resource
    3. 1.8.2.3 fly enable-resource-version
    4. 1.8.2.4 fly disable-resource-version
    5. 1.8.2.5 fly clear-resource-cache

Examples

git resource

The following resource definition is an example of the git resource:

name: booklit
type: git
source: {uri: "https://github.com/concourse/booklit"}

This could be passed to a job via a get step with trigger: true to run the tests whenever there's new code:

resources:
- name: booklit
  type: git
  source: {uri: "https://github.com/concourse/booklit"}

jobs:
- name: unit
  plan:
  - get: booklit
    trigger: true
  - task: test
    file: booklit/ci/test.yml

time resource

The following resource emits a new version every hour:

name: 1h
type: time
source: {interval: 1h}

This could be passed to a job via a get step with trigger: true to run the job periodically:

resources:
- name: 1h
  type: time
  source: {interval: 1h}

jobs:
- name: nag
  plan:
  - get: 1h
    trigger: true
  - task: nag
    config: # ...