Conditionals

Jobs and steps can be conditionally executed using the if: field. Conditions are evaluated using expr-lang , a simple expression language.

Examples

  name: Job Conditionals Example

vars:
  environment: production
  send_notifications: true
  allowed_envs:
    - staging
    - production

jobs:
  deploy:
    aliases: [default]
    desc: Deploy to production
    if: environment == "production"
    steps:
      - run: echo "Deploying to production..."

  notify:
    desc: Send notifications
    if: send_notifications == true
    steps:
      - run: echo "Sending notifications..."

  validate:
    desc: Validate environment
    if: environment in allowed_envs
    steps:
      - run: echo "Environment ${{ environment }} is valid"

  name: Step Conditionals Example

vars:
  environment: staging

jobs:
  deploy:
    aliases: [default]
    steps:
      - name: Deploy to production
        if: environment == "production"
        run: echo "Deploying to production..."
      - name: Deploy to staging
        if: environment == "staging"
        run: echo "Deploying to staging..."
      - name: Always run
        run: echo "Deployment complete for ${{ environment }}"

Available Variables

Conditions have access to:

1. Pipeline variables - All variables defined in vars: blocks
2. Environment variables - All environment variables (from shell and env: blocks)
3. Loop variables - When inside a for: loop, the loop variable is available

Expression Syntax

Expr-lang supports common operators and comparisons:

Examples

Combining conditions:

  if: environment == "production" && branch == "main"

Checking for values in lists:

  vars:
  allowed_envs:
    - staging
    - production

jobs:
  deploy:
    if: environment in allowed_envs
    steps:
      - run: echo "Deploying..."

Pattern matching:

  if: branch matches "^release/.*"

Truthiness

Values are coerced to boolean as follows:

Undefined Variables

Undefined variables evaluate to nil (falsy) rather than causing an error:

  jobs:
  optional:
    if: maybe_defined
    steps:
      - run: echo "Running optional job..."

Skipped Output

When a job or step is skipped due to a condition, the tree output shows the condition:

  [ok] build
[skip] deploy (if: environment == "production")

See Also

• Jobs - Job configuration
• Steps - Step configuration