Migrate from pipeline variables to pipeline inputs for better security

Pipeline variables have long been a convenient way to customize GitLab CI/CD pipelines at runtime. However, as CI/CD security best practices have evolved, we've recognized the need for stronger controls around pipeline customization. Unrestricted pipeline variables allow any users with pipeline trigger permissions to override values without validation or type checking.

Beyond security considerations, pipeline variables lack proper documentation and explicit declaration, making it difficult to understand what inputs are expected and how they're used throughout your pipeline. This can lead to maintenance challenges and make it harder to establish proper governance over your CI/CD processes.

Enter pipeline inputs

Instead of relying on pipeline variables, we strongly recommend using GitLab's pipeline inputs feature. Pipeline inputs provide:

• Explicit declaration: Inputs must be explicitly declared in your .gitlab-ci.yml and are self-documented.

• Type safety: Support for different input types (string, boolean, number, array)

• Built-in validation: Automatic validation of input values

• Better security: No risk of variable injection attacks — only the declared inputs can be passed from the outside

Basic example

spec:
  inputs:
    deployment_env:
      description: "Target deployment environment"
      type: string
      options: ["staging", "production"]
      default: "staging"
    enable_tests:
      description: "Run test suite"
      type: boolean
      default: true

test:
  script:
    - echo "Running tests"
  rules:
    - if: $[[ inputs.enable_tests ]] == true

deploy:
  script:
    - echo "Deploying to $[[ inputs.deployment_env ]]"

Learn more about how CI/CD inputs provide type-safe parameter passing with validation in this tutorial.

Restrict pipeline variables

To effectively move to pipeline inputs and away from pipeline variables, you should configure the "Minimum role to use pipeline variables" setting. This setting provides fine-grained control over which role can use pipeline variables when triggering pipelines.

At the project level: Navigate to your project's Settings > CI/CD > Variables > Minimum role to use pipeline variables to configure the setting.

Available options are:

• No one allowed (no_one_allowed) - Recommended and most secure option. Prevents all variable overrides.

• Developer (developer) - Allows developers and above to override variables

• Maintainer (maintainer) - Requires maintainer role or higher

• Owner (owner) - Only project owners can override variables

At the group level: Group maintainers can go to Settings > CI/CD > Variables > Default role to use pipeline variables to establish secure defaults for all new projects within their group, ensuring consistent security policies across your organization. Here we recommend again to use No one allowed as default value — this way, new projects in this group are created with a secure default setting. Note that this still allows project owners to change the setting.

When pipeline variables are restricted completely (with “No one allowed”), the prefilled variables won’t appear in the "New Pipeline UI" form.

How to migrate from pipeline variables

Close the gaps

Your group may have projects that have pipeline variables enabled by default despite never having used them when triggering a pipeline. These projects can be migrated to the more secure setting without a risk of interruption. GitLab provides migration functionality via group settings:

• Go to Settings > CI/CD > Variables

• In Disable pipeline variables in projects that don’t use them, select Start migration.

This migration is a background job that safely disables pipeline variables via project settings for all projects that historically have not used them.

Convert pipeline variables to inputs

For each identified pipeline variable, create a corresponding pipeline input.

Before (using pipeline variables)

variables:
  DEPLOY_ENV:
    description: "Deployment environment"
    value: "staging"
  ENABLE_CACHE:
    description: "Enable deployment cache"
    value: "true"
  VERSION:
    description: "Application version"
    value: "1.0.0"

deploy:
  script:
    - echo "Deploying version $VERSION to $DEPLOY_ENV"
    - |
      if [ "$ENABLE_CACHE" = "true" ]; then
        echo "Cache enabled"
      fi

After (using pipeline inputs)

spec:
  inputs:
    deploy_env:
      description: "Deployment environment"
      type: string
      default: "staging"
      options: ["dev", "staging", "production"]

    enable_cache:
      description: "Enable deployment cache"
      type: boolean
      default: true
    
    version:
      description: "Application version"
      type: string
      default: "1.0.0"
      regex: '^[0-9]+\.[0-9]+\.[0-9]+$'

deploy:
  script:
    - echo "Deploying version $[[ inputs.version ]] to $[[ inputs.deploy_env ]]"
    - |
      if [ "$[[ inputs.enable_cache ]]" = "true" ]; then
        echo "Cache enabled"
      fi

Migrate trigger jobs

If you use trigger jobs with the trigger keyword, ensure they don't define job-level variables or disable inheriting variables from top-level variables, extends, or include, because variables could implicitly be passed downstream as pipeline variables. If pipeline variables are restricted on the downstream project, pipeline creation will fail.

Consider updating your CI configuration to use pipeline inputs instead of pipeline variables.

variables:
  FOO: bar

deploy-staging:
  inherit:
    variables: false # otherwise FOO would be sent downstream as a pipeline variable
  trigger:
    project: myorg/deployer
    inputs:
      deployment_env: staging
      enable_tests: true

Summary

Migrating from pipeline variables to pipeline inputs is a security enhancement that protects your CI/CD infrastructure from variable injection while providing better documentation, type safety, and validation. By implementing these restrictions and adopting pipeline inputs, you're not just improving security, you're also making your pipelines more maintainable, self-documenting, and resilient.

The transition requires some initial effort, but the long-term benefits far outweigh the migration costs. Start by restricting pipeline variables at the group level for new projects, then systematically migrate existing pipelines using the step-by-step approach outlined above.

Security is not a destination but a journey. Pipeline inputs are one important step in creating a more secure CI/CD environment, complementing other GitLab security features like protected branches, job token allowlists, and container registry protections.

To get started with pipeline inputs, sign up for a free trial of GitLab Ultimate today.