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 (str | None) – The build number within the build’s job.

  • BUILD_JOB_NAME (str | None) – The name of the build’s job.

  • BUILD_PIPELINE_NAME (str | None) – The name of the pipeline that the build’s job lives in.

  • BUILD_PIPELINE_INSTANCE_VARS (str | None) – 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.

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"
    }
}
Return type:

dict[str, object]

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

format_string(string, additional_values=None, ignore_missing=False)[source]

Format a string with metadata using standard bash $ notation.

Only a handful of “safe” values will be interpolated, not arbitrary attributes on the instance. These are the original environment variables, including BUILD_CREATED_BY if it exists. object missing environment variable (such as in the case of a one-off build) will be empty. A $BUILD_URL variable is also added for ease.

Danger

By passing additional values you are allowing an arbitrary user to view these with the correct choice of variable. You should take great care not to pass any sensitive values.

Added in version 0.8.0.

Parameters:

  • string (str) – The string to be interpolated.

  • additional_values (dict[str, str] | None) – Additional values which can be used for interpolation. The keys of the mapping should not include the $ character.

  • ignore_missing (bool) – By default, if the variable is not available then a KeyError will be raised. Setting this to True will ignore missing variables.

Return type:

str

Returns:

The interpolated string.

Seealso:

Interpolation is done using an instance of string.Template by calling either substitute() when ignore_missing is False, and safe_substitute() otherwise.

Example:
>>> from concoursetools.mocking import TestBuildMetadata
>>> metadata = TestBuildMetadata()
>>> metadata.format_string("The build id is $BUILD_ID.")
'The build id is 12345678.'
classmethod from_env()[source]

Return an instance populated from the environment.

Return type:

BuildMetadata