release-and-rollout

name	release-and-rollout
description	How a change in this repo actually reaches CI - the two tag series, cutting a v* source tag, publishing an orb version, and bumping consumer pins. Read this before or after merging any fix that needs to run in production CI.

Release and rollout

Merging a PR here deploys nothing. There are two independent release channels, and a change only reaches CI once both have been advanced and the consumer's orb pin bumped.

Two tag series - don't confuse them

Tag	Releases
vX.Y.Z	The source tree (github_utility/, scripts) that jobs clone at runtime
orb/X.Y.Z	Bookkeeping mirror of a published CircleCI orb version

The two version numbers are unrelated. Orb versions live in CircleCI, not in git - orb/* tags are only created after the fact by orb/publish-prod-repository-tag.sh and are not what CircleCI serves.

Why merging deploys nothing

orb/src/commands/setup-circleci-utils-and-github-token.yml clones this repo at a tag:

git clone --branch << parameters.circleci-utils-tag >> --depth 1 \
  https://github.com/ethereum-optimism/circleci-utils.git /tmp/circleci-utils

circleci-utils-tag has a default in that file, and that default is frozen into every published orb version. A consumer runs whatever tag its pinned orb version was published with, no matter what main says.

No orb command forwards circleci-utils-tag to the setup command, so consumers cannot pick up new source code by passing a parameter to the command they actually call.

The full chain

1. Merge the PR to main.
2. Cut a source tag at the merge commit: git tag vX.Y.Z <merge-sha> && git push origin vX.Y.Z.
3. Bump circleci-utils-tag's default to vX.Y.Z in orb/src/commands/setup-circleci-utils-and-github-token.yml and merge that.
4. Publish a new orb version - orb/publish-dev.sh, test, then orb/publish-prod.sh - and push the orb/X.Y.Z tag. See Development & Release Process.
5. Bump every consumer's orb pin. For the monorepo that's ethereum-optimism/circleci-utils@<version> in .circleci/continue/main.yml.

Nothing is live until step 5.

Steps 2 and 3 apply only to changes in the cloned source tree. A change to orb YAML alone needs steps 1, 4 and 5.

Who can publish

Publishing a production orb version requires GitHub org Owner; org Members can only publish dev: versions. If you're not an owner, ask in #eng-oncall - see Permissions & Access.

Checking what's actually published

The orb is private, so https://circleci.com/api/v2/orb/ethereum-optimism/circleci-utils returns 404. Use the CircleCI GraphQL API instead; reads need no token.

List published versions:

curl -s https://circleci.com/graphql-unstable \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ orb(name: \"ethereum-optimism/circleci-utils\") { isPrivate versions { version createdAt } } }"}'

Read a published version's full source - the only reliable way to see which circleci-utils-tag a version really shipped with:

curl -s https://circleci.com/graphql-unstable \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ orbVersion(orbVersionRef: \"ethereum-optimism/circleci-utils@1.0.30\") { source } }"}' \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["data"]["orbVersion"]["source"])' \
  | grep -A2 circleci-utils-tag

Escape hatch for an urgent rollout

A consumer can force a source tag without waiting on an orb publish, by running the setup command itself first with an explicit tag:

- utils/github-stale:
    pre-steps:
      - utils/setup-circleci-utils-and-github-token:
          circleci-utils-tag: vX.Y.Z

This works because the setup command clones only if /tmp/circleci-utils doesn't exist, so the later internal call is a no-op.

Use it as a temporary bridge only. Publishing an orb version is the right fix - an override has to be repeated in every consumer and leaves the stale default in place everywhere else.

Verify after rollout

Check a real job on the consumer, not just the config diff. The Setup circleci-utils step logs the tag it clones; if it's still the old one, the orb version you pinned still carries the old default - go back to step 4.

Checklist

• PR merged to main
• vX.Y.Z tag cut at the merge commit and pushed
• circleci-utils-tag default bumped to vX.Y.Z and merged
• New orb version published and orb/X.Y.Z tag pushed
• Published orb source confirmed to carry the new default (GraphQL orbVersion)
• Consumer pins bumped (monorepo: .circleci/continue/main.yml)
• Consumer job log shows the new tag being cloned