Change zof.yaml safely

Change your services, tiers, tags or owners in zof.yaml without getting stuck behind your own gate. It takes about 3 minutes to read; do it before you merge a pull request that edits zof.yaml.

Once Zof / Control is required, Zof guards every merge, including changes to its own settings.

Why a pull request can't change its own rules

Zof reads zof.yaml from your default branch only, never from the pull request. Otherwise a pull request could lower its own service's tier, or drop a tag like payments, and then pass with less evidence.

The side effect: a pull request that adds a service, or changes a tier, is judged by the old settings. A new service has no tier yet, so it counts as unknown, and Zof treats unknown as the strictest tier. The pull request stays blocked until it has the strictest evidence.

Merge a zof.yaml change today

1. Tighten freely. Raising a service's criticality (a lower tier number) or adding a tag to a service that already has tags makes Zof stricter, so a pull request that does only that merges like any other once it meets the current rules. Adding an owner isn't only stricter: the owner gains approval and take-over authority.
2. Adding a service, or loosening anything, is judged by the old settings. A new service counts as unknown, so the pull request needs the strictest evidence. Open the pull request, then open its Zof / Control check. Its "To unblock" section lists what's missing.
3. If it can't meet that evidence but must merge now: use a short, deliberate bypass. See Bypass Zof in an emergency.

Set it in the console instead

You can also set tiers, owners, domains and tags in the Zof console, with no pull request. See Set up your system map. Every key is described in System map fields.

A stored copy wins over the repository's own zof.yaml. Once an admin accepts a map in the console, the System Graph ignores the file in the repository, so a pull request that edits it changes nothing. To make the file apply again, an admin uses Stop using the stored copy.

Check that it worked

After the pull request merges, open a new pull request that touches the service. Its Zof / Control check is judged by the new settings: its "To unblock" list no longer asks for the strictest tier's evidence.

How Zof will handle zof.yaml changes

• Zof will judge a pull request by the stricter of the old and new settings. A pull request will be able to make its own release stricter, never looser.
• A change that only tightens the settings will merge like any other change.
• Loosening will need an org admin. Lowering a tier, removing a tag, removing an owner or removing a sandbox restriction will add a requirement: approval by an active admin of your GitHub organization. The check will name what is being loosened, for example "lowers payments-api from tier 0 to tier 1". Its reason code will be config_change_needs_admin.
• A new service will get its tier approved by an org admin in the same pull request, so it won't need the strictest evidence.
• Your company will be able to require that the approving admin isn't the pull request's author (an optional two-person rule).
• Zof will record who approved, which commit, and the old and new values.

Once this ships, a zof.yaml change won't need a bypass just because it adds a service or changes a tier.