Skip to content

opgeth-decoupling: CI ratchet — required upstream type-check against a shrinking allowlist #21748

Closed

Description

@sebastianst

Part of #20257.

Goal

Make decoupling progress measurable and regression-proof: a required CI check that rehearses the #20266 cutover on every PR, so that no new op-geth-only API use lands unnoticed and the final flip becomes a formality.

Design

  • just opgeth-ratchet type-checks the whole tree, tests included, against the upstream go-ethereum version op-geth is based on. It decodes that version from op-geth's own version, so v1.101702.x checks against v1.17.2. It uses a temporary go.mod; the repo's go.mod and go.sum are untouched. It uses go/types through go/packages, which type-checks every package from source and continues past errors, so each package reports only its own uses. go build/go vet stop at the first failing layer, which makes a failing-package set useless as a ratchet.
  • Uses are compared against a committed allowlist, ops/scripts/opgeth-ratchet/allowlist.txt. Each entry is keyed by package (with a (tests) suffix for test files) and the fork API it needs, and carries a reason.
    • A use not on the allowlist fails the check. A PR that needs one adds the entry with a reason, so introducing an op-geth dependency is a deliberate, reviewed decision. The allowlist header points to the decoupling doc for ways to avoid the dependency.
    • An entry no longer used also fails. just opgeth-ratchet-update removes it and never adds entries, so the list only shrinks unless someone adds to it on purpose.
  • It is a required check: the opgeth-ratchet job in the main workflow, gated by ci-gate. It runs on every non-docs PR.
  • op-core differential tests and upstream backports are ordinary allowlist entries. Upstream backports are newer go-ethereum features op-geth carries ahead of its base; they have their own reason and go away when op-geth's base moves.
  • Cutover (opgeth-decoupling: final cutover (flip go.mod to upstream go-ethereum) #20266) is ready when the allowlist is empty; the flip PR deletes the tool, the allowlist and the job.

This replaces the first design, a scheduled build compared against a baseline of failing packages. A scheduled job only reports regressions after they merge. Auditing the seeded allowlist found production code that had taken up op-geth APIs after their op-core replacements existed (fixed in #23409), so the check gates PRs instead.

Acceptance criteria

  • The required check passes on the seeded allowlist. A new fork-API use fails it, and so does a stale entry.
  • The local command and the allowlist workflow are documented in the decoupling doc (§19), in AGENTS.md and in docs/ai/go-dev.md.

Implemented in #23407.

🤖 Co-created with Claude Opus 5.5

Activity

  1. changed the title [-]opgeth-decoupling: CI ratchet — scheduled upstream-geth build with a tightening baseline[/-] [+]opgeth-decoupling: CI ratchet — required upstream type-check against a shrinking allowlist[/+] on Oct 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions