Use when working with ANY Concourse CI task: writing pipelines, configuring resources, building images with oci-build-task, troubleshooting failing jobs, migrating from legacy patterns, or optimizing CI/CD.
Use when working with ANY Concourse CI task: writing pipelines, configuring resources, building images with oci-build-task, troubleshooting failing jobs, migrating from legacy patterns, or optimizing CI/CD.
Troubleshooting resource check failures or build issues
Migrating from legacy patterns (docker-image, duplicate jobs)
Quick Reference
Task
Modern (Recommended)
Legacy (Avoid)
Building images
oci-build-task + registry-image
docker-image resource
Multi-env deploys
across step modifier
Duplicate jobs per env
Dynamic pipelines
set_pipeline + instanced pipelines
Manual pipeline duplication
Notification symbols
UTF-8 characters (e.g. \u2714 for checkmark, \u274c for X)
HTML entities (e.g. ✓, ✗)
Resource styling
Always use icon: property
No icon
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, setpipeline, inparallel, do, try, loadvar. Job hooks: onsuccess, onfailure, onerror, onabort, ensure. Note: onfailure (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
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.
registrymirror format mismatch -- registry-image expects an object (host: mirror), docker-image expects a URL string. Provide separate formats in CONCOURSEBASERESOURCETYPE_DEFAULTS. See references/resources-guide.md.
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.
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