How to Use Pipeline Parameters in CircleCI

Pipeline parameters are typed values you declare once and reference anywhere with the pipeline.parameters context, often to gate which workflows run.

Declare parameters: at the top level, then read them as << pipeline.parameters.name >>. Override defaults when triggering via the API parameters body or the "Trigger Pipeline" UI.

Steps

• Add a top-level parameters: block with a type and default for each value.
• Reference values as << pipeline.parameters.<name> >> in jobs or workflow conditions.
• Pass overrides in the API trigger body or the UI when starting a pipeline.

Config

version: 2.1
parameters:
  deploy_env:
    type: string
    default: staging
  run_e2e:
    type: boolean
    default: false
workflows:
  ci:
    jobs:
      - test
      - e2e:
          requires: [test]
          filters:
            branches:
              only: main
      - deploy:
          requires: [test]
          context: << pipeline.parameters.deploy_env >>

Trigger with parameters

curl -X POST https://circleci.com/api/v2/project/gh/acme/app/pipeline \
  -H "Circle-Token: $CIRCLE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"branch":"main","parameters":{"deploy_env":"production","run_e2e":true}}'

Related guides