Conditional jobs

Sometimes, you want to execute a job conditionally. You can use the when job property for this.

branch

You can limit job execution to specific branch by setting when.branch to an array of regular expressions.

job:
  test:
    when:
      branch:
        - master
        - feat/.*
    image: alpine
    script:
      - echo "test"

or use include (same behavior as above):

job:
  test:
    when:
      branch:
        include:
          - master
    image: alpine
    script:
      - echo "test"

When you do not want a job to be executed on a specific branch, you can use branch.exclude:

job:
  test:
    when:
      branch:
        exclude:
          - master
    image: alpine
    script:
      - echo "test"

By default, when a job is skipped, we do not prevent downstream jobs to be executed. To force downstream jobs to be skipped as well, set when.propagate to true:

job:
  test:
    when:
      propagate: true
      branch:
        exclude:
          - master
    image: alpine
    script:
      - echo "test"

status

You can limit job execution based on the upstream status, which is the status computed for jobs upstream (parents + parents of parents + ...) of the given job.

job:
  test:
    when:
      status:
        - success
        - failure
    image: alpine
    script:
      - echo "test"

or use include (same behavior as above):

job:
  test:
    when:
      status:
        include:
          - success
          - failure
    image: alpine
    script:
      - echo "test"

When you do not want a job to be executed on a specific branch, you can use branch.exclude:

job:
  test:
    when:
      status:
        exclude:
          - failure
    image: alpine
    script:
      - echo "test"

possible values are:

success # all jobs succeeded
failure # one or more jobs failed
partial # one ore more jobs with allowFailure:true failed
skipped # all jobs were skipped