mcpField
C
concourse-ci

concourse-ci

github.com/netresearchCloud & DevOps381 installsUpdated 1d ago
Repository

About concourse-ci

A reference skill for creating, refactoring, and troubleshooting Concourse CI pipelines, targeting Concourse v8.0 and later. It combines pipeline guidance with migration notes, operational gotchas, examples, and a syntax validation script.

Key features

  1. 01Pipeline creation and refactoring guidance
  2. 02Resource and job configuration
  3. 03Container image build patterns
  4. 04Legacy pattern migration notes
  5. 05Examples and syntax validation script

Use cases

  1. 01Creating or modifying Concourse pipelines
  2. 02Troubleshooting resource checks and builds
  3. 03Migrating from legacy pipeline patterns
  4. 04Validating pipeline YAML before deployment

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/netresearch/concourse-ci-skill --skill concourse-ci

After installing, type/concourse-ciin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

checkpoints.yaml
examples/
basic-pipeline.yml
docker-build.yml
modern-ci-cd.yml
multi-branch.yml
vars-template.yml
references/
best-practices.md
core-concepts.md
pipeline-syntax.md
resource-types-catalog.md
resources-guide.md
scripts/
validate-pipeline.sh

Details

From the project README

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

TaskModern (Recommended)Legacy (Avoid)
Building imagesoci-build-task + registry-imagedocker-image resource
Multi-env deploysacross step modifierDuplicate jobs per environment
Dynamic pipelinesset_pipeline + instanced pipelinesManual pipeline duplication
Notification symbolsUTF-8 characters (e.g. \u2714 for checkmark, \u274c for X)HTML entities (e.g. ✓, ✗)
Resource stylingAlways use icon: propertyNo 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, 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.

Comments

Markdown supported