README

Concourse CI Skill

Agent Skill for expert Concourse CI pipeline development, optimization, and troubleshooting.

Supported Platforms

Platform	Status
Claude Code (Anthropic)	✅ Supported
Cursor	✅ Supported
GitHub Copilot	✅ Supported
Other skills-compatible AI agents	✅ Supported

Features

Pipeline Creation: Write production-ready Concourse CI pipelines with proper structure
Resource Configuration: Configure git-resource, registry-image-resource, and 50+ resource types
Optimization: Parallel execution, task caching, resource filtering patterns
Troubleshooting: Debug common issues including git tag detection problems
Best Practices: YAML anchors for DRY, job lifecycle hooks, webhook triggers
Multi-Branch Pipelines: Dynamic pipeline management with set_pipeline and across
Container Builds: OCI image building with oci-build-task and versioning

Installation

Marketplace (Recommended)

Add the Netresearch marketplace once, then browse and install skills:

# Claude Code
/plugin marketplace add netresearch/claude-code-marketplace
/plugin install concourse-ci@netresearch-claude-code-marketplace

Without a marketplace

Since Claude Code 2.1.157 a plugin directory under your personal skills directory loads on its own:

mkdir -p ~/.claude/skills
git clone https://github.com/netresearch/concourse-ci-skill.git \
  ~/.claude/skills/concourse-ci

It loads as concourse-ci@skills-dir on the next session. Update with git -C ~/.claude/skills/concourse-ci pull and start a new session; remove it by deleting the directory. This route has no claude plugin update.

npx (skills.sh)

Install with any Agent Skills-compatible agent:

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

Download Release

Download the latest release and extract to your agent's skills directory.

Git Clone

git clone https://github.com/netresearch/concourse-ci-skill.git

Composer (PHP Projects)

composer require netresearch/concourse-ci-skill

Requires netresearch/composer-agent-skill-plugin.

npm (Node Projects)

npm install --save-dev \
  @netresearch/agent-skill-coordinator \
  github:netresearch/concourse-ci-skill

Requires @netresearch/agent-skill-coordinator, which discovers the skill in node_modules and registers it in AGENTS.md via a postinstall hook. For pnpm, also allowlist the coordinator's postinstall:

{
  "pnpm": {
    "onlyBuiltDependencies": ["@netresearch/agent-skill-coordinator"]
  }
}

Usage

The skill activates automatically when you work with Concourse CI topics:

"Create a Concourse pipeline for my Node.js app"
"Configure git-resource with tag filtering"
"Debug why my pipeline isn't detecting new tags"
"Optimize my Concourse CI build times"
"Add webhook triggers to my pipeline"

Skill Contents

skills/concourse-ci/
├── SKILL.md                          # Core guidance
├── references/
│   ├── pipeline-syntax.md            # Complete YAML schema
│   ├── resources-guide.md            # Git, registry-image, docker-image migration
│   ├── best-practices.md             # Optimization, notifications, deployment
│   └── resource-types-catalog.md     # 50+ resource types incl. Ansible, Terraform
├── examples/
│   ├── basic-pipeline.yml            # Build-test-deploy with oci-build-task
│   ├── modern-ci-cd.yml              # Modern patterns: across, build_log_retention
│   ├── multi-branch.yml              # Dynamic branch pipelines
│   ├── docker-build.yml              # OCI image building with versioning
│   └── vars-template.yml             # Variable file organization
└── scripts/
    └── validate-pipeline.sh          # Pipeline validation script

Key Topics Covered

Pipeline Architecture

Resources, jobs, steps, and resource types
Job lifecycle hooks (on_success, on_failure, on_error, on_abort, ensure)
Step types (get, put, task, set_pipeline, in_parallel, do, try)
Variable syntax and credential management

Critical Gotchas

Git Resource Tag Detection - The skill documents the notorious issue where Concourse stops detecting tags after force-pushing, including root causes and solutions:

# Enable tag cleanup to fix detection issues
resources:
- name: repo
  type: git
  source:
    uri: ((git.uri))
    branch: main
    tag_regex: "^v[0-9]+\\.[0-9]+\\.[0-9]+$"
    fetch_tags: true
    clean_tags: true  # Critical fix

Optimization Patterns

Parallel step execution with in_parallel
Task caching for dependencies
Shallow clones with depth: 1
Resource path filtering
Serial groups for resource contention

Compatibility

Concourse v8.0+ (current)
Legacy support for v6.5+ where noted

Related Resources

Development and tests

The shell scripts have behaviour tests in tests/:

tests/validate-pipeline.sh runs skills/concourse-ci/scripts/validate-pipeline.sh against pipeline fixtures: usage and missing-file errors, valid and invalid YAML (also after a long valid document), missing jobs and resources, literal versus ((var)) credentials, tag_regex findings, resource names with quotes or backslash sequences, jobs without a triggering get, the exit when yq is missing, the python3 syntax check with a quote in the path, every example pipeline under skills/concourse-ci/examples/, and the fly branch through a stub. It needs yq v4 and GNU grep; a locally installed fly is never called.
tests/check-plugin-version.sh covers Build/Scripts/check-plugin-version.sh, the version comparison the pre-push hook runs.

Run them locally from the repository root:

for t in tests/*.sh; do bash "$t" || exit 1; done

Each test prints ok or FAIL per case, followed by the captured output of a failing case, and exits non-zero if any case failed. CI runs the same files on every pull request and on pushes to main (.github/workflows/tests.yml). The pre-commit hooks in .pre-commit-config.yaml run the linters that lint.yml runs in CI.

New or changed behaviour in a script needs a test case in tests/ in the same pull request.

Governance and policies

This repository follows the Netresearch organisation policies:

Governance: who decides, how changes are accepted, and how disputes are resolved.
Roadmap: planned and excluded work for the coming year.
Handling of dependency and code analysis findings: thresholds, deadlines and exceptions for dependency and static-analysis findings.
Secret management: how CI and release credentials are stored, accessed and rotated.
Access roster: the accounts that can change code, settings or releases of this repository, with their access level.
Security assurance case: threat model, trust boundaries and countermeasures for this skill.

Every pull request to main runs these security checks (.github/workflows/security.yml): dependency review, Composer Audit, Opengrep (static analysis), Betterleaks (secret scanning), zizmor (workflow analysis) and CodeQL (analysis of the GitHub Actions workflows).

License

This project uses split licensing:

Code (scripts, workflows, configs): MIT
Content (skill definitions, documentation, references): CC-BY-SA-4.0

See the individual license files for full terms.

Author

Netresearch DTT GmbH

Website: netresearch.de
GitHub: @netresearch

netresearch / concourse-ci-skill

Package info

Security

Statistics