Publish and check from CI

This page is for developers who keep an instruction in a repository and want a pipeline to release it. The pipeline validates the file, writes it to the instruction's draft, runs the server's checks, and releases the next version. A person sets the gates once, so stable only takes versions that have stood on latest and passed.

In the CLI, "publish" and "release" are the same act: making the draft the next version, v1, v2 and so on.

Before you start

Plans On Pro, Team, and Enterprise

  • An agent credential. The pipeline signs in as a service, not as a person. An owner or admin of the organization creates it. See Get a service credential.
  • Agents may publish. By default an organization doesn't let agents release versions. An owner or admin turns on Settings ▸ Security ▸ Agents may publish. Without it, every release from the pipeline is refused.
  • The instruction exists and has a first version. A person creates it (in the editor, or with instruction push) and releases v1, because the first release has to say who can read it. See The first release.
  • Node.js 20.19 or later on the runner, and npm i -g instruction.md (0.11.0 or later).

Get a service credential

An owner or admin creates the credential once, from a terminal. Creating one needs the permission to administer the organization, which instruction login --admin asks for:

Shell
instruction login --admin
instruction agents create release-pipeline --org acme --kind service \
  --scopes read,write,publish --workspace-role maintainer
Output
agent agt_<id> (release-pipeline) in acme
client_id:     <client id>
client_secret: <client secret>   <- shown once; store it now (INSTRUCTION_MD_CLIENT_SECRET)
token_url:     <token url>
audience:      <audience>
scopes:        instructions:publish instructions:read instructions:write

next: instruction connect --host agentd --agent <client id> --org acme <uri>
  • --scopes read,write,publish lets it read, change drafts and release. Without --scopes it may only read.
  • --workspace-role maintainer gives it the Maintainer role in the organization's default workspace: enough to edit the draft, run the checks and release. An agent works only where it is given a role. For an instruction in another workspace, give it a role there too, as Agent credentials and CI tokens says.
  • The secret is shown once. Store it in your CI's secrets as INSTRUCTION_MD_CLIENT_SECRET, and the client id and token URL as plain variables (INSTRUCTION_MD_CLIENT_ID, INSTRUCTION_MD_TOKEN_URL).

The number of agent credentials an organization keeps depends on its plan:

Plans Pro 10 · Team 100 · Enterprise unlimited

Rotating and revoking a credential are on Agent credentials and CI tokens.

Mint a token in the job

The CLI doesn't exchange a client secret itself: it sends the token in INSTRUCTION_MD_TOKEN as it is. Each job asks the token URL for one with the client-credentials grant. A token lives five minutes, so mint it in the job that uses it.

Shell
TOKEN=$(curl -s -X POST "$INSTRUCTION_MD_TOKEN_URL" \
  -d grant_type=client_credentials -d client_id="$INSTRUCTION_MD_CLIENT_ID" \
  -d client_secret="$INSTRUCTION_MD_CLIENT_SECRET" \
  | node -p 'JSON.parse(require("fs").readFileSync(0, "utf8")).access_token')
export INSTRUCTION_MD_TOKEN="$TOKEN"
instruction whoami

instruction whoami says who the server sees: the agent, in your organization.

Release from the pipeline

  1. Validate the file

    instruction validate checks the file offline, with the reader a release uses. Errors fail the job with exit code 1. Warnings are shown and pass; --strict fails on them too.

    Shell
    instruction validate support-agent.md
    Output
    ok       support-agent.md

    A file the reader refuses names each problem with its line and code:

    Output
    INVALID  support-agent.md
             line 14: <what the reader refuses>  [<code>]
  2. Run the eval cases (optional)

    instruction eval runs the instruction's own eval cases against Claude, with your Anthropic API key. It exits 1 when a case fails. A file with no eval cases passes. Each run calls a model and costs what the model costs, so many teams run it on pull requests only. --dry-run prints what each case would send and calls no model.

    Shell
    export ANTHROPIC_API_KEY="<your key>"
    instruction eval support-agent.md
    Output
    PASS refunds/asks-for-the-order-date
    PASS refunds/never-promises-a-date
    2 passed, 0 failed

    How to write eval cases is on Checks, evals and tests.

  3. Sign in as the pipeline

    Mint the token as in Mint a token in the job, and export it as INSTRUCTION_MD_TOKEN. Every instruction command after this uses it.

  4. Write the file to the draft

    The file becomes the draft's text, as a direct edit. This script uses the client in the instruction.md package, installed beside it:

    .github/scripts/write-draft.mjs
    // node write-draft.mjs <file> <owner/name>: the file becomes the instruction's draft.
    // Needs instruction.md installed beside it (npm i --no-save instruction.md) and INSTRUCTION_MD_TOKEN.
    import { readFileSync } from "node:fs";
    import { createClient, ToolError } from "instruction.md/client";
    
    const [file, instructionId] = process.argv.slice(2);
    const client = createClient({
      url: process.env.INSTRUCTION_MD_URL ?? "https://instruction.md/mcp",
      token: () => process.env.INSTRUCTION_MD_TOKEN,
      clientInfo: { name: "release-pipeline", version: "1" },
    });
    
    try {
      const ins = await client.call("instructions_get", { instructionId });
      if (!ins.draft) throw new Error(`${instructionId}: this credential can't read its draft`);
      const r = await client.call("instructions_draft_replace", {
        instructionId: ins.id,
        expectedRevision: ins.draft.revision,
        content: readFileSync(file, "utf8"),
        asSuggestion: false, // an agent's edit is a suggestion unless it says otherwise
      });
      console.log(r.changed ? `draft: revision ${r.revision}` : `draft: unchanged (revision ${r.revision})`);
    } catch (e) {
      if (e instanceof ToolError) { console.error(`${e.tool}: ${e.code}: ${e.message}`); process.exit(1); }
      throw e;
    }
    Shell
    npm i --no-save instruction.md
    node .github/scripts/write-draft.mjs support-agent.md acme/support-agent
    Output
    draft: revision 42

    The text the draft had is kept as a checkpoint first, so the instruction's history can put it back. Edits made in the editor since the last run are replaced by the file. If someone edits the draft between the script's read and its write, the server answers version_conflict and the job fails: run it again once you have looked at what changed.

  5. Run the server's checks

    instruction checks runs the checks a release gate asks for on the draft: validate and lint (credentials the reader doesn't know, invisible characters, text that tells a model to set aside its instructions). It exits 1 when one fails. Warnings are printed and pass.

    Shell
    instruction checks acme/support-agent
    Output
    the draft (revision 42): the checks pass
      validate  passed — valid
      lint      passed — passed, 1 warning
        line 12    warning  override-attempt     this mentions setting aside the model's instructions; make sure it reads as a rule against it

    The result is kept for that exact text, so the version released from it carries it. Every release runs the checks again anyway.

  6. Release the next version

    Shell
    instruction publish acme/support-agent --message "$GITHUB_SHA" --yes
    Output
    published acme/support-agent v9 (ver_<id>) → latest
    instruction://ins_<id>

    Moving latest switches the agents that follow it, so the server asks first. --yes agrees to it; without --yes and without a terminal, nothing changes and the command exits 7. --json prints the version as JSON for the next step of your pipeline.

    The server signs the version with the organization's platform key. --sign-with is refused with exit code 2: a release can't be signed with your own key here. See Signing and verification.

The first release

The first version of an instruction must say who can read it, so instruction publish without --visibility refuses it with exit code 2. A person usually makes it once:

Shell
instruction publish acme/support-agent --visibility internal --yes

--visibility takes private (only you), internal (your organization) or public (anyone, signed in or not).

Release to another ref

--refs names the refs a release moves instead of latest. --quiet moves none: a quiet version. Releasing to a ref other than the default ref asks nothing, so --yes isn't needed:

Shell
instruction publish acme/support-agent --refs canary --message "$GITHUB_SHA"

Gate stable

A ref's gates decide what it may move to. A person with the Admin role on the instruction sets them once, from a terminal or the editor. The pipeline never changes them.

Shell
instruction refs acme/support-agent set stable v8
instruction refs acme/support-agent gate stable --require-checks --promote-from latest --after 1440
Output
stable → v8 (ver_<id>)
stable: checks must pass, follows latest after 1440 min
Flag of instruction refs <id> gate REFGateWhat it does
--require-checksrequireChecksThe ref moves only to a version whose checks passed
--require-signaturerequireSignatureThe ref moves only to signed versions
--promote-from Rpromote.fromThe ref follows R: a newer version of R is taken once R has pointed at it long enough. With --require-checks, only if its checks passed. Only a person sets it
--after MINpromote.afterMinutesHow long it must stand on R first, in whole minutes, at most 43,200 (30 days). Default 60
  • gate sets all of a ref's gates at once. A gate you don't name is turned off.
  • The ref must exist: make it with instruction refs <id> set REF <version> first. @stable is never made for you.
  • Only a person sets a promotion. It runs later as that person, who must still be allowed to move the ref; the move is theirs in the audit trail.
  • The wait counts from the last time R moved. If R moves to a newer version before the wait ends, the wait starts again for that version, and the one it skipped is never taken.
  • The server looks for due promotions every 30 seconds. It tries each version once. A version whose checks failed isn't tried again: fix the text and release a new one. A revoked version is never taken.
  • A gate governs where the ref moves next. Setting one leaves the version it points at now where it is.

With the gate above, every release from the pipeline goes to latest, and stable takes it 1,440 minutes (a day) later if its checks pass. Agents that must not get a version early follow @stable.

Shell
instruction refs acme/support-agent
Output
latest       → v9    ver_<id>  2026-11-22 10:14
stable       → v8    ver_<id>  2026-11-21 09:02  checks must pass, follows latest after 1440 min

To keep latest for people and release to a canary ref from the pipeline instead, gate canary and let stable follow it. The pipeline then publishes with --refs canary:

Shell
instruction refs acme/support-agent set canary v8
instruction refs acme/support-agent gate canary --require-checks
instruction refs acme/support-agent gate stable --require-checks --promote-from canary --after 60

The plain-words version of refs and gates is on A stable version.

Revoke a bad version

Revoking needs the Admin role on the instruction, which an agent credential can't have, so a person does it. First move every ref off the version, then revoke it:

Shell
instruction login
instruction refs acme/support-agent set latest v8 --yes
instruction revoke acme/support-agent v9 --reason "refund rule was wrong" --yes
Output
latest → v8 (ver_<id>)
revoked v9 (ver_<id>): refund rule was wrong — it stays readable, marked revoked; refs can't return to it, followers hold their last good version

A revoked version stays readable for the audit, marked revoked. No ref can move back to it, and agents pinned to it keep their last good version and are told it was revoked. Revoking while a ref still points at the version is refused with move <refs> off v<N> first.

GitHub Actions

The whole pipeline, with the script from Write the file to the draft at .github/scripts/write-draft.mjs. Pull requests validate and evaluate; a push to main releases. Put the client secret and your Anthropic key in the repository's secrets, and the token URL and client id in its variables.

.github/workflows/instruction.yml
name: instruction
on:
  push:
    branches: [main]
    paths: [support-agent.md]
  pull_request:
    paths: [support-agent.md]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm i -g instruction.md
      - run: instruction validate support-agent.md
      - run: instruction eval support-agent.md
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

  release:
    if: github.event_name == 'push'
    needs: check
    runs-on: ubuntu-latest
    concurrency: instruction-release
    env:
      INSTRUCTION_MD_TOKEN_URL: ${{ vars.INSTRUCTION_MD_TOKEN_URL }}
      INSTRUCTION_MD_CLIENT_ID: ${{ vars.INSTRUCTION_MD_CLIENT_ID }}
      INSTRUCTION_MD_CLIENT_SECRET: ${{ secrets.INSTRUCTION_MD_CLIENT_SECRET }}
      INSTRUCTION_MD_LABEL: github-actions/${{ github.repository }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm i -g instruction.md && npm i --no-save instruction.md
      - name: Sign in as the pipeline
        run: |
          TOKEN=$(curl -s -X POST "$INSTRUCTION_MD_TOKEN_URL" \
            -d grant_type=client_credentials -d client_id="$INSTRUCTION_MD_CLIENT_ID" \
            -d client_secret="$INSTRUCTION_MD_CLIENT_SECRET" \
            | node -p 'JSON.parse(require("fs").readFileSync(0, "utf8")).access_token')
          echo "::add-mask::$TOKEN"
          echo "INSTRUCTION_MD_TOKEN=$TOKEN" >> "$GITHUB_ENV"
      - run: node .github/scripts/write-draft.mjs support-agent.md acme/support-agent
      - run: instruction checks acme/support-agent
      - run: instruction publish acme/support-agent --message "$GITHUB_SHA" --yes --json
  • paths runs it only when the file changes. A release of a text that equals the latest version is refused with nothing changed since the latest version, so a run without a change would fail.
  • concurrency keeps two releases from racing for the same draft.
  • ::add-mask:: keeps the token out of the log.
  • INSTRUCTION_MD_LABEL names the pipeline among the instruction's readers.
  • The check job runs on pull requests too, where the secrets of a fork's pull request aren't given: instruction eval then fails without ANTHROPIC_API_KEY. Leave the eval step out, or use --dry-run, if you take pull requests from forks.

GitLab CI

The same pipeline in GitLab. Set INSTRUCTION_MD_TOKEN_URL, INSTRUCTION_MD_CLIENT_ID, INSTRUCTION_MD_CLIENT_SECRET (masked) and ANTHROPIC_API_KEY (masked) as CI/CD variables, and keep the script from Write the file to the draft at scripts/write-draft.mjs.

.gitlab-ci.yml
stages: [check, release]

default:
  image: node:22
  before_script:
    - npm i -g instruction.md

check:
  stage: check
  rules:
    - changes: [support-agent.md]
  script:
    - instruction validate support-agent.md
    - instruction eval support-agent.md   # ANTHROPIC_API_KEY from the CI/CD variables

release:
  stage: release
  resource_group: instruction-release
  variables:
    INSTRUCTION_MD_LABEL: gitlab-ci/$CI_PROJECT_PATH
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      changes: [support-agent.md]
  script:
    - npm i --no-save instruction.md
    - >
      export INSTRUCTION_MD_TOKEN=$(curl -s -X POST "$INSTRUCTION_MD_TOKEN_URL"
      -d grant_type=client_credentials -d client_id="$INSTRUCTION_MD_CLIENT_ID"
      -d client_secret="$INSTRUCTION_MD_CLIENT_SECRET"
      | node -p 'JSON.parse(require("fs").readFileSync(0, "utf8")).access_token')
    - node scripts/write-draft.mjs support-agent.md acme/support-agent
    - instruction checks acme/support-agent
    - instruction publish acme/support-agent --message "$CI_COMMIT_SHA" --yes --json

AI-assisted CI

instruction.md's MCP server offers the skill release-gates-in-ci at skill://instruction-md/release-gates-in-ci/SKILL.md. An agent that runs your pipeline, or a person's assistant setting up the gates, loads it first. It covers the same steps through the MCP tools (spec_validate, instructions_draft_replace, instructions_checks_run, instructions_publish, instructions_refs_set), what to do with each error, and why stable didn't move. See Prompts and skills.

Check it worked

  • instruction versions acme/support-agent lists the new version at the top, with signed and the commit in its message.
  • instruction refs acme/support-agent shows latest on it, and stable where it was until its promotion is due.
  • The instruction's activity in the editor shows the release, made by the agent credential's name.

If it doesn't work

What you seeWhyWhat to do
this organization doesn't let agents release versions (policy agentPublish)Agents may publish is offAn owner or admin turns on Settings ▸ Security ▸ Agents may publish, or a person releases
instructions_publish: conflict: nothing changed since the latest versionThe draft equals the latest version: the file didn't change, or the draft was written as suggestionsRun the job only when the file changes; write the draft with asSuggestion: false, not push --to
instructions_publish: this asks first; nothing changed (run again with --yes to go ahead), exit 7Moving latest asks first, and a job has no terminalAdd --yes
Who can read the first version of …, exit 2The instruction has no version yetRelease v1 once with --visibility
version_conflict from the scriptSomeone edited the draft during the runLook at their change, then run the job again. Never retry over someone's edits automatically
forbidden with requireChecksThe ref takes checked versions only, and the checks failed or weren't run on that textFix what instruction checks reports
limit_reachedA plan limit, such as versions a monthTell an owner or admin. See Rate and size limits
Exit 3, this registry needs a signed-in callerNo token, or it expired (five minutes)Mint the token in the same job, just before the commands
Still stuckAsk us, with the command, its output and the job's log

Every error code and its fields are on Errors.

Questions

How do I get a non-interactive token for CI?

Create an agent credential with instruction agents create … --kind service, store its secret in your CI, and mint a token in each job with the client-credentials grant at its token URL. Pass the token as INSTRUCTION_MD_TOKEN. See Get a service credential and Agent credentials and CI tokens.

How do I make stable follow latest automatically once checks pass?

Make the stable ref once, then run instruction refs <id> gate stable --require-checks --promote-from latest --after <minutes> as a person with the Admin role. The server moves stable to each newer version of latest once it has stood there that long and its checks pass. See Gate stable.

Can the pipeline set the gates or revoke a version itself?

No. Gates and revoking need the Admin role on the instruction, and an agent credential can be a Maintainer at most. A promotion also runs as the person who set it, so only a person can set one.

Why did my pipeline's change show up as suggestions?

An agent's edit is a suggestion unless the call says it isn't, and instruction push --to doesn't say so. Write the draft with instructions_draft_replace and asSuggestion: false, as the script on this page does.

Last checked against the product:

Was this page helpful? Report a problem