Help documentation

 

Pass environment variables to a job

You can specify variables for Environments and Jobs. If a variable is specified more than once, the most specific scope is used. For example if you specify variable FOO='foo' for an environment, and FOO='bar' for a Job, then the variable will have the value 'bar' when the job runs.

Setting variables on an environment

You specify variables on an environment by adding an <environmentvariables> section to the environment definition.

<environment name="UAT">
    <environmentvariables>
        <variable name="FOO">bar</variable>
        <variable name="MULTIPLE_LINES">Variable values can have
        multiple lines (assuming that your operating system supports this correctly).</variable>
        <variable name="COMPLEX"><![CDATA[<complex
        values>]]></variable>
    </environmentvariables>
    <agents />
    <pipelines />
</environment>

Setting variables on a Job

You specify variables on an job by adding an <environmentvariables> section to the job definition.

<job name="my-job">
    <environmentvariables>
        <variable name="FOO">bar</variable>
        <variable name="MULTIPLE_LINES">Variable values can have
        multiple lines (assuming that your operating system supports this correctly).</variable>
        <variable name="COMPLEX"><![CDATA[<complex
        values>]]></variable>
    </environmentvariables>
    ...
</job>

Standard Go environment variables

Go sets the following environment variables for all builds it executes. You can override these by setting the same variables in the Environment or Job.

  • GO_SERVER_URL -- the base URL for the server. This includes the /go - so it would look something like this: https://[Go server host]:8154/go
  • GO_ENVIRONMENT_NAME -- the name of the current environment. This is only set if the environment is specified. Otherwise the variable is not set in the system environment.
  • GO_PIPELINE_COUNTER -- the execution iteration of the current pipeline.
  • GO_PIPELINE_LABEL -- the label for the current pipeline for the server. By default this is set to the pipeline count. You can customise this in the pipeline configuration by setting a labeltemplate.
  • GO_PIPELINE_NAME -- the name of the pipeline that is being run
  • GO_STAGE_NAME -- the name of the stage that is being run
  • GO_STAGE_COUNTER -- the execution iteration of the current stage.
  • GO_JOB_NAME -- the name of the job that is being run
  • GO_DEPENDENCY_LABEL_${PIPELINE_NAME} -- The label of the upstream pipeline (when using dependant pipelines). $(PIPELINE_NAME) will be the name of the pipeline dependency material if a name is specified for the material. $(PIPELINE_NAME) will be the name of the upstream pipeline otherwise.
  • GO_DEPENDENCY_LOCATOR_${PIPELINE_NAME} -- The canonical locator of the upstream pipeline. $(PIPELINE_NAME) will be the name of the pipeline dependency material if a name is specified for the material. $(PIPELINE_NAME) will be the name of the upstream pipeline otherwise.
  • The revision of your materials. Either:
    • GO_REVISION -- The current source control revision being run (when no name is specified for the material). If you have just one material and have specified a name for it, the environment variable will be called GO_REVISON_${material name}
    • GO_REVISION_${material dest} -- If you are using more than one material in your pipeline the revision for each material is available. The environment variable is names with the material's "dest" directory. Non alphanumeric characters are replaced with underscores("_").

You can access these environment variables to construct versioned artifacts or to store properties on the current build. For example the following snippet of an ant file shows how to access Go variables:

<property environment="cruise" />
<target name="all">
    <echo message="Building all!" />
    <echo message="GO_SERVER_URL: ${cruise.GO_SERVER_URL}" />
    <echo message="GO_PIPELINE_NAME: ${cruise.GO_PIPELINE_NAME}" />
    <echo message="GO_PIPELINE_COUNTER: ${cruise.GO_PIPELINE_COUNTER}" />
    <echo message="GO_PIPELINE_LABEL: ${cruise.GO_PIPELINE_LABEL}" />
    <echo message="GO_STAGE_NAME: ${cruise.GO_STAGE_NAME}" />
    <echo message="GO_STAGE_COUNTER: ${cruise.GO_STAGE_COUNTER}" />
    <echo message="GO_JOB_NAME: ${cruise.GO_JOB_NAME}" />
    <echo message="GO_REVISION: ${cruise.GO_REVISION}" />
</target>

CRUISE_XXX variables are deprecated since Go 2.0. Please use GO_XXX instead of CRUISE_XXX (For example: GO_SERVER_URL instead of CRUISE_SERVER_URL).