Using Environment Variables in Go

Standard Go environment variables

Use current revision in a build

It is often useful to use the current version control revision number in your build. For example, you might want to use the svn version number in the name of your binary for tracing purposes. Go makes much of this information available to your build scripts as environment variables.

Example usages

One material

For this example, we are going to assume we are using a single Subversion repository for our source control system and we have a job set up to call the ant target "dist".

• Add the following target to your ant build.xml

build.xml

<project name="test-build">
  <property environment="env" />
  <target name="dist">
    <echo message="Building pipeline ${env.GO_PIPELINE_NAME}"
          file="deploy-${env.GO_REVISION}.txt" />
  </target>
</project>

• Now, when Go runs the 'my-app' pipeline on revision 123, the file deploy-123.txt will be created, with the following content:

deploy-123.txt

Building pipeline my-app

Multiple materials

For this example we are going to assume we are using a Subversion repository containing the code and a Mercurial repository containing configuration scripts.

• Ensure the pipeline materials look like this

<pipeline name="multiple-materials">
  <materials>
    <svn url="..." dest="code" />
    <hg url="..." dest="configuration/latest" />
  </materials>
  ...
</pipeline>

• Add the following target to your ant build.xml

build.xml

<project name="my-app">
  <property environment="env" />
  <target name="dist">
    <echo message="Building pipeline ${env.GO_PIPELINE_NAME}"
          file="deploy-${env.GO_REVISION_CODE}.txt" />
    <echo message="Configuration version: ${env.GO_REVISION_CONFIGURATION_LATEST}"
          file="deploy-${env.GO_REVISION_CODE}.txt"
          append="true" />
  </target>
</project>

• Now, when Go runs the 'my-app' pipeline with the code at revision '123' and the configuration at revision '59cab75ccf231b9e338c96cff0f4adad5cb7d335', the file deploy-123.txt will be created with the following content:

deploy-123.txt

Building pipeline my-app
Configuration version: 59cab75ccf231b9e338c96cff0f4adad5cb7d335

Pass environment variables to a job

You can specify variables for Environments, Pipelines, Stages 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 can add variables to an environment by editing the configuration of the environment. Click on the name of the environment to edit configuration.

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

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

You can add variables for a job by editing the job configuration.

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

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

Using environment variables in task

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="go" />
<target name="all">
    <echo message="Building all!" />
    <echo message="GO_SERVER_URL: ${go.GO_SERVER_URL}" />
    <echo message="GO_PIPELINE_NAME: ${go.GO_PIPELINE_NAME}" />
    <echo message="GO_PIPELINE_COUNTER: ${go.GO_PIPELINE_COUNTER}" />
    <echo message="GO_PIPELINE_LABEL: ${go.GO_PIPELINE_LABEL}" />
    <echo message="GO_STAGE_NAME: ${go.GO_STAGE_NAME}" />
    <echo message="GO_STAGE_COUNTER: ${go.GO_STAGE_COUNTER}" />
    <echo message="GO_JOB_NAME: ${go.GO_JOB_NAME}" />
    <echo message="GO_REVISION: ${go.GO_REVISION}" />
</target>