Vibe coding with Claude Code course · Module 13: Twitch clone

A Pipeline under the Flag: CI Written by Claude Code

9 min read
In this lesson7

The crate is packed but one more hole is left in the port. Before every commit you run lint, tests and the build, because it is your habit. The bosun is in a hurry: he pushes to main a change he did not build, and in the morning nobody can sail. You need a lighthouse keeper who checks every ship before it enters the port, no matter who sails it.

That lighthouse keeper is CI (continuous integration): on every change a server runs by itself the same checks you run locally. On GitHub this is done by GitHub Actions. You write the instructions in a YAML file in the .github/workflows/ folder, and such a file is called a workflow. The result shows by the commit and by the pull request, which you know from lesson 1_5 as a request to merge a branch with room for code review: a green tick or a red cross.

What you will learn

  • describe to Claude Code the goal of the checks instead of dictating YAML, and have it check the action versions instead of guessing;
  • read a workflow key by key: on, permissions, jobs, steps;
  • recognise a green test that tests nothing;
  • run Claude Code without a conversation, through claude -p, with narrow permissions and a JSON result;
  • keep the deployment token in the repository secrets, not in the request.

Request for Claude Code

The request says what should happen and when, not what the file should look like. Two sentences in it matter most: the one about the action versions and the one about a missing script.

Request for Claude Code:

Add a GitHub Actions workflow in .github/workflows/ci.yml: on push
and pull request to main install dependencies (npm ci), run lint,
tests in a single run and the build. Check with gh the latest releases
of actions/checkout and actions/setup-node and use their major versions,
and Node.js in the current LTS version. Workflow token read-only.
If any script is missing from package.json, tell me about it
instead of inventing it. Skip deployment for now.
Done when: ci.yml parses, and npm ci, npm run lint,
npm run test -- --run and npm run build pass locally.

The agent does not know the action versions. It remembers the ones from the texts it learned from, and examples on the web often lag a few releases behind. That is why you tell it to check, and it will ask for permission to run the gh command from lesson 1_5:

gh api repos/actions/checkout/releases/latest --jq .tag_name

gh api asks the GitHub API for the latest release of the action's repository, and --jq .tag_name cuts the version name alone out of the answer. The same goes for actions/setup-node. For us it came out as v7.0.1 and v7.1.0, so the workflow uses @v7, and the current Node.js LTS is 26 (as of November 2026).

What Claude wrote: the workflow key by key

Open .github/workflows/ci.yml in Cursor. At the top stand the name and the moment the workflow starts:

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

on says which events start the workflow: here a push to main and a pull request aimed at main. A push to another branch starts nothing by itself; the check starts when you open a pull request from that branch, and runs again on every further commit in that pull request. Next come the permissions:

permissions:
  contents: read

permissions sets what the token GitHub gives the workflow for the duration of the run (GITHUB_TOKEN) can do. The GitHub documentation advises keeping the minimum, and when you list even one permission, all the unlisted ones get none. Our workflow only reads the code, so it will write nothing to the repository, even if someone slipped a malicious step into it. Now the actual work:

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 26

jobs is the list of jobs; our only one is called check, and runs-on picks the machine on which GitHub will run it. steps are the steps of that job, executed in order. uses runs a ready-made action: checkout fetches the repository code onto the machine, and setup-node installs Node.js in the version from node-version. At the end come four commands:

      - run: npm ci
      - run: npm run lint
      - run: npm run test -- --run
      - run: npm run build

run executes a command in the machine's shell. When a step fails, the job ends with an error, and the following steps do not start. --run tells Vitest to do a single run and exit. GitHub sets the variable CI=true on its machines, and according to the Vitest documentation, in CI it switches to a single run by itself, but writing it explicitly works the same on your machine and is already in CLAUDE.md from lesson 12_1. For us the file parsed, and all four commands passed locally with CI=true.

The green lie

Our clone has had Vitest since lesson 12_1, but many projects have no tests at all. Then the test step ends right at the start, as it did for us in a project without a test script:

npm error Missing script: "test"

A typical agent mistake is a "fix" in package.json: the script "test": "exit 0" or "test": "echo ok". The workflow then shines green and checks nothing. That is why the request says to report a missing script. In the diff you spot this trick at once: package.json changed in the same step as the workflow, although nobody asked for new scripts.

A check before the push: claude -p

The workflow will run only on GitHub. Before you push the file, you can have Claude quickly compare the workflow with the scripts, and without opening a conversation. Non-interactive mode, claude -p, takes one request, prints the result and exits. The documentation calls it the Agent SDK on the command line: the same agent and the same tools, only without the window. Type in a separate terminal tab, in the project folder:

claude -p "Compare the run steps in .github/workflows/ci.yml with the scripts in package.json and list the missing scripts." --allowedTools "Read" --permission-mode dontAsk --max-turns 3 --output-format json

Every flag narrows the room to manoeuvre:

  • --allowedTools "Read" lists the tools Claude uses without asking;
  • --permission-mode dontAsk rejects every call that in a normal session would wait for your consent; the documentation recommends this mode for locked-down runs in CI, where nobody will answer a question;
  • --max-turns 3 limits the number of agent turns, and by default there is no limit;
  • --output-format json returns the result as JSON instead of plain text.

In the JSON the text of the answer sits in the result field. Next to it are other fields worth a look: num_turns (the number of turns), total_cost_usd (a cost estimate based on API pricing, not a bill) and permission_denials, the list of calls that dontAsk mode rejected. For us the run took about 18 seconds and used three turns. In result Claude printed a table: every run step has its script, and npm ci needs none. It added a note that CI does not run npx tsc --noEmit from CLAUDE.md; next build checks types anyway, which shows in its log as Running TypeScript. The permission_denials field was empty, while with another request it caught the command node -e, which Claude tried to run before it reached for Read. The cost estimate came to about half a dollar, so even a short automation is not free. In a script the jq program extracts the answer alone, for example jq -r '.result', as the documentation shows.

Captain's review

  1. Versions. uses: points at the same major versions that gh api showed, and node-version is the current LTS. From memory the agent types versions from a few years ago.
  2. Permissions. There is permissions with contents: read.
  3. Scripts. Every run step has its script in package.json, and the test step ends by itself thanks to --run.
  4. Secrets. The file contains no token or password.

The real test happens on GitHub. Ask Claude: "Create a branch ci, make a commit, push it and open a pull request to main with gh". On the pull request page a CI check will appear. Click it, and you will see the log of every step. A red cross is no shame, just a lighthouse that works: read which step failed, and give Claude that piece of the log.

Next step

When CI shines green, merge the pull request. The next step is deployment from the workflow, and here the captain sets a hard rule: the Vercel token does not go into the request, a file or the conversation. What you type into a request becomes part of the conversation, and from there it can reach code, a commit or a log, like the contents of the .env file in lesson 8_4. You create the token yourself in the Vercel dashboard and add it yourself on GitHub: in the repository Settings, then Secrets and variables, Actions and New repository secret, name VERCEL_TOKEN. Vercel's guide to GitHub Actions requires two more secrets, VERCEL_ORG_ID and VERCEL_PROJECT_ID, from the .vercel/project.json file that vercel link creates. Then you ask:

Request for Claude Code:

Add a preview deployment to Vercel following Vercel's guide
to GitHub Actions. Read the token from the VERCEL_TOKEN secret, the IDs
from VERCEL_ORG_ID and VERCEL_PROJECT_ID. You do not need the secret
values, so do not ask for them.

In the file from Claude look for references to secrets instead of values, for example in a line like this one from Vercel's guide:

run: vercel pull --yes --environment=preview --token=${{ secrets.VERCEL_TOKEN }}

GitHub replaces the notation ${{ secrets.VERCEL_TOKEN }} with the value only on its own machine, during the run. The GitHub documentation adds that secrets are not passed to workflows run from forks, the copies of the repository owned by other people. If in lesson 10_5 you imported the repository in the Vercel dashboard, Vercel already deploys by itself after every push: pick one road, not both. In the editor below waits a workflow reader: click the keys and play a simulated run with a missing script or with the agent's green lie.

Remember: a lighthouse does not steer the ship, but every night it makes sure the ship reaches port safely.

Code for this lesson: App.tsx
// CI workflow reader: what the keys of ci.yml mean and what a run on GitHub will show
import { useState } from 'react';

type KeyName = 'on' | 'permissions' | 'jobs' | 'steps';
type TestScript = 'vitest' | 'none' | 'fake';
type StepStatus = 'ok' | 'fail' | 'skipped';

interface StepResult {
  name: string;
  status: StepStatus;
  log: string;
}

const WORKFLOW: { text: string; key?: KeyName }[] = [
  { text: 'name: CI' },
  { text: 'on:', key: 'on' },
  { text: '  push:', key: 'on' },
  { text: '    branches: [main]', key: 'on' },
  { text: '  pull_request:', key: 'on' },
  { text: '    branches: [main]', key: 'on' },
  { text: 'permissions:', key: 'permissions' },
  { text: '  contents: read', key: 'permissions' },
  { text: 'jobs:', key: 'jobs' },
  { text: '  check:', key: 'jobs' },
  { text: '    runs-on: ubuntu-latest', key: 'jobs' },
  { text: '    steps:', key: 'steps' },
  { text: '      - uses: actions/checkout@v7', key: 'steps' },
  { text: '      - uses: actions/setup-node@v7', key: 'steps' },
  { text: '        with:', key: 'steps' },
  { text: '          node-version: 26', key: 'steps' },
  { text: '      - run: npm ci', key: 'steps' },
  { text: '      - run: npm run lint', key: 'steps' },
  { text: '      - run: npm run test -- --run', key: 'steps' },
  { text: '      - run: npm run build', key: 'steps' },
];

const EXPLAIN: Record<KeyName, string> = {
  on: 'on: when the workflow starts. Here on a push to main and on a pull request aimed at main.',
  permissions: 'permissions: what the run token can do. contents: read only allows reading the code; the other permissions get none.',
  jobs: 'jobs: the jobs of the workflow. One job, check, and runs-on picks the machine on which GitHub will run it.',
  steps: 'steps: the steps of the job, in order. uses runs a ready-made action, run executes a command in the shell.',
};

export function simulateRun(testScript: TestScript, lintError: boolean): StepResult[] {
  const plan: { name: string; run: () => { ok: boolean; log: string } }[] = [
    { name: 'actions/checkout', run: () => ({ ok: true, log: 'Code fetched onto the machine' }) },
    { name: 'actions/setup-node', run: () => ({ ok: true, log: 'Node.js 26 ready' }) },
    { name: 'npm ci', run: () => ({ ok: true, log: 'Dependencies installed according to package-lock.json' }) },
    {
      name: 'npm run lint',
      run: () => (lintError ? { ok: false, log: 'eslint reported an error in components/LiveChat.tsx' } : { ok: true, log: 'eslint found no errors' }),
    },
    {
      name: 'npm run test -- --run',
      run: () => {
        if (testScript === 'none') return { ok: false, log: 'npm error Missing script: "test"' };
        if (testScript === 'fake') return { ok: true, log: '> exit 0 (no test ran)' };
        return { ok: true, log: 'Tests passed: a single run and done' };
      },
    },
    { name: 'npm run build', run: () => ({ ok: true, log: 'Compiled successfully' }) },
  ];

  const results: StepResult[] = [];
  let failed = false;
  for (const step of plan) {
    if (failed) {
      results.push({ name: step.name, status: 'skipped', log: 'Skipped, because an earlier step failed' });
      continue;
    }
    const outcome = step.run();
    results.push({ name: step.name, status: outcome.ok ? 'ok' : 'fail', log: outcome.log });
    if (!outcome.ok) failed = true;
  }
  return results;
}

export function verdict(results: StepResult[], testScript: TestScript): string {
  if (results.some((r) => r.status === 'fail')) return 'Red cross: read the log of the step that failed';
  if (testScript === 'fake') return 'Green tick, but the tests checked nothing: a green lie';
  return 'Green tick: lint, tests and build passed';
}

const STATUS_LABEL: Record<StepStatus, string> = { ok: 'OK', fail: 'Error', skipped: 'Skipped' };
const STATUS_CLASS: Record<StepStatus, string> = { ok: 'text-emerald-400', fail: 'text-red-400', skipped: 'text-zinc-500' };

export default function App() {
  const [active, setActive] = useState<KeyName>('on');
  const [testScript, setTestScript] = useState<TestScript>('vitest');
  const [lintError, setLintError] = useState(false);
  const results = simulateRun(testScript, lintError);

  return (
    <div className="min-h-screen space-y-4 bg-zinc-950 p-4 text-zinc-100">
      <h1 className="text-xl font-bold">Workflow reader: ci.yml</h1>
      <div className="grid gap-4 md:grid-cols-2">
        <pre className="overflow-x-auto rounded bg-zinc-900 p-2 font-mono text-xs leading-5">
          {WORKFLOW.map((line, i) => (
            <div key={i}>
              {line.key ? (
                <button
                  type="button"
                  onClick={() => setActive(line.key as KeyName)}
                  aria-pressed={active === line.key}
                  className={active === line.key ? 'w-full bg-purple-900 text-left whitespace-pre' : 'w-full text-left whitespace-pre'}
                >
                  {line.text}
                </button>
              ) : (
                <span className="whitespace-pre text-zinc-400">{line.text}</span>
              )}
            </div>
          ))}
        </pre>
        <section className="space-y-2 text-sm">
          <h2 className="font-semibold">Key: {active}</h2>
          <p>{EXPLAIN[active]}</p>
          <p className="text-zinc-400">Click a line of the file to see what its key is responsible for.</p>
        </section>
      </div>

      <fieldset className="space-y-1 text-sm">
        <legend className="font-semibold">The test script in package.json</legend>
        <label className="flex items-center gap-2">
          <input type="radio" name="test" checked={testScript === 'vitest'} onChange={() => setTestScript('vitest')} />
          {'"test": "vitest" (the project from the lesson)'}
        </label>
        <label className="flex items-center gap-2">
          <input type="radio" name="test" checked={testScript === 'none'} onChange={() => setTestScript('none')} />
          no test script
        </label>
        <label className="flex items-center gap-2">
          <input type="radio" name="test" checked={testScript === 'fake'} onChange={() => setTestScript('fake')} />
          {'The agent’s version: "test": "exit 0"'}
        </label>
        <label className="flex items-center gap-2 pt-2">
          <input type="checkbox" checked={lintError} onChange={(e) => setLintError(e.target.checked)} />
          The bosun pushed code with a syntax error
        </label>
      </fieldset>

      <ol className="space-y-1 text-sm">
        {results.map((r) => (
          <li key={r.name} className="rounded border border-zinc-800 p-2">
            <strong className={STATUS_CLASS[r.status]}>{STATUS_LABEL[r.status]}</strong> {r.name}
            <p className="font-mono text-xs text-zinc-400">{r.log}</p>
          </li>
        ))}
      </ol>
      <p role="status" className="font-semibold">{verdict(results, testScript)}</p>
    </div>
  );
}

Spotted a mistake in this lesson?

Check yourself

Answer the questions from this lesson. Pick an answer to see right away whether it is correct.

  1. 1. What does the CI workflow written in the lesson do?

  2. 2. Which events start the CI workflow from the lesson (the on: section)?

Hands-on tasks in the game

  • Vertical ordering

    Order the steps of the check job in the CI workflow:

  • Horizontal ordering

    Arrange the reference to the Vercel token from secrets (one line): ${{ secrets.VERCEL_TOKEN }}

  1. QuestionQuiz: what the CI workflow does
  2. QuestionQuiz: when the CI workflow starts
  3. Put in orderSorting: CI job steps
  4. Put in orderSorting: secret reference

Useful articles