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:
instruction login --admin
instruction agents create release-pipeline --org acme --kind service \
--scopes read,write,publish --workspace-role maintainer 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,publishlets it read, change drafts and release. Without--scopesit may only read.--workspace-role maintainergives 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.
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
Validate the file
instruction validatechecks the file offline, with the reader a release uses. Errors fail the job with exit code 1. Warnings are shown and pass;--strictfails on them too.Shellinstruction validate support-agent.mdOutputok support-agent.mdA file the reader refuses names each problem with its line and code:
OutputINVALID support-agent.md line 14: <what the reader refuses> [<code>]Run the eval cases (optional)
instruction evalruns the instruction's ownevalcases 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-runprints what each case would send and calls no model.Shellexport ANTHROPIC_API_KEY="<your key>" instruction eval support-agent.mdOutputPASS refunds/asks-for-the-order-date PASS refunds/never-promises-a-date 2 passed, 0 failedHow to write eval cases is on Checks, evals and tests.
Sign in as the pipeline
Mint the token as in Mint a token in the job, and export it as
INSTRUCTION_MD_TOKEN. Everyinstructioncommand after this uses it.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.mdpackage, 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; }Shellnpm i --no-save instruction.md node .github/scripts/write-draft.mjs support-agent.md acme/support-agentOutputdraft: revision 42The 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_conflictand the job fails: run it again once you have looked at what changed.Run the server's checks
instruction checksruns the checks a release gate asks for on the draft:validateandlint(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.Shellinstruction checks acme/support-agentOutputthe 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 itThe result is kept for that exact text, so the version released from it carries it. Every release runs the checks again anyway.
Release the next version
Shellinstruction publish acme/support-agent --message "$GITHUB_SHA" --yesOutputpublished acme/support-agent v9 (ver_<id>) → latest instruction://ins_<id>Moving
latestswitches the agents that follow it, so the server asks first.--yesagrees to it; without--yesand without a terminal, nothing changes and the command exits 7.--jsonprints the version as JSON for the next step of your pipeline.The server signs the version with the organization's platform key.
--sign-withis 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:
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:
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.
instruction refs acme/support-agent set stable v8
instruction refs acme/support-agent gate stable --require-checks --promote-from latest --after 1440 stable → v8 (ver_<id>)
stable: checks must pass, follows latest after 1440 min Flag of instruction refs <id> gate REF | Gate | What it does |
|---|---|---|
--require-checks | requireChecks | The ref moves only to a version whose checks passed |
--require-signature | requireSignature | The ref moves only to signed versions |
--promote-from R | promote.from | The 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 MIN | promote.afterMinutes | How long it must stand on R first, in whole minutes, at most 43,200 (30 days). Default 60 |
gatesets 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.@stableis 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.
instruction refs acme/support-agent 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:
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:
instruction login
instruction refs acme/support-agent set latest v8 --yes
instruction revoke acme/support-agent v9 --reason "refund rule was wrong" --yes 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.
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 pathsruns it only when the file changes. A release of a text that equals the latest version is refused withnothing changed since the latest version, so a run without a change would fail.concurrencykeeps two releases from racing for the same draft.::add-mask::keeps the token out of the log.INSTRUCTION_MD_LABELnames the pipeline among the instruction's readers.- The
checkjob runs on pull requests too, where the secrets of a fork's pull request aren't given:instruction evalthen fails withoutANTHROPIC_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.
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-agentlists the new version at the top, withsignedand the commit in its message.instruction refs acme/support-agentshowslateston it, andstablewhere 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 see | Why | What to do |
|---|---|---|
this organization doesn't let agents release versions (policy agentPublish) | Agents may publish is off | An owner or admin turns on Settings ▸ Security ▸ Agents may publish, or a person releases |
instructions_publish: conflict: nothing changed since the latest version | The draft equals the latest version: the file didn't change, or the draft was written as suggestions | Run 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 7 | Moving latest asks first, and a job has no terminal | Add --yes |
Who can read the first version of …, exit 2 | The instruction has no version yet | Release v1 once with --visibility |
version_conflict from the script | Someone edited the draft during the run | Look at their change, then run the job again. Never retry over someone's edits automatically |
forbidden with requireChecks | The ref takes checked versions only, and the checks failed or weren't run on that text | Fix what instruction checks reports |
limit_reached | A plan limit, such as versions a month | Tell an owner or admin. See Rate and size limits |
Exit 3, this registry needs a signed-in caller | No token, or it expired (five minutes) | Mint the token in the same job, just before the commands |
| Still stuck | Ask 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.