Concourse Ci

Concourse CI Pipeline Development

Expert guidance for writing, refactoring, and optimizing Concourse CI pipelines (v8.0+).

When to Use

• Creating or modifying Concourse pipelines
• Configuring resources (git, registry-image, custom types)
• Building container images with oci-build-task
• Troubleshooting resource check failures or build issues
• Migrating from legacy patterns (docker-image, duplicate jobs)

Quick Reference

Core Concepts

Pipelines consist of resources (external versioned artifacts), jobs (sequences of steps), and optional groups (UI organization). All execution runs in containers.

Key step types: get, put, task, set_pipeline, in_parallel, do, try, load_var. Job hooks: on_success, on_failure, on_error, on_abort, ensure. Note: on_failure (non-zero exit) differs from on_error (infrastructure crash/OOM) -- handle both. Use fly execute to test tasks locally.

See references/core-concepts.md for step types table, lifecycle hooks, and fly CLI essentials.

Critical Gotchas

1. Git tag detection after force-push -- Escape regex dots, enable clean_tags: true, separate read/write resources, force recheck with fly -t T check-resource -r pipeline/resource. See references/resources-guide.md. 2. registry_mirror format mismatch -- registry-image expects an object (host: mirror), docker-image expects a URL string. Provide separate formats in CONCOURSE_BASE_RESOURCE_TYPE_DEFAULTS. See references/resources-guide.md. 3. GitLab Container Registry JWT auth -- The JWT endpoint lives on the GitLab host, not the registry host. Discover via Www-Authenticate header. See references/resources-guide.md. 4. git push --mirror and default branch -- Target repo's default branch must exist upstream. If absent, the pre-receive hook rejects the push with "pre-receive hook declined". Set it before the first mirror push.

References

• references/pipeline-syntax.md -- Complete YAML schema for pipelines, jobs, resources
• references/core-concepts.md -- Step types, lifecycle hooks, fly CLI essentials
• references/resources-guide.md -- Git-resource, registry-image, docker-image migration, gotcha details
• references/best-practices.md -- Optimization, troubleshooting, notifications, deployment patterns
• references/resource-types-catalog.md -- Available resource types (Ansible, Terraform, etc.)

Examples

Working examples in examples/:

• basic-pipeline.yml -- Build-test-deploy with versioning
• modern-ci-cd.yml -- oci-build-task, across, build_log_retention
• multi-branch.yml -- Dynamic branch pipelines with set_pipeline
• docker-build.yml -- Container image build and push
• vars-template.yml -- Variable file organization

Validation

Use scripts/validate-pipeline.sh to check pipeline syntax before deployment.

Concourse CI Best Practices and Troubleshooting

Optimization patterns, common pitfalls, and debugging strategies.

Pipeline Organization

Use YAML Anchors for DRY Configuration

# Top of pipeline: define reusable snippets
git-source: &git-source
  username: ((gitlab.USER))
  password: ((gitlab.ACCESS_TOKEN))

registry-source: &registry-source
  username: ((registry.USER))
  password: ((registry.PASSWORD))

notify-failure: &notify-failure
  put: slack
  params:
    text: '((SLACK_ICON_FAILURE)) $BUILD_PIPELINE_NAME/$BUILD_JOB_NAME failed'

notify-success: &notify-success
  put: slack
  params:
    text: '((SLACK_ICON_SUCCESS)) $BUILD_PIPELINE_NAME/$BUILD_JOB_NAME succeeded'

# Use anchors in resources
resources:
- name: repo-main
  type: git
  source:
    <<: *git-source
    uri: https://git.example.com/org/repo.git
    branch: main

- name: repo-staging
  type: git
  source:
    <<: *git-source
    uri: https://git.example.com/org/repo.git
    branch: staging

# Use anchors in jobs
jobs:
- name: build
  plan:
  - get: repo-main
    trigger: true
  - task: build
    file: repo-main/ci/tasks/build.yml
  on_failure:
    <<: *notify-failure

Group Jobs Logically

groups:
- name: all
  jobs: ["*"]

- name: build
  jobs:
  - compile
  - test
  - package

- name: deploy
  jobs:
  - deploy-staging
  - deploy-prod

- name: maintenance
  jobs:
  - update-dependencies
  - cleanup-images

Separate Read and Write Resources

Avoid using the same resource for both tracking versions and pushing changes:

# BAD: Mixed read/write
resources:
- name: repo
  type: git
  source:
    uri: https://github.com/org/repo
    branch: main
    tag_regex: "^v.*"

jobs:
- name: release
  plan:
  - get: repo
    trigger: true
  - task: bump-version
  - put: repo  # Creates version conflicts!
    params:
      repository: repo
      tag: version/tag

# GOOD: Separate resources
resources:
- name: repo-read
  type: git
  source:
    uri: https://github.com/org/repo
    branch: main
    tag_regex: "^v.*"
    fetch_tags: true
    clean_tags: true

- name: repo-write
  type: git
  source:
    uri: https://github.com/org/repo
    branch: main
    fetch_tags: true

jobs:
- name: release
  plan:
  - get: repo-read
    trigger: true
  - task: bump-version
  - put: repo-write
    params:
      repository: repo-read
      tag: version/tag

---

Git Resource Gotchas

Tag Detection After Force Push

Problem: Concourse stops detecting new tags after force-pushing a branch.

Root Causes:

1. Tags unreachable from branch: After force push, tags may point to commits no longer on the tracked branch 2. Version model conflict: Concourse's append-only version tracking conflicts with rewritten history 3. Cached tag state: Old tags cached in resource state

Diagnosis:

# Check if tag is reachable from branch
git fetch --tags origin
git branch -r --contains <tag_commit_sha>  # Should show origin/main
# OR
git merge-base --is-ancestor <tag_commit_sha> origin/main  # Should succeed

Solutions:

# 1. Enable tag cleanup
resources:
- name: repo
  type: git
  source:
    uri: https://github.com/org/repo
    branch: main
    tag_regex: "^v[0-9]+\\.[0-9]+\\.[0-9]+$"
    fetch_tags: true
    clean_tags: true  # Critical: clears cached tags

# 2. Force resource check from specific ref
# fly -t target check-resource -r pipeline/repo --from ref:abc123

Best Practice: Treat release branches and tags as immutable. Never force-push.

Regex Escaping

Problem: Unescaped dots match any character.

# BAD: . matches any character
tag_regex: "^v[0-9]+.[0-9]+.[0-9]+$"  # Matches v1a2b3 too

# GOOD: Escape literal dots
tag_regex: "^v[0-9]+\\.[0-9]+\\.[0-9]+$"

Branch vs Tag Tracking

# Track branch commits
- name: repo-branch
  type: git
  source:
    branch: main

# Track tags (no branch needed for triggering)
- name: repo-tags
  type: git
  source:
    branch: main  # Still needed for put operations
    tag_regex: "^v.*"

# Tag filtering modes
tag_filter: "v*"      # Bash glob (simple patterns)
tag_regex: "^v[0-9]"  # Extended grep regex (complex patterns)

Path Filtering Optimization

resources:
- name: app-source
  type: git
  source:
    uri: https://github.com/org/repo
    branch: main
    # Only trigger on application code changes
    paths:
    - src/**
    - lib/**
    - package.json
    - package-lock.json
    # Ignore documentation and CI changes
    ignore_paths:
    - "**/*.md"
    - docs/**
    - ci/**
    - .github/**

---

Performance Optimization

Parallel Execution

# Parallel independent steps
- in_parallel:
    limit: 5  # Control concurrency
    fail_fast: true  # Stop on first failure
    steps:
    - get: dependency-a
    - get: dependency-b
    - get: dependency-c

# Parallel tests
- in_parallel:
    steps:
    - task: unit-tests
    - task: integration-tests
    - task: e2e-tests

Task Caching

# Cache dependencies between runs
platform: linux
image_resource:
  type: registry-image
  source:
    repository: node
    tag: 20

caches:
- path: source/node_modules
- path: source/.npm

run:
  path: /bin/bash
  args:
  - -c
  - |
    cd source
    npm ci  # Uses cache if available
    npm run build

Shallow Clones

# For builds that don't need git history
- get: source
  params:
    depth: 1

Resource Check Intervals

# Reduce load for stable resources
resources:
- name: base-image
  type: registry-image
  check_every: 24h  # Daily check
  source:
    repository: node
    tag: 20-alpine

- name: source-code
  type: git
  check_every: 1m  # Frequent check for active development
  source:
    uri: https://github.com/org/repo

Serial Groups

# Prevent resource contention
jobs:
- name: deploy-staging
  serial_groups: [deploy]
  plan:
  - get: app-image
  - task: deploy

- name: deploy-prod
  serial_groups: [deploy]
  plan:
  - get: app-image
  - task: deploy

---

Security Best Practices

Credential Management

# Use var sources (Vault, SSM, etc.)
var_sources:
- name: vault
  type: vault
  config:
    url: https://vault.example.com
    path_prefix: /concourse/main

# Reference credentials
resources:
- name: repo
  type: git
  source:
    username: ((vault:git.username))
    password: ((vault:git.token))

Minimize Privileged Tasks

# Only use privileged when absolutely necessary
- task: docker-build
  privileged: true  # Required for Docker-in-Docker
  file: source/ci/tasks/build-image.yml

# Prefer oci-build-task over Docker-in-Docker
- task: build-image
  privileged: true  # Still needed but more secure
  config:
    platform: linux
    image_resource:
      type: registry-image
      source:
        repository: concourse/oci-build-task
    inputs:
    - name: source
    outputs:
    - name: image
    run:
      path: build

Resource Visibility

# Keep sensitive resources private
resources:
- name: credentials
  type: git
  public: false  # Default, but be explicit
  source:
    uri: git@github.com:org/secrets.git

# Only expose what's necessary
- name: public-docs
  type: git
  public: true
  source:
    uri: https://github.com/org/docs.git

---

Debugging Strategies

Hijack into Containers

# Hijack into a running or failed build
fly -t target hijack -j pipeline/job -b 123

# Hijack specific step
fly -t target hijack -j pipeline/job -s task-name

# List hijack targets
fly -t target hijack -j pipeline/job --list

Check Resource Versions

# List versions
fly -t target resource-versions -r pipeline/resource

# Force check
fly -t target check-resource -r pipeline/resource

# Check from specific version
fly -t target check-resource -r pipeline/resource --from ref:abc123

Watch Build Logs

# Stream live logs
fly -t target watch -j pipeline/job

# Specific build
fly -t target watch -j pipeline/job -b 123

Validate Pipeline

# Syntax check
fly -t target validate-pipeline -c pipeline.yml

# With variables
fly -t target validate-pipeline -c pipeline.yml -l vars.yml

Debug Task Locally

# Execute task with local inputs
fly -t target execute -c ci/tasks/build.yml \
  -i source=. \
  -o artifacts=./out

# Include ignored files (e.g., .gitignore'd)
fly -t target execute --include-ignored -c ci/tasks/build.yml -i source=.

---

Common Patterns

Build-Test-Release with Gates

jobs:
- name: build
  plan:
  - get: source
    trigger: true
  - task: compile
    file: source/ci/tasks/compile.yml
  - put: artifact-rc
    params:
      file: build/app-*.tar.gz

- name: test
  plan:
  - get: artifact-rc
    passed: [build]
    trigger: true
  - get: source
    passed: [build]
  - task: integration-test
    file: source/ci/tasks/test.yml

- name: release
  plan:
  - get: artifact-rc
    passed: [test]
    trigger: true
  - get: version
    params:
      bump: minor
  - put: artifact-release
    params:
      file: artifact-rc/app-*.tar.gz
      tag: version/version
  - put: version
    params:
      file: version/version

Manual Deployment Gate

- name: deploy-prod
  plan:
  - get: app-image
    passed: [deploy-staging]
    # No trigger: true - requires manual click
  - task: deploy
    file: source/ci/tasks/deploy.yml
    params:
      ENVIRONMENT: production

Scheduled Jobs

resources:
- name: nightly
  type: time
  source:
    start: 2:00 AM
    stop: 3:00 AM
    location: America/New_York

- name: weekday-morning
  type: time
  source:
    start: 9:00 AM
    stop: 9:30 AM
    location: Europe/Berlin
    days: [Monday, Tuesday, Wednesday, Thursday, Friday]

jobs:
- name: nightly-cleanup
  plan:
  - get: nightly
    trigger: true
  - task: cleanup
    file: ci/tasks/cleanup.yml

- name: weekday-update
  plan:
  - get: weekday-morning
    trigger: true
  - get: source
  - task: update-dependencies
    file: source/ci/tasks/update.yml

Multi-Environment Deploy with across

Modern approach using the across step modifier:

jobs:
- name: deploy
  plan:
  - get: app-image
    trigger: true
  - get: source
  - task: deploy
    across:
    - var: env
      values: [dev, staging, prod]
      max_in_flight: 1  # Sequential deployment
    file: source/ci/tasks/deploy.yml
    params:
      ENVIRONMENT: ((.:env))
      CONFIG: source/config/((.:env)).yml

Environment-Specific Resources (Traditional Pattern)

When across isn't suitable, use separate resources per environment:

# Define anchor for common settings
git-source: &git-source
  uri: https://github.com/org/repo
  username: ((git.username))
  password: ((git.password))

resources:
- name: repo-staging
  type: git
  source:
    <<: *git-source
    branch: staging

- name: repo-prod
  type: git
  source:
    <<: *git-source
    branch: prod

- name: image-staging
  type: registry-image
  source:
    repository: registry.example.com/org/app
    tag: staging
    username: ((registry.user))
    password: ((registry.pass))

- name: image-prod
  type: registry-image
  source:
    repository: registry.example.com/org/app
    tag: prod
    username: ((registry.user))
    password: ((registry.pass))

---

Notification Patterns

Modern: Dedicated Notification Resources

Use specialized resources for better formatting and features:

Slack (Recommended: arbourd/concourse-slack-alert-resource)

resource_types:
- name: slack-alert
  type: registry-image
  source:
    repository: arbourd/concourse-slack-alert-resource

resources:
- name: notify
  type: slack-alert
  source:
    url: ((slack.webhook_url))
    channel: "#builds"

jobs:
- name: build
  plan:
  - get: source
    trigger: true
  - task: build
    file: source/ci/tasks/build.yml
  on_success:
    put: notify
    params:
      alert_type: success
  on_failure:
    put: notify
    params:
      alert_type: failed

Microsoft Teams

resource_types:
- name: teams-notification
  type: registry-image
  source:
    repository: navicore/teams-notification-resource

resources:
- name: teams
  type: teams-notification
  source:
    url: ((teams.webhook_url))

jobs:
- name: deploy
  on_failure:
    put: teams
    params:
      text: "Deploy failed: $BUILD_PIPELINE_NAME/$BUILD_JOB_NAME"
      color: "FF0000"

Generic: HTTP Resource for Custom Webhooks

For Matrix, Element, Discord, or custom endpoints:

resource_types:
- name: http-resource
  type: registry-image
  source:
    repository: jgriff/http-resource

resources:
- name: webhook
  type: http-resource
  source:
    url: https://hooks.example.com/notify
    headers:
      Content-Type: application/json
      Authorization: Bearer ((webhook.token))
    out_only: true          # No check/get operations
    sensitive: true         # Hide response in logs
    build_metadata: [headers, body]  # Enable CI variable resolution

# Usage with CI metadata variables
- put: webhook
  params:
    body: |
      {
        "pipeline": "$BUILD_PIPELINE_NAME",
        "job": "$BUILD_JOB_NAME",
        "build": "$BUILD_NAME",
        "url": "$ATC_EXTERNAL_URL/builds/$BUILD_ID",
        "status": "failed"
      }

Notification Anchor Pattern

DRY notification configuration:

# Top of pipeline
notify-success: &notify-success
  put: notify
  params:
    alert_type: success

notify-failure: &notify-failure
  put: notify
  params:
    alert_type: failed

jobs:
- name: build
  plan:
  - get: source
  - task: build
    file: source/ci/tasks/build.yml
  on_success:
    <<: *notify-success
  on_failure:
    <<: *notify-failure

- name: deploy
  plan:
  - get: source
    passed: [build]
  - task: deploy
    file: source/ci/tasks/deploy.yml
  on_success:
    <<: *notify-success
  on_failure:
    <<: *notify-failure

---

Deployment Patterns

Ansible Playbook Execution

For infrastructure provisioning with Ansible:

resource_types:
- name: ansible-playbook
  type: registry-image
  source:
    repository: troykinsella/concourse-ansible-playbook-resource
    tag: latest

resources:
- name: ansible-deploy
  type: ansible-playbook
  source:
    ssh_private_key: ((ssh.private_key))
    env:
      ANSIBLE_HOST_KEY_CHECKING: "false"
      SSH_USER: ((ssh.user))

jobs:
- name: provision
  plan:
  - get: infrastructure-repo
    trigger: true
  - put: ansible-deploy
    params:
      path: infrastructure-repo/ansible
      playbook: playbooks/provision.yml
      inventory: inventory/hosts
      limit: production  # Target host group
      extra_vars:
        app_version: "1.2.3"

Task-Based Ansible (Alternative)

For simpler setups without the resource type:

- task: ansible-deploy
  config:
    platform: linux
    image_resource:
      type: registry-image
      source:
        repository: cytopia/ansible
        tag: latest
    inputs:
    - name: source
    params:
      ANSIBLE_HOST_KEY_CHECKING: "false"
      SSH_PRIVATE_KEY: ((ssh.private_key))
    run:
      path: /bin/sh
      args:
      - -c
      - |
        mkdir -p ~/.ssh
        echo "$SSH_PRIVATE_KEY" > ~/.ssh/id_rsa
        chmod 600 ~/.ssh/id_rsa
        cd source/ansible
        ansible-playbook -i inventory/hosts playbook.yml

Cross-Repository Pipeline Triggers

Trigger downstream pipelines by pushing to other repositories:

- task: trigger-downstream
  config:
    platform: linux
    image_resource:
      type: registry-image
      source:
        repository: alpine/git
    inputs:
    - name: source
    params:
      GIT_USER: ((git.username))
      GIT_TOKEN: ((git.token))
      DOWNSTREAM_REPO: https://github.com/org/downstream.git
    run:
      path: /bin/sh
      args:
      - -c
      - |
        VERSION=$(cat source/version)
        git clone https://${GIT_USER}:${GIT_TOKEN}@${DOWNSTREAM_REPO#https://} downstream
        cd downstream
        echo "$VERSION" > app-version
        git config user.email "ci@example.com"
        git config user.name "CI Bot"
        git add app-version
        git commit -m "Update app version to $VERSION"
        git push origin main

---

Troubleshooting Checklist

Pipeline Not Triggering

1. Check resource is not paused: fly -t target unpause-resource -r pipeline/resource 2. Verify trigger: true on get step 3. Check resource versions: fly -t target resource-versions -r pipeline/resource 4. Force resource check: fly -t target check-resource -r pipeline/resource 5. Verify path filters aren't excluding changes

Build Failing Silently

1. Check ensure steps for errors masking failures 2. Review try steps that swallow failures 3. Check container limits (OOM kills) 4. Hijack and inspect logs/state

Credentials Not Working

1. Verify var source configuration 2. Check credential path/field names 3. Test credentials outside Concourse 4. Check var source connectivity from workers

Resource Check Hanging

1. Increase check_timeout 2. Check network connectivity from workers 3. Verify worker tags match resource tags 4. Check for rate limiting on external services

registry_mirror Errors

Error: json: cannot unmarshal string into Go struct field Source.source.registry_mirror of type resource.RegistryMirror

• Cause: CONCOURSE_BASE_RESOURCE_TYPE_DEFAULTS passes registry_mirror as a plain string, but registry-image resource expects an object
• Fix: Change config to registry_mirror: { host: "hostname" } for registry-image entries
• Note: docker-image still needs the plain string format — provide both in defaults config

Error: registries must be valid RFC 3986 URI authorities: https://mirror.example.com

• Cause: registry_mirror.host includes URL scheme (https://)
• Fix: Strip scheme — host must be bare hostname only (e.g., mirror.example.com)

Error: Failed to obtain registry token (from CI tasks checking registry)

• Cause: JWT auth URL hardcoded to registry host, but GitLab Container Registry auth endpoint is on the GitLab host
• Fix: Discover auth realm dynamically from registry's Www-Authenticate header on /v2/
• Example: registry.example.com may have auth at git.example.com/jwt/auth

See resources-guide.md for detailed format reference and Ansible template patterns.

Core Concepts Reference

Step Types

Job Lifecycle Hooks

Important: on_failure (exit code 1) is different from on_error (container crash). Handle both.

fly CLI Essentials

fly -t target set-pipeline -p pipeline-name -c pipeline.yml -l vars.yml
fly -t target check-resource -r pipeline/resource-name
fly -t target trigger-job -j pipeline/job-name -w
fly -t target hijack -j pipeline/job-name -s step-name
fly -t target validate-pipeline -c pipeline.yml
fly -t target execute -c task.yml -i source=.    # Run task locally
fly -t target execute --include-ignored -c task.yml -i source=.

Concourse CI Pipeline Syntax Reference

Complete YAML schema reference for Concourse CI pipelines.

Pipeline Root Schema

# Required
jobs: []  # At least one job required

# Optional
resources: []           # External versioned artifacts
resource_types: []      # Custom resource type definitions
var_sources: []         # Variable sources (Vault, SSM, etc.)
groups: []              # UI organization
display:                # Visual customization
  background_image: ""
  background_filter: "opacity(30%) grayscale(100%)"

Resource Schema

resources:
- name: resource-name        # Required: identifier
  type: git                  # Required: resource type
  source: {}                 # Required: type-specific config

  # Optional
  old_name: previous-name    # Rename while preserving history
  icon: gitlab               # Material Design icon name
  version: { ref: abc123 }   # Pin specific version
  check_every: 1m            # Check interval (default: 1m)
  check_timeout: 1h          # Check timeout (default: 1h)
  tags: [private-network]    # Worker selection tags
  public: false              # Expose metadata publicly
  webhook_token: secret      # Webhook trigger token
  expose_build_created_by: false

Resource Type Schema

resource_types:
- name: slack-notification   # Required: identifier
  type: registry-image       # Required: image source type
  source:                    # Required: image location
    repository: cfcommunity/slack-notification-resource
    tag: latest

  # Optional
  privileged: false          # Run with full capabilities
  params: {}                 # Default get params
  check_every: 1m            # Version check interval
  tags: []                   # Worker selection tags
  defaults: {}               # Default source config

Job Schema

jobs:
- name: job-name             # Required: identifier
  plan: []                   # Required: steps to execute (alias: steps)

  # Optional
  old_name: previous-name    # Rename preserving history
  serial: false              # Sequential execution only
  serial_groups: []          # Serialize jobs sharing groups
  max_in_flight: 1           # Max concurrent builds
  public: false              # Public build logs
  disable_manual_trigger: false
  interruptible: false       # Allow worker shutdown

  # Build log retention
  build_log_retention:
    days: 30                 # Keep builds from last N days
    builds: 100              # Keep last N builds
    minimum_succeeded_builds: 1

  # Lifecycle hooks
  on_success: { step }       # Run on success
  on_failure: { step }       # Run on failure
  on_error: { step }         # Run on error
  on_abort: { step }         # Run on abort
  ensure: { step }           # Always run

Step Types

Get Step

- get: resource-name         # Resource to fetch

  # Optional
  resource: actual-resource  # Override resource name
  version: latest            # Version selection: latest, every, { ref: x }
  passed: [job1, job2]       # Only versions passing these jobs
  params: {}                 # Resource-specific get params
  trigger: false             # Auto-trigger on new versions
  tags: []                   # Worker selection
  timeout: 1h                # Step timeout
  attempts: 1                # Retry count

  # Hooks
  on_success: { step }
  on_failure: { step }
  on_error: { step }
  on_abort: { step }
  ensure: { step }

Put Step

- put: resource-name         # Resource to update

  # Optional
  resource: actual-resource  # Override resource name
  inputs: detect             # Input artifacts: detect, all, [list]
  params: {}                 # Resource-specific put params
  get_params: {}             # Implicit get params
  no_get: false              # Skip implicit get after put
  tags: []                   # Worker selection
  timeout: 1h
  attempts: 1

  # Hooks
  on_success: { step }
  on_failure: { step }
  on_error: { step }
  on_abort: { step }
  ensure: { step }

Task Step

- task: task-name            # Required: task identifier

  # Config source (choose one)
  config: { task-config }    # Inline configuration
  file: path/to/task.yml     # File from input artifact

  # Optional
  image: input-name          # Use input artifact as image
  privileged: false          # Run as root
  vars: {}                   # Static variables for config
  params: {}                 # Environment variables
  input_mapping:             # Rename inputs
    task-input: get-name
  output_mapping:            # Rename outputs
    task-output: result
  tags: []
  timeout: 1h
  attempts: 1
  container_limits:
    cpu: 1024                # CPU shares
    memory: 1073741824       # Memory in bytes

  # Hooks
  on_success: { step }
  on_failure: { step }
  on_error: { step }
  on_abort: { step }
  ensure: { step }

Task Configuration Schema

platform: linux              # Required: linux, darwin, windows

# Image (required for linux)
image_resource:
  type: registry-image
  source:
    repository: alpine
    tag: latest
  params: {}
  version: {}

# Private registry example
image_resource:
  type: registry-image
  source:
    repository: registry.example.com/org/build-tools
    username: ((registry.user))
    password: ((registry.pass))
    tag: "1.2.3"

# OR use docker-image type (legacy)
image_resource:
  type: docker-image
  source:
    repository: registry.example.com/org/build-tools
    username: ((registry.user))
    password: ((registry.pass))

# OR use rootfs_uri for pre-uploaded images
rootfs_uri: /path/to/rootfs

inputs:
- name: input-name           # Required
  path: custom-path          # Optional: override directory name
  optional: false            # Allow missing input

outputs:
- name: output-name
  path: custom-path

caches:
- path: node_modules         # Persistent across runs

params:
  ENV_VAR: value             # Environment variables
  SECRET: ((vault:secret))   # From credential manager

run:
  path: /bin/bash            # Required: executable
  args: [-c, "echo hello"]   # Command arguments
  dir: input-name            # Working directory
  user: root                 # Execution user

container_limits:
  cpu: 1024
  memory: 1073741824

Set Pipeline Step

- set_pipeline: pipeline-name
  file: config/pipeline.yml  # Required: config file

  # Optional
  vars: {}                   # Variables to pass
  var_files: []              # Variable files
  instance_vars: {}          # Instance pipeline variables
  team: other-team           # Target team (default: current)

Load Var Step

- load_var: var-name
  file: path/to/file         # Required: file with value

  # Optional
  format: json               # json, yaml, trim, raw
  reveal: false              # Show in UI (false redacts)

In Parallel Step

- in_parallel:
    steps:                   # Required: steps to parallelize
    - get: resource-a
    - get: resource-b
    - task: parallel-work

    # Optional
    limit: 3                 # Max concurrent steps
    fail_fast: false         # Abort remaining on first failure

Do Step

- do:                        # Sequential step sequence
  - get: resource
  - task: step1
  - task: step2

Try Step

- try:                       # Continue regardless of outcome
    task: optional-step

Across Step Modifier

- task: deploy
  across:
  - var: region
    values: [us-east, us-west, eu-west]
  - var: env
    values: [staging, prod]
    max_in_flight: 1         # Serial across this dimension
  file: ci/tasks/deploy.yml
  vars:
    region: ((.:region))
    environment: ((.:env))

Step Modifiers

Apply to any step:

- task: example
  timeout: 30m               # Step timeout
  attempts: 3                # Retry on failure
  tags: [specialized]        # Worker selection

  # Hooks run after step
  on_success: { put: notify }
  on_failure: { put: alert }
  on_error: { put: page }
  on_abort: { put: cleanup }
  ensure: { task: always-run }

Groups Schema

groups:
- name: group-name           # Required
  jobs:                      # Required: job references
  - job-name
  - deploy-*                 # Glob patterns
  - terraform-{dev,prod}     # Brace expansion

Var Sources Schema

var_sources:
- name: vault
  type: vault
  config:
    url: https://vault.example.com
    path_prefix: /concourse
    auth_backend: token
    auth_params:
      token: ((VAULT_TOKEN))

- name: ssm
  type: ssm
  config:
    region: us-east-1

- name: secrets-manager
  type: secretsmanager
  config:
    region: us-east-1

Display Schema

display:
  background_image: https://example.com/bg.png
  background_filter: "blur(5px) brightness(0.5)"

Variable Syntax Reference

# Basic var
((var-name))

# Var with source
((source:path))

# Var with field
((source:path.field))

# Local var (from load_var)
((.:local-var))

# Nested field access
((vault:secret/app.data.password))

YAML Anchor Patterns

# Define anchor
common-config: &common
  username: ((git.user))
  password: ((git.pass))

# Reference anchor
resources:
- name: repo
  source:
    <<: *common
    uri: https://github.com/org/repo

# Anchor with override
- name: other-repo
  source:
    <<: *common
    uri: https://github.com/org/other
    branch: develop  # Override common setting

Identifier Rules

Pipeline, job, resource, and resource type names must:

• Start with a lowercase letter
• Contain only lowercase letters, numbers, hyphens, periods, underscores
• Cannot be purely numeric
• Cannot contain consecutive special characters

Valid: my-pipeline, build_v2, deploy.prod Invalid: My-Pipeline, 123, build--test

Concourse CI Resource Types Catalog

Comprehensive list of available resource types organized by category.

Core Resources (Bundled with Concourse)

---

Version Control

Git

Example: Git Branches Resource

resource_types:
- name: git-branches
  type: registry-image
  source:
    repository: aoldershaw/git-branches-resource

resources:
- name: feature-branches
  type: git-branches
  source:
    uri: https://github.com/org/repo
    branch_regex: "feature/.*"
    private_key: ((git.private_key))

---

Container Images

Example: Registry Tag Resource

resource_types:
- name: registry-tag
  type: registry-image
  source:
    repository: ghcr.io/tlwr/registry-tag-resource

resources:
- name: base-image-tags
  type: registry-tag
  source:
    repository: node
    tag_regex: "^20-.*"

---

Cloud Providers

AWS

Google Cloud

Azure

---

Kubernetes & Infrastructure

Example: Ansible Playbook Resource

resource_types:
- name: ansible-playbook
  type: registry-image
  source:
    repository: troykinsella/concourse-ansible-playbook-resource
    tag: latest

resources:
- name: deploy-playbook
  type: ansible-playbook
  source:
    ssh_private_key: ((ssh.private_key))
    env:
      ANSIBLE_HOST_KEY_CHECKING: "false"
      APP_USER: ((app.user))
      APP_PASSWORD: ((app.password))

jobs:
- name: deploy
  plan:
  - get: source
    trigger: true
    passed: [build]
  - put: deploy-playbook
    params:
      path: source/ansible
      playbook: playbooks/deploy.yml
      inventory: inventory/hosts
      limit: production        # Target specific host group
      tags:                    # Run only tagged tasks
      - deploy
      - configure
      extra_vars:
        app_version: "1.2.3"
      setup_commands:          # Run before playbook
      - "pip install boto3"

Example: Terraform Resource

resource_types:
- name: terraform
  type: registry-image
  source:
    repository: ljfranklin/terraform-resource

resources:
- name: infrastructure
  type: terraform
  source:
    env_name: production
    backend_type: s3
    backend_config:
      bucket: terraform-state
      key: infra/terraform.tfstate
      region: us-east-1

jobs:
- name: provision
  plan:
  - get: infra-repo
    trigger: true
  - put: infrastructure
    params:
      terraform_source: infra-repo/terraform
      vars:
        instance_type: t3.medium
        environment: production

---

Notifications

Example: Slack Notification

resource_types:
- name: slack-notification
  type: registry-image
  source:
    repository: cfcommunity/slack-notification-resource

resources:
- name: slack
  type: slack-notification
  source:
    url: ((slack.webhook_url))

jobs:
- name: build
  plan:
  - get: source
    trigger: true
  - task: build
    file: source/ci/tasks/build.yml
  on_success:
    put: slack
    params:
      text: ":white_check_mark: Build succeeded!"
      channel: "#ci-notifications"
  on_failure:
    put: slack
    params:
      text: ":x: Build failed!"
      channel: "#ci-notifications"

---

Artifact Management

---

Databases

---

Monitoring & Metrics

Example: GitHub Commit Status

resource_types:
- name: cogito
  type: registry-image
  source:
    repository: pix4d/cogito

resources:
- name: commit-status
  type: cogito
  check_every: never
  source:
    owner: org
    repo: repo
    access_token: ((github.token))

jobs:
- name: build
  plan:
  - get: source
    trigger: true
  - put: commit-status
    params:
      state: pending
      context: build
  - task: build
    file: source/ci/tasks/build.yml
    on_success:
      put: commit-status
      params:
        state: success
        context: build
    on_failure:
      put: commit-status
      params:
        state: failure
        context: build

---

Build Tools

Example: OCI Build Task

jobs:
- name: build-image
  plan:
  - get: source
    trigger: true
  - task: build
    privileged: true
    config:
      platform: linux
      image_resource:
        type: registry-image
        source:
          repository: concourse/oci-build-task
      inputs:
      - name: source
      outputs:
      - name: image
      params:
        CONTEXT: source
        DOCKERFILE: source/Dockerfile
      run:
        path: build
  - put: app-image
    params:
      image: image/image.tar

---

RSS & Feeds

---

Custom Resource Development

Create custom resources by implementing three scripts:

/opt/resource/check   # Detect versions
/opt/resource/in      # Fetch version
/opt/resource/out     # Update/push

Minimal Custom Resource

FROM alpine:latest

RUN apk add --no-cache bash jq curl

COPY check /opt/resource/check
COPY in /opt/resource/in
COPY out /opt/resource/out

RUN chmod +x /opt/resource/*

Pipeline Registration

resource_types:
- name: custom-resource
  type: registry-image
  source:
    repository: myregistry/custom-resource
    tag: latest

resources:
- name: my-custom
  type: custom-resource
  source:
    config_option: value

---

Resource Discovery

Find more resources at:

• Concourse Resource Types Catalog
• Concourse GitHub Organization
• Community Resources on GitHub

Concourse CI Resources Configuration Guide

Detailed configuration reference for commonly used Concourse CI resources.

Git Resource (concourse/git-resource)

Tracks commits in a Git repository branch or by tags.

Source Configuration

resources:
- name: source-repo
  type: git
  source:
    # Required
    uri: https://github.com/org/repo.git  # Repository URL

    # Authentication (choose method)
    # HTTPS with username/password
    username: ((git.username))
    password: ((git.token))

    # SSH with private key
    private_key: ((git.private_key))
    private_key_user: git                 # SSH config User
    private_key_passphrase: ((passphrase)) # If key is encrypted

    # Branch tracking (optional, defaults to repo default branch)
    branch: main

    # Tag tracking (choose one, mutually exclusive with branch for triggers)
    tag_filter: "v*"                      # Bash glob pattern
    tag_regex: "^v[0-9]+\\.[0-9]+\\.[0-9]+$"  # Extended grep regex

    # Path filtering (trigger only on changes to specific files)
    paths:
    - src/**
    - lib/**
    ignore_paths:
    - "*.md"
    - tests/**
    - ci/**

    # Sparse checkout (only fetch specific paths)
    sparse_paths:
    - src
    - lib

    # Tag behavior options
    fetch_tags: true                      # Fetch all tags
    clean_tags: true                      # Delete cached tags before fetch
    tag_behaviour: match_tagged           # or match_tag_ancestors

    # Security
    skip_ssl_verification: false
    commit_verification_keys:             # GPG keys for signature verification
    - |
      -----BEGIN PGP PUBLIC KEY BLOCK-----
      ...
      -----END PGP PUBLIC KEY BLOCK-----

    # Git-crypt support
    git_crypt_key: ((git-crypt-key-base64))

    # Proxy configuration
    https_tunnel:
      proxy_host: proxy.example.com
      proxy_port: 8080
      proxy_user: ((proxy.user))
      proxy_password: ((proxy.pass))

    # Advanced options
    disable_ci_skip: false                # Process [ci skip] commits
    version_depth: 100                    # Versions returned in check
    search_remote_refs: false             # Search remote refs (Gerrit)

    # Commit filtering
    commit_filter:
      exclude:
        - "\\[skip ci\\]"
        - "Merge pull request"
      include:
        - "\\[deploy\\]"

    # Git config
    git_config:
    - name: core.autocrlf
      value: input

    # Submodule credentials
    submodule_credentials:
    - host: github.com
      username: ((github.user))
      password: ((github.token))

Get Parameters

- get: source-repo
  params:
    depth: 1                              # Shallow clone depth
    fetch_tags: true                      # Override source setting
    clean_tags: true                      # Delete tags before checkout
    submodules: all                       # none, all, or [list]
    submodule_recursive: true             # Recursive submodule checkout
    submodule_remote: true                # Checkout for remote branch
    disable_git_lfs: false                # Skip LFS files
    all_branches: false                   # Fetch all branches

    # Output formatting
    short_ref_format: "%s"                # Printf format for short_ref
    timestamp_format: iso8601             # Commit timestamp format
    describe_ref_options: "--always --dirty"

Put Parameters

- put: source-repo
  params:
    repository: modified-repo             # Required: path to repo

    # Branching
    branch: release                       # Target branch (default: source)
    refs_prefix: refs/heads               # Reference prefix

    # Tagging
    tag: version/tag-file                 # File containing tag name
    tag_prefix: "v"                       # Prepend to tag
    only_tag: true                        # Push only tags, not commits
    annotate: version/annotation-file     # Annotated tag message

    # Push behavior
    force: false                          # Force push
    rebase: false                         # Rebase on conflict
    rebase_strategy: recursive            # ort, octopus, ours, subtree
    rebase_strategy_option: theirs        # -X option
    merge: false                          # Merge on conflict
    returning: merged                     # merged or unmerged (with merge)

    # Notes
    notes: notes/note-file                # Git notes file

Metadata Files (after get)

.git/ref              # Full commit SHA
.git/short_ref        # Short SHA (configurable)
.git/commit_message   # Commit message
.git/author           # Author name
.git/author_date      # Author date
.git/committer        # Committer name
.git/committer_date   # Committer date
.git/branch           # Branch name
.git/tags             # Space-separated tags
.git/describe_ref     # Git describe output
.git/metadata.json    # JSON with all metadata

---

Registry Image Resource (concourse/registry-image-resource)

Tracks OCI/Docker images in container registries.

Source Configuration

resources:
- name: app-image
  type: registry-image
  source:
    # Required
    repository: registry.example.com/org/app

    # Tag tracking (choose one mode)
    # 1. Single tag tracking
    tag: latest                           # Default: latest

    # 2. Regex-based tag tracking
    tag_regex: "^[0-9]+\\.[0-9]+\\.[0-9]+$"
    created_at_sort: true                 # Sort by creation time

    # 3. Semver auto-detection (no tag/tag_regex)
    variant: alpine                       # Filter by suffix (1.2.3-alpine)
    semver_constraint: "~1.2.x"           # Semver range
    pre_releases: false                   # Include prereleases
    pre_release_prefixes: [alpha, beta, rc]

    # Authentication
    username: ((registry.username))
    password: ((registry.password))

    # AWS ECR authentication
    aws_access_key_id: ((aws.key_id))
    aws_secret_access_key: ((aws.secret))
    aws_session_token: ((aws.token))
    aws_region: us-east-1
    aws_role_arn: arn:aws:iam::123:role/ecr-role
    aws_role_arns:                        # Role chain
    - arn:aws:iam::123:role/first
    - arn:aws:iam::456:role/second
    aws_account_id: "123456789"           # For ECR

    # Platform selection (multi-arch images)
    platform:
      architecture: amd64                 # amd64, arm64, etc.
      os: linux                           # linux, windows

    # Security
    insecure: false                       # Allow insecure registries
    ca_certs:                             # Custom CA certificates
    - |
      -----BEGIN CERTIFICATE-----
      ...
      -----END CERTIFICATE-----

    # Docker Content Trust
    content_trust:
      server: https://notary.example.com
      repository_key_id: abc123
      repository_key: ((notary.key))
      repository_passphrase: ((notary.pass))
      tls_key: ((tls.key))
      tls_cert: ((tls.cert))

    # Fallback registry mirror
    # ⚠️ CRITICAL: registry_mirror must be an OBJECT, not a string!
    # The host field must be a bare hostname (RFC 3986 authority) — NO scheme.
    # See "registry_mirror Format Differences" section below.
    registry_mirror:
      host: mirror.example.com            # ✅ Correct: hostname only
      # host: https://mirror.example.com  # ❌ Wrong: includes scheme
      username: ((mirror.user))
      password: ((mirror.pass))

    debug: false

Get Parameters

- get: app-image
  params:
    format: rootfs                        # rootfs, oci, oci-layout
    skip_download: false                  # Skip image download (optimization)
    platform:                             # Override source platform
      architecture: arm64
      os: linux

Optimization: skip_download

Use skip_download: true when you only need version metadata without the image:

# Check if new version exists without downloading
- get: base-image
  params:
    skip_download: true
  trigger: true

# Later, download only when needed
- get: base-image
  passed: [check-job]
  # No skip_download = full download

Put Parameters

- put: app-image
  params:
    # Required: image source (choose one)
    image: build-output/image.tar         # OCI tarball
    # OR oci-layout directory

    # Tagging
    version: version/version-file         # Version number as tag
    bump_aliases: true                    # Auto-tag 1.2, 1, latest
    additional_tags: tags/tags-file       # Whitespace-separated tags
    tag_prefix: "v"                       # Prefix for additional_tags

Output Files (after get)

rootfs format:

rootfs/           # Unpacked filesystem
metadata.json     # Image metadata
labels.json       # Image labels
repository        # Repository name
tag               # Tag name
digest            # Image digest

oci format:

image.tar         # OCI tarball
labels.json
repository
tag
digest

---

Time Resource (concourse/time-resource)

Triggers on time intervals.

resources:
- name: every-hour
  type: time
  icon: clock-outline
  source:
    interval: 1h                          # Trigger interval

- name: weekday-morning
  type: time
  source:
    start: 9:00 AM
    stop: 9:30 AM
    location: America/New_York
    days: [Monday, Tuesday, Wednesday, Thursday, Friday]

---

S3 Resource (concourse/s3-resource)

Interacts with S3-compatible storage.

resources:
- name: artifacts
  type: s3
  source:
    bucket: my-bucket
    regexp: releases/app-(.*)\.tar\.gz    # Version from filename
    # OR
    versioned_file: releases/app.tar.gz   # S3 versioning

    access_key_id: ((aws.key))
    secret_access_key: ((aws.secret))
    region_name: us-east-1

    # Non-AWS S3-compatible
    endpoint: https://minio.example.com
    disable_ssl: false

    # IAM role (instead of keys)
    use_v2_signing: false

---

Semver Resource (concourse/semver-resource)

Manages semantic versions.

resources:
- name: version
  type: semver
  source:
    driver: git                           # git, s3, gcs, swift
    uri: git@github.com:org/version.git
    branch: main
    file: version
    private_key: ((git.private_key))
    initial_version: 0.0.1

# Usage
- get: version
  params:
    bump: minor                           # major, minor, patch
    pre: rc                               # Add prerelease suffix

---

Pool Resource (concourse/pool-resource)

Manages locks and shared state.

resources:
- name: env-lock
  type: pool
  source:
    uri: git@github.com:org/locks.git
    branch: main
    pool: environments
    private_key: ((git.private_key))

# Acquire lock
- put: env-lock
  params:
    acquire: true

# Release lock
- put: env-lock
  params:
    release: env-lock

---

registry_mirror Format Differences (registry-image vs docker-image)

⚠️ CRITICAL GOTCHA: registry-image and docker-image expect completely different formats for registry_mirror. Getting this wrong causes opaque errors at check time.

registry-image (modern, pure Go binary — no Docker daemon)

registry-image:
  registry_mirror:
    host: registry-mirror.example.com     # Object with host field
    # host must be RFC 3986 URI authority = hostname only, NO scheme

Errors if misconfigured:

• Passing a string instead of object: json: cannot unmarshal string into Go struct field Source.source.registry_mirror of type resource.RegistryMirror
• Including scheme in host: registries must be valid RFC 3986 URI authorities: https://registry-mirror.example.com

docker-image (legacy, has Docker daemon internally)

docker-image:
  registry_mirror: https://registry-mirror.example.com  # Plain URL string with scheme

Docker daemon handles the URL parsing internally, so it accepts the full URL.

CONCOURSE_BASE_RESOURCE_TYPE_DEFAULTS interaction

Concourse web nodes can inject default source params into all resource type checks via CONCOURSE_BASE_RESOURCE_TYPE_DEFAULTS. This is typically configured in /etc/concourse/resource-type-defaults.yml (Ansible-managed). The config must provide both formats:

registry-image:
  registry_mirror:
    host: registry-mirror.example.com       # Object format for registry-image

docker-image:
  registry_mirror: https://registry-mirror.example.com  # String format for docker-image

Note: This is a web node setting, not a worker setting. Restart concourse-web after changes.

Ansible role template pattern (Jinja2)

When the mirror URL variable includes a scheme (e.g., https://registry-mirror.example.com), strip it for the registry-image host field:

registry-image:
  registry_mirror:
    host: {{ concourse_worker_registry_mirror_url | regex_replace('^https?://', '') }}

docker-image:
  registry_mirror: {{ concourse_worker_registry_mirror_url }}

---

GitLab Container Registry JWT Auth Discovery

⚠️ GOTCHA: The JWT auth endpoint for GitLab Container Registry is on the GitLab host, NOT the registry host.

When scripting against a GitLab Container Registry (e.g., registry.example.com), never hardcode the JWT auth URL. Discover it dynamically:

# Discover auth realm from registry's Www-Authenticate header
AUTH_HEADER=$(curl -s -o /dev/null -D - "https://${REGISTRY_URL}/v2/" \
  | grep -i www-authenticate)
if [ -z "${AUTH_HEADER}" ]; then
  echo "Error: Failed to get Www-Authenticate header from ${REGISTRY_URL}" >&2
  exit 1
fi
REALM=$(echo "${AUTH_HEADER}" | sed -n 's/.*realm="\([^"]*\)".*/\1/p')
SERVICE=$(echo "${AUTH_HEADER}" | sed -n 's/.*service="\([^"]*\)".*/\1/p')

# Request token
TOKEN=$(curl -sf -u "${USER}:${PASSWORD}" \
  "${REALM}?service=${SERVICE}&scope=repository:${REPO}:pull" \
  | jq -r '.token')

Example: For registry.netresearch.de, the realm is https://git.netresearch.de/jwt/auth (GitLab host), not https://registry.netresearch.de/jwt/auth.

---

Docker Image Resource (concourse/docker-image-resource)

⚠️ LEGACY: The docker-image resource is deprecated. Use oci-build-task + registry-image for new pipelines.

Migration Guide: docker-image → oci-build-task

Before (Legacy docker-image):

resources:
- name: app-image
  type: docker-image
  source:
    repository: registry.example.com/org/app
    username: ((registry.user))
    password: ((registry.pass))

jobs:
- name: build
  plan:
  - get: source
  - put: app-image
    params:
      build: source
      build_args:
        NODE_VERSION: "20"
      docker_buildkit: 1

After (Modern oci-build-task + registry-image):

resources:
- name: app-image
  type: registry-image
  source:
    repository: registry.example.com/org/app
    username: ((registry.user))
    password: ((registry.pass))

jobs:
- name: build
  plan:
  - get: source
  - task: build
    privileged: true
    config:
      platform: linux
      image_resource:
        type: registry-image
        source:
          repository: concourse/oci-build-task
      inputs:
      - name: source
      outputs:
      - name: image
      params:
        CONTEXT: source
        BUILD_ARG_NODE_VERSION: "20"
      caches:
      - path: cache
      run:
        path: build
  - put: app-image
    params:
      image: image/image.tar

Why Migrate?

Legacy docker-image Reference

If migrating existing pipelines, here's the legacy syntax:

resources:
- name: app-image
  type: docker-image
  source:
    repository: registry.example.com/org/app
    username: ((registry.user))
    password: ((registry.pass))
    tag: latest

# Build and push
- put: app-image
  params:
    build: source-repo                    # Dockerfile context
    dockerfile: source-repo/Dockerfile
    tag_file: version/version             # Dynamic tag
    tag_as_latest: true
    build_args:
      BUILD_ARG: value
    cache: true
    cache_tag: cache
    load_base: base-image                 # Pre-loaded base
    docker_buildkit: 1                    # Enable BuildKit

Passing Images Between Jobs (Legacy Pattern)

When using docker-image, pass images between jobs with save/load:

# Job 1: Build and save
- get: app-image
  params:
    save: true  # Save image layers for downstream jobs

# Job 2: Load and use
- get: app-image
  passed: [build]
  params:
    save: true
- put: app-image
  params:
    load: app-image  # Load from previous get
    tag_file: version/tag

Modern alternative: Use task outputs with image.tar artifact.

---

Slack Notification Resource

Common community resource for Slack notifications.

resource_types:
- name: slack-notification
  type: registry-image
  source:
    repository: cfcommunity/slack-notification-resource
    tag: latest

resources:
- name: slack
  type: slack-notification
  source:
    url: ((slack.webhook_url))

# Send notification
- put: slack
  params:
    text: "Build $BUILD_PIPELINE_NAME/$BUILD_JOB_NAME completed"
    channel: "#builds"
    username: Concourse CI
    icon_emoji: ":concourse:"

---

HTTP Resource

For webhook triggers and HTTP interactions.

resource_types:
- name: http-resource
  type: registry-image
  source:
    repository: jgriff/http-resource

resources:
- name: webhook
  type: http-resource
  source:
    url: https://api.example.com/webhook
    method: POST
    headers:
      Content-Type: application/json
      Authorization: Bearer ((api.token))
    out_only: true                        # Disable implicit get
    sensitive: true                       # Hide response
    build_metadata: [headers, body]       # Resolve CI vars