Inject environment variables with the CircleCI API
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
.
In order to pass a parameter when triggering a pipeline via the API, the parameter must be declared in the configuration file. |
curl -u ${CIRCLE_TOKEN}: -X POST --header "Content-Type: application/json" -d '{
"parameters": {
"workingdir": "./myspecialdir",
"image-tag": "4.8.2"
}
}' https://circleci.com/api/v2/project/:project_slug/pipeline
Refer to the Getting started with the API section of the API Developer’s Guide for more guidance on making requests.
Pipeline parameters are not treated as sensitive data and must not be used by customers for sensitive values (secrets). |
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 \
https://circleci.com/api/v1.1/project/github/circleci/mongofinil/tree/master
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\"]"
Build parameters are not treated as sensitive data and must not be used by customers for sensitive values (secrets). |
Help make this document better
This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.
- Suggest an edit to this page (please read the contributing guide first).
- To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
- CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.
Need support?
Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.
You can also visit our support site to find support articles, community forums, and training resources.
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.