Skip to content

Gated Pipeline Patterns

Gated pipelines provide control for administrators and release managers on when a given software release is deployed to a tightly protected environment (e.g. production).

The execution of jobs that perform certain tasks (e.g. deployment) targeting the downstream environment beyond the " gate" step is done only upon either an approval coming from an external Change Control system or an explicit manual trigger of such step.

1) - A Simple Gated Pipeline

By default, all Jobs only run when manually triggered. That means a user has to run fly trigger-job or click the plus button in the web interface for a job to run. A job only runs automatically if one of its resources has the trigger: true parameter set.

Therefore, in order to create a gated job in a pipeline you simply need to create a job that can only be manually triggered. That means not setting trigger: true for any of the jobs' get steps.

jobs:
  - name: run-automatically
    plan:
      - get: my-repo
        trigger: true  # has trigger:true so automatically triggers
    # can include more steps to run other things before hitting the gate

  - name: the-gate  # manually trigger this job
    plan:
      - get: my-repo
        trigger: false  # redundant but guarantees the job won't run automatically
        passed:
          - run-automatically

  # runs immediately after the gate is triggered
  - name: do-more-stuff-after-the-gate
    plan:
      - get: my-repo
        passed:
          - the-gate
        trigger: true
    # can include more steps to run other things

resources:
  - name: my-repo
    type: git
    source:
      uri: https://github.com/concourse/examples.git

2) - Gated Pipeline Fanning In and Out

You can also use a gate as way to fan-in from multiple jobs and/or fan-out to multiple jobs as well.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
jobs:
  # three pre-gate jobs
  - name: job-a
    plan:
      - get: my-repo
        trigger: true
  - name: job-b
    plan:
      - get: my-repo
        trigger: true
  - name: job-c
    plan:
      - get: my-repo
        trigger: true

  - name: the-gate  # manually trigger this job
    plan:
      - get: my-repo
        trigger: false
        passed: # fan-in from the three pre-gate jobs
          - job-a
          - job-b
          - job-c

  # fan-out to three post-gate jobs
  - name: post-gate-job-a
    plan:
      - get: my-repo
        trigger: true
        passed: [ the-gate ]
  - name: post-gate-job-b
    plan:
      - get: my-repo
        trigger: true
        passed: [ the-gate ]
  - name: post-gate-job-c
    plan:
      - get: my-repo
        trigger: true
        passed: [ the-gate ]

resources:
  - name: my-repo
    type: git
    source:
      uri: https://github.com/concourse/examples.git

3) - A Gated Pipeline With Notifications

This pipeline shows you how you can send a notification, like an email, to notify someone that a new build of your application is ready to be shipped.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
jobs:
  - name: build-it
    plan:
      - get: my-repo
        trigger: true
    # can add steps to build your app

  - name: test-it
    plan:
      - get: my-repo
        trigger: true
        passed: [ build-it ]
      # can add steps to run tests
      - put: email-release-manager
        params:
          subject: "Ready to ship"
          body_text: |
            A build is ready to be shipped!
            Build to be shipped: ${ATC_EXTERNAL_URL}/teams/${BUILD_TEAM_NAME}/pipelines/${BUILD_PIPELINE_NAME}/jobs/${BUILD_JOB_NAME}/builds/${BUILD_NAME}
            Link to pipeline: ${ATC_EXTERNAL_URL}/teams/${BUILD_TEAM_NAME}/pipelines/${BUILD_PIPELINE_NAME}

  - name: ship-it
    plan:
      - get: my-repo
        trigger: false
        passed: [ test-it ]

resources:
  - name: my-repo
    type: git
    source:
      uri: https://github.com/concourse/examples.git
  - name: email-release-manager
    type: email
    source:
      # other required fields for this resource have been omitted
      from: pipeline@example.com
      to: release-manager@example.com

resource_types:
  - name: email
    type: registry-image
    source:
      repository: pcfseceng/email-resource