Build a CI/CD Pipeline with AI

Most CI/CD pipelines look like they were grown rather than designed. A YAML file from a tutorial got copied in. Somebody added a deploy step. Somebody else added a cache step that may or may not work. The test step was extended every time a new test framework joined the project, and the artifact upload was added the day a postmortem revealed nobody could find the failed test logs. Years later, the pipeline is a working but inscrutable artifact: it deploys the application, the team trusts it within reason, and the cost of cleaning it up never quite justifies the time. The pipeline does its job, and it is doing more work than it needs to do, in a sequence nobody fully understands.

A pipeline designed correctly looks different. The stages are sequenced so that the cheapest, fastest checks run first and fail the build before the expensive ones get to run. Dependencies are cached so the second run of the day finishes in a third of the time of the first. Environment variables and secrets are managed centrally rather than scattered across job definitions. Deploy gates are explicit: a deploy only proceeds when the relevant tests have passed, when the right approvers have approved, when the target environment is in a state that accepts the deploy. The discipline is well-known and rarely applied to existing pipelines because the cost of refactoring a working pipeline is high. The /relay-pipeline skill is built to apply the discipline at greenfield: it generates the pipeline correctly the first time so the cleanup task never needs to be scheduled.

Why generalist AI produces tutorial-shaped pipelines

Ask Cursor or ChatGPT to write a CI pipeline for a Node.js project. You get a YAML file that runs npm install, npm test, and npm run build. The file looks correct. It also has no caching, no parallelization, no environment-specific deploy steps, no concurrency control, no artifact upload on failure, and no SLA on the run time. The file is a starter kit. The team will live with the starter kit for years because the cost of evolving it is paid in YAML edits that produce mysterious failures. The fact that the pipeline runs is treated as evidence that it does not need work, even when it is taking three times longer than it should and missing the gates that would have caught a recent incident.

The deeper problem is that pipeline design depends on the project. The right caching strategy depends on which package manager and lockfile the project uses. The right test parallelization depends on the test framework and the suite shape. The right deploy gate depends on the target platform (a Vercel deploy is different from a Kubernetes rolling deploy is different from an ECS task update). A generic pipeline cannot calibrate to those, and a generic pipeline is what generalist tools produce because they cannot read the project to find out what it needs.

What a calibrated pipeline requires

A correctly designed pipeline has five layers. First, the trigger configuration: which events run the pipeline, with concurrency control so a new push cancels an in-flight run on the same branch. Second, the dependency layer: cache configuration that recognizes lockfile changes, scoped per package manager, with a cache key that survives normal commits and busts on real dependency changes. Third, the test layer: parallelization that splits the test suite across runners so the wall-clock time matches the slowest single test rather than the sum of all tests. Fourth, the build artifact layer: the build outputs are uploaded with a cache that the deploy step reads, so the deploy never rebuilds. Fifth, the deploy layer: environment-specific deploy logic with the right gates (manual approval for production, automatic for preview), the right rollback path, and the right notification on failure.

Each layer has trade-offs that depend on the project. Cache too aggressively and a real dependency change does not get a fresh install. Parallelize too much and the runner cost outweighs the time savings. Add too many deploy gates and the pipeline becomes the bottleneck. The discipline is to make each decision deliberately rather than copy them from a tutorial. The senior platform engineer who designs a pipeline well asks each question explicitly. /relay-pipeline asks the same questions and produces the calibrated result.

How /relay-pipeline works

Step one: detect the stack

Before generating any YAML, /relay-pipeline reads the repository to detect the stack: the language and runtime, the package manager and lockfile, the test framework, the build tool, and the deploy target. Each detection drives a calibration decision. Node with pnpm gets a different cache configuration than Node with npm. A Vite build gets a different build cache from a Next.js build. A Vercel deploy gets a different gate from a Kubernetes deploy. The skill is opinionated about reading the repository rather than asking the user to specify the stack; the repository is the source of truth, and the pipeline should match it.

Step two: produce the pipeline config

The pipeline is generated for the platform the project uses. GitHub Actions is the default; GitLab CI, CircleCI, Cloud Build, Buildkite, and Jenkins are also supported. The output is the YAML or HCL config plus the supporting files (cache configs, deploy scripts, environment files). The config includes structured comments so the next person reading it understands why each decision was made: "this cache key includes the lockfile hash so a normal commit does not bust the cache," "this concurrency block cancels in-flight runs on the same PR." The comments are part of the artifact, not optional decoration.

Step three: deploy gates and rollback

The deploy section is calibrated to the target environment. Preview deploys (PR previews) are automatic on every push. Staging deploys are automatic on every merge to the main branch. Production deploys require manual approval by default, with the option to make them automatic if the project has the test coverage to justify it. Each deploy step has a rollback path: how to revert if the deploy succeeds but the application breaks, how to fail forward if the deploy fails halfway through. The rollback paths are documented in the YAML so the on-call engineer does not have to invent them at 2am.

Step four: secrets and environment management

Secrets are managed centrally rather than scattered across jobs. The skill generates the secret references and produces a separate document listing every secret the pipeline needs and where it is expected to live (GitHub Actions secrets, GCP Secret Manager, Doppler, etc.). Environment variables that are not secrets are handled the same way: declared once, referenced everywhere. The cleanup pass removes any inline secret values it finds in the existing pipeline, replacing them with references and producing a list for the operator to provision.

Tonone's /relay-pipeline skill builds calibrated CI/CD pipelines from scratch with proper stage sequencing, dependency caching, deploy gates, and rollback paths.

When to use /relay-pipeline, and when not to

/relay-pipeline is the right call when a new service needs CI/CD and nothing exists yet, or when an existing pipeline is so broken or outdated that rebuilding correctly is faster than patching. The signal is when the team is shipping code manually, when the existing pipeline takes longer than 15 minutes for a routine PR, or when deploys regularly fail in ways the pipeline did not catch.

Skip the skill for incremental changes to a working pipeline (adding a new test job, updating the runner version). For container builds specifically, /relay-docker produces production-ready Dockerfiles. For deployment configuration that is more complex than a single deploy step, /relay-deploy generates the full deploy spec. For an audit of an existing pipeline, /relay-audit is the right call.

A worked example: pipeline for a Next.js app on Vercel

Suppose the brief is: build a CI/CD pipeline for a Next.js application that deploys to Vercel. Run /relay-pipeline and the output is the GitHub Actions workflow plus the Vercel project config plus the secrets list.

# .github/workflows/ci.yml (excerpt)
name: ci
on:
  push:
    branches: [main]
  pull_request:
concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v3
        with: { version: 9 }
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm typecheck
      - run: pnpm test --shard=${{ matrix.shard }}/4
    strategy:
      matrix:
        shard: [1, 2, 3, 4]

  e2e:
    runs-on: ubuntu-latest
    needs: test
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v3
        with: { version: 9 }
      - uses: actions/setup-node@v4
        with: { node-version: 20, cache: pnpm }
      - run: pnpm install --frozen-lockfile
      - run: pnpm exec playwright install --with-deps chromium
      - run: pnpm e2e
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 7

# Deploys are managed by Vercel's GitHub integration:
# - PR opens   -> preview deploy at <pr>.<project>.vercel.app
# - merge main -> production deploy with the gating env protection rule
#
# Required secrets (provisioned in repo settings):
# - VERCEL_TOKEN (Vercel CLI for promotion)
# - SENTRY_AUTH_TOKEN (source map upload during build)

The pipeline runs typecheck and tests in parallel shards (test wall-clock time is the slowest shard, not the sum), runs E2E only after unit tests pass (so a unit failure stops the expensive E2E run), uploads the Playwright report on E2E failure, and lets Vercel handle the actual deploy with environment protection rules. Total run time on a clean cache: about 6 minutes. On a warm cache: about 2 minutes.

Related skills

/relay-pipeline builds the pipeline. For container builds, /relay-docker produces production-ready Dockerfiles. For complex deployment specs (Kubernetes manifests, Terraform deploys), /relay-deploy produces the full deploy configuration. For auditing an existing pipeline, /relay-audit produces the gap report.

Install

/relay-pipeline ships with the Relay agent in the Tonone for Claude Code package. Install Tonone, invoke /relay-pipeline from any Claude Code session, and the skill produces a calibrated pipeline for the project's stack and deploy target.

Pipelines are the part of the codebase that runs on every commit, which means a slow or wrong pipeline is a tax on every change. The skill is built so the pipeline is right the first time, before the tax compounds.