Keep agents on a stable version

This page is for anyone who publishes an instruction that agents depend on, and explains how to keep agents on a version you trust while you go on publishing.

Every time you publish, the live version moves to the new one, and the agents that follow it switch. A second name, stable, moves only when you say so, or when a rule you set says so. Agents you point at stable stay where they are while you keep working.

latest moves on every publish; stable follows only after the wait, and only to versions whose checks pass.

Live moves on every publish; stable moves when you say

An instruction's versions are numbered: v1, v2, v3 and so on. A ref is a name that points at one of those versions. Agents follow a ref, and they get the version it points at.

  • latest is the ref every instruction has. History marks the version it points at Live, and it is what "the live version" means everywhere in the editor. When you publish, latest moves to the new version, and every agent that follows it gets the new version the next time it looks.
  • stable is a ref you create yourself. Nobody makes it for you. Publishing never moves it. It moves only when you move it, or when its publish gate moves it for you (see Publish gates).

You can also use other names. The editor suggests canary (a version a few agents try first) next to stable. In History, every ref that points at a version shows as a small tag on that version, with the tip "Agents that follow stable get this version".

Create stable

stable doesn't exist until you create it. You need the Admin role on the instruction, and the instruction needs at least one published version.

Open the instruction. Click Search in the side bar, or press Ctrl+K (⌘K on a Mac). Type "gates", and pick Publish gates…. The dialog Publish gates of "…" opens. It lists the refs the instruction has, each with the version it points at.

Click Add stable at v…. The button names the live version, for example Add stable at v4. A message says "stable points at v4", and stable appears in the list.

Leave it as it is, and stable stays on v4 until you change it. Or set its gates in the same row, as Publish gates explains. A gate is saved as soon as you change it.

Publish gates…: what each ref takes, and what following did lately.

The add button always uses the live version. To start stable on an older version, add it, then make that older version stable from a connected AI app (ask it to "point stable at v3"), or ask a developer on your team.

If the dialog says "Publish a version first: refs point at versions.", publish once, then come back.

Pin to one version

You don't need a ref to keep an agent still. You can pin it: tell it to follow one exact version, such as v4. A pinned agent stays on v4 until you choose another version for it. It ignores every publish and every move of latest or stable.

You choose this when you connect an agent. In Share ▸ Follow in your coding agent…, the list 2. The version to follow offers each ref, such as stable (now v4), and Only v4. The note under it says what you picked: "Your agent moves to each new version this name points to." for a ref, and "Your agent stays on this version until you choose another." for a pin.

Pin an agent when nothing may change under it, for example during an audit. Follow stable when you want it to move, but only to versions you trust.

Publish gates

A gate is a rule a ref checks before it moves to a version. Each ref in Publish gates… has three. They apply to stable, to latest or to any other ref you add.

  • Checks must pass: the ref moves only to a version whose checks passed. The checks look for problems in the text that would stop it from being read correctly. They also look for passwords or keys, invisible characters, and text that tells a model to ignore its instructions. instruction.md runs them on every version you publish. History marks a version that failed with Checks failed.
  • Signed only: the ref moves only to a version that carries its publisher's signature. A signature says who published a version, and agents can check it. An organization admin can turn this on for every instruction at once: Developer ▸ Signing ▸ Only signed versions on refs.
  • Follows … after … min: the ref follows another ref, after a wait. For example, stable Follows latest after 1440 min. A new version must stay live for 24 hours before stable moves to it.

How following works

When you tick Follows, pick the ref to follow and how many minutes to wait. The wait is 60 minutes unless you change it, and it can be up to 43,200 minutes (30 days).

  • The wait starts when the followed ref moves. If you publish v5 and then v6 an hour later, the clock starts again for v6, and v5 is never taken.
  • When the wait is over, the version's checks must pass too. A version whose checks failed stays off, even if you didn't tick Checks must pass.
  • The ref only moves forward, to a newer version. If you roll the live version back, stable stays where it is.
  • Each version is tried once. If it is refused, it isn't tried again. Publish a new version, or move the ref yourself.
  • The move is made as the person who last changed that ref's gates. If they lose the right to publish this instruction, the moves stop.
  • instruction.md looks for versions that are due about every 30 seconds. The maintainers get a notification each time a ref moves or is refused.

The promotions log

Under the list, Promotions, the last 30 days shows what following did. Each line names the ref, the version and where it came from:

Line What it means
stable ← v5 from latest: moved stable points at v5 now.
stable ← v5 from latest: on its way The wait is over, and the move is being made.
stable ← v5 from latest: stayed off: its checks failed v5's checks failed, so stable kept its version.
stable ← v5 from latest: didn't move: … Something else stopped it. The reason follows the colon, for example that v5 isn't signed.

Check the draft before you publish

The dialog's last part, The draft's checks, runs the same checks on your draft now. Click Run the checks. "They pass: a version published from this draft carries that." means a ref that requires checks will take it. If they fail, each problem has a Show button that takes you to its line. Fix them, then publish.

Gates on latest

A gate on latest guards every publish. If latest has Checks must pass and the draft's checks fail, Publish is refused and says why. Nothing is published. Use this when no version should go live without passing its checks.

What an agent sees before stable exists

An agent can only follow a ref that exists. instruction.md never gives it the live version instead.

  • In Share ▸ Follow in your coding agent… and Share ▸ Deploy to…, stable isn't in the version list until you create it.
  • A rule that runs every instruction of a project (Run every instruction on…) offers The version named stable under How the agents act ▸ Version to follow even before stable exists. Its preview, What it would start now, shows "no version named stable" next to each instruction that has no stable yet.
  • An AI app or agent asked to follow stable before it exists is told it wasn't found, and gets no instruction.
  • If you delete a ref, the agents that followed it keep the last version they had.

Create stable first, then point agents at it.

Which one to give your AI apps

Give it When What happens on publish
The live version (latest) You test as you write, or a few people use it. It switches to every new version.
stable Many agents, or agents that act for customers. Nothing, until stable moves: by you, or by its Follows gate.
One version (a pin) Nothing may change, for example during an audit. Nothing, ever, until you choose another version.

A common setup: you and your reviewers follow latest, and everyone else follows stable. stable follows latest after a day, and checks must pass. A version reaches everyone only after it has been live for a day without problems.

Common misunderstandings

  • "Publishing updates stable." It doesn't. Only you, or stable's own Follows gate, move it.
  • "instruction.md makes stable for me." It doesn't. Create it in Publish gates….
  • "Rolling back live rolls back stable." It doesn't. Each ref moves on its own. See Roll back or withdraw a version.
  • "A gate moves the ref now." Changing a gate never moves the ref. It decides only where the ref may move next. Agents keep the version it points at now.

Questions

How do I create a 'stable' version for agents, and what happens if it doesn't exist?

Open Publish gates… and click Add stable at v…. It points at the live version. Until you do, an agent can't follow stable: it is told stable wasn't found, and instruction.md doesn't give it the live version instead. Create stable.

Can stable move by itself?

Only if you tell it to. Tick Follows on stable's row and set a wait, and stable moves to each new live version once it has stood for that long and its checks pass. How following works.

Who can change the gates?

Someone with the Admin role on the instruction. Maintainers publish versions and make them live, but they don't see Publish gates…. People and roles.

What is the difference between stable and pinning?

stable is a name that can move, so agents that follow it move with it. A pin is one exact version: the agent stays on it until you choose another. Pin to one version.

For developers: refs and gates in the model, and gating releases in CI.

Last checked against the product:

Was this page helpful? Report a problem