Managing Pipeline Parameters

1. Understanding Pipeline Parameters

Pipeline parameters in CircleCI allow you to customize the behavior of your CI/CD workflows dynamically. They provide a way to pass values into your configuration at runtime, enabling flexibility in how jobs and workflows behave based on input.

parameters:
  environment:
    type: string
    default: "staging"
    description: "Environment to deploy to"

jobs:
  build:
    parameters:
      environment:
        type: string
    steps:
      - run:
          command: echo "Deploying to $environment"

2. Defining Pipeline Parameters (parameters key)

Pipeline parameters are defined using the parameters key in your configuration file. This key allows you to define a set of parameters that can be referenced throughout the pipeline.

parameters:
  project-name:
    type: string
    default: "my-app"
    description: "Name of the project to build"

  is-production:
    type: boolean
    default: false
    description: "Flag indicating if this is a production deployment"

3. Using Parameter Types

CircleCI supports several parameter types that you can use to define your pipeline parameters. These types ensure that values passed to the pipeline are of the correct format.

parameters:
  environment:
    type: enum
    enum:
      - development
      - staging
      - production
    default: development

4. Setting Default Values

You can set default values for pipeline parameters to provide fallback behavior when no value is explicitly provided. These defaults are used if the parameter isn't overridden during pipeline execution.

parameters:
  branch:
    type: string
    default: "main"
    description: "Branch to build from"

  timeout:
    type: number
    default: 60
    description: "Timeout in seconds"

5. Referencing Parameters

Parameters can be referenced in various parts of your CircleCI configuration using the <parameter-name></parameter-name> syntax. This allows you to dynamically configure jobs and workflows based on input values.

parameters:
  environment:
    type: string
    default: "staging"

jobs:
  deploy:
    steps:
      - run:
          command: |
            echo "Deploying to $environment"

6. Using Parameters in Workflows

Pipeline parameters can be used within workflows to customize how jobs are executed. This enables you to run the same workflow with different configurations based on parameter inputs.

parameters:
  environment:
    type: string
    default: "staging"

workflows:
  deploy-workflow:
    jobs:
      - build:
          environment: <environment>

7. Using Parameters in Jobs

Parameters can be defined within individual jobs to allow customization of job behavior. These parameters are specific to the job and can be used to configure steps or other aspects of that job.

jobs:
  build:
    parameters:
      environment:
        type: string
        default: "staging"
    steps:
      - run:
          command: echo "Building on $environment"

8. Validating Parameter Values

CircleCI provides mechanisms to validate parameter values to ensure they meet specific criteria. You can define validation rules for parameters to enforce acceptable inputs.

parameters:
  project-name:
    type: string
    min_length: 3
    max_length: 20
    pattern: ^[a-zA-Z0-9_-]+$

9. Passing Parameters via API

Pipeline parameters can be passed to CircleCI using the API. This allows you to trigger pipelines with specific parameter values programmatically.

curl -X POST https://circleci.com/api/v2/project/github/owner/repo/pipeline \
  -H "Circle-Token: <token>" \
  -d '{"parameters": {"environment": "production"}}'

10. Debugging Parameter Issues

When working with pipeline parameters, it's important to understand how to debug issues related to parameter usage. Common problems include incorrect parameter types, missing values, or invalid syntax.

parameters:
  environment:
    type: string
    default: "staging"

jobs:
  debug:
    steps:
      - run:
          command: echo "Environment is set to $environment"