Build Metadata#

Build metadata represents the environment of the build.

The download_version() and publish_new_version() methods are each passed a build_metadata parameter, which is an instance of BuildMetadata populated from environment variables.

Note

Build metadata is deliberately not passed to fetch_new_versions(), as none of this metadata is passed to the check environment by Concourse, to avoid antipatterns.

See the Concourse resource metadata documentation for more information.

class concoursetools.metadata.BuildMetadata(BUILD_ID, BUILD_TEAM_NAME, ATC_EXTERNAL_URL, BUILD_NAME=None, BUILD_JOB_NAME=None, BUILD_PIPELINE_NAME=None, BUILD_PIPELINE_INSTANCE_VARS=None)[source]#

A class containing metadata about the running build.

Parameters:

  • BUILD_ID (str) – The internal identifier for the build. Right now this is numeric, but it may become a UUID in the future. Treat it as an absolute reference to the build.

  • BUILD_TEAM_NAME (str) – The team that the build belongs to.

  • ATC_EXTERNAL_URL (str) – The public URL for your ATC; useful for debugging.

  • BUILD_NAME (Optional[str]) – The build number within the build’s job.

  • BUILD_JOB_NAME (Optional[str]) – The name of the build’s job.

  • BUILD_PIPELINE_NAME (Optional[str]) – The name of the pipeline that the build’s job lives in.

  • BUILD_PIPELINE_INSTANCE_VARS (Optional[str]) – The instance vars of the instanced pipeline that the build’s job lives in, serialized as JSON.

Note

A few variables are often present in the build environment, but are not documented by Concourse:

  • BUILD_JOB_ID

  • BUILD_TEAM_ID

  • BUILD_PIPELINE_ID

These can still be accessed via os.environ, but they are not supported by Concourse Tools.

property BUILD_CREATED_BY: str#

The username that created the build.

Raises:

PermissionError – If this information has not been enabled.

Warning

By default this information is not available. To enable it, you need to set expose_build_created_by in your resource schema.

property is_one_off_build: bool#

Return True if this build is one-off, and False otherwise.

A build is a “one-off” is it is triggered via the Concourse CLI execute command. It is determined by the absence of all of the following attributes:

  • BUILD_JOB_NAME

  • BUILD_PIPELINE_NAME

  • BUILD_PIPELINE_INSTANCE_VARS

Caution

The documentation insists that $BUILD_NAME will also not be set in the environment during a one-off build, but experimentation has shown this to be false.

property is_instanced_pipeline: bool#

Return True if this is an instanced pipeline.

instance_vars()[source]#

Return the instance vars set on this pipeline as a mapping.

When working with an instanced pipeline, it is much more convenient to work with the instance vars as a mapping instead of a JSON string. :rtype: Dict[str, Any]

Note

If this is not an instanced pipeline, this method just returns an empty dict.

Example:

If a instanced pipeline has been created from within another pipeline (using the set pipeline step), such as this:

- set_pipeline: my-bots
  file: examples/pipelines/pipeline-vars.yml
  instance_vars:
    first: the-third
    hello: R2D2
    branches:
      from: develop
      to: main

then this method will return the following mapping:

{
    "first": "the-third",
    "hello": "R2D2",
    "branches": {
        "from" "develop",
        "to": "main"
    }
}
build_url()[source]#

Calculate the url to the build.

This method will return a full URL to the build within the web UI, accounting for any instanced pipelines. It is the most robust way to get a link to the build within Concourse, and should be preferred where possible.

Return type:

str

classmethod from_env()[source]#

Return an instance populated from the environment.

Return type:

BuildMetadata