Start Building for Free

Inject environment variables with the CircleCI API

9 months ago2 min read
Server 3.x
Server 4.x
On This Page

API v2

Pipeline parameters can be used to pass variables using the CircleCI API v2.

A pipeline can be triggered with specific parameter values using the API v2 endpoint to trigger a pipeline. This can be done by passing a parameters key in the JSON packet of the POST body.

The example below triggers a pipeline with parameter values for workingdir and image-tag.

curl -u ${CIRCLE_TOKEN}: -X POST --header "Content-Type: application/json" -d '{
  "parameters": {
    "workingdir": "./myspecialdir",
    "image-tag": "4.8.2"

Refer to the Getting started with the API section of the API Developer’s Guide for more guidance on making requests.

Read more about pipeline parameters on the Pipeline values and parameters page.

API v1

You can inject environment variables with the build_parameters key to enable your functional tests to build against different targets on each run (for example, a run with a deploy step to a staging environment that requires functional testing against different hosts).

It is possible to include build_parameters by sending a JSON body with Content-type: application/json as in the following example that uses bash and curl. You may also use an HTTP library in your language of choice.

  "build_parameters": {
    "param1": "value1",
    "param2": 500

Using curl ($CIRCLE_TOKEN is a personal API token):

curl \
  --header "Content-Type: application/json" \
  --header "Circle-Token: $CIRCLE_TOKEN" \
  --data '{"build_parameters": {"param1": "value1", "param2": 500}}' \
  --request POST \

The build will see the environment variables:

export param1="value1"
export param2="500"

A POST API call with an empty body will start a new run of the named branch. Refer to the Trigger a new job with a branch section of the API v1 documentation for details.

Best practices for using build parameters with API v1

Build parameters are environment variables, therefore their names have to meet the following restrictions:

  • They must contain only ASCII letters, digits and the underscore character.

  • They must not begin with a number.

  • They must contain at least one character.

Aside from the usual constraints for environment variables, there are no restrictions on the values themselves and are treated as simple strings.

Build parameters are exported as environment variables inside each job’s containers and can be used by scripts/programs and commands in .circleci/config.yml. The injected environment variables may be used to influence the steps that are run during the job. It is important to note that injected environment variables will not override values defined in .circleci/config.yml nor in the project settings.

The order in which build parameters are loaded is not guaranteed, so avoid interpolating one build parameter into another. It is best practice to set build parameters as an unordered list of independent environment variables.

For example, when you pass the parameters:

  "build_parameters": {
    "foo": "bar",
    "baz": 5,
    "qux": {"quux": 1},
    "list": ["a", "list", "of", "strings"]

Your build will see the environment variables:

export foo="bar"
export baz="5"
export qux="{\"quux\": 1}"
export list="[\"a\", \"list\", \"of\", \"strings\"]"

Suggest an edit to this page

Make a contribution
Learn how to contribute