Release safety
Flag changes can't skip review.Not even with an admin key.
NanoFlags treats a flag change like a code change: a draft, a reason, tests that must pass and a reviewer who isn't the author. The rules are enforced by the database, so no client, script or key can route around them.
Draft
Edit flags in an environment's draft. SDKs don't see it.
draft
Test
Run scenario checks on that exact draft.
testing
Review
Request approval from someone who didn't edit it.
awaiting_approval
Approve
The approval is bound to the draft's checksum.
approved
Publish
A new signed, numbered revision. The record stays.
published
Drafts and revisions
Nothing reaches an SDK until you publish.
Editing a flag changes the environment's draft. Publishing snapshots the whole draft, every flag and segment, into an immutable, numbered revision with a checksum. SDKs only ever receive published revisions.
Expected revision
DESTINATION_CHANGEDEvery publish names the revision it expects to replace. If someone published in the meantime, yours is refused instead of overwriting theirs.
No empty publishes
NO_CHANGESA draft identical to the published configuration can't be published.
Typed values
INVALID_VALUEValues that don't match the flag's type, or its JSON schema, are refused by the database.
Change requests and approvals
Independent means independent.
A change request groups the flags you mean to change in one environment, with a title, a reason and an optional code reference. Where approval is required, publishing is only possible through a change with enough valid approvals.
- The author can't approveSELF_APPROVAL
- Neither can anyone who saved an edit to that environment's draft since the change began. Approvers must be admins or owners.
- Approvals are bound to the draftdraft checksum
- An approval records the checksum of the draft it reviewed. Edit the draft afterwards and the approval goes stale: it stops counting and the change needs a fresh one.
- 1 to 5 required approversper environment
- Each environment sets how many valid approvals a publish needs. A rejection sends the change back to draft.
- Keys can't bypass reviewCHANGE_REQUIRED · APPROVAL_REQUIRED
- An admin API key can't publish an environment that requires approval. The CLI and scripts follow the same rules as people.
- draft
- testing
- awaiting_approval
- approved
- published
author maya
draft c27d80 (edited after approval)
reason Error rate flat for 48 h at 25%. Next step of the rollout plan.
Scenario checks
runs were on 9f3c1a · run again on c27d80
Approvals · 1 required
- mayaauthor · cannot approve
- samedited this draft · cannot approve
- leeapproved 9f3c1a · stale, draft changed
Scenario checks
Tests that gate the publish button.
A scenario is a flag, a context and the value you expect, such as “a signed-in user in the EU gets true”. Where scenario checks are required, every scenario in scope must have passed on the exact draft being published.
- Exact draft, exact resultsame checksum
- A run counts only for the draft checksum it ran against. Edit the draft and you run them again. Pass means deep-equal, with no type coercion.
- Independent evidenceCI key or another person
- A run gates a change only when it came from a CI or admin key, or from someone other than the author and the draft's editors.
- Versioned scenariosscenario versions
- Every edit to a scenario keeps the previous definition. Only runs of the current definition count.
- In CI and in pull requestsGitHub Action · GitHub App
- The CLI runs scenarios for a commit; the GitHub App adds a “NanoFlags scenarios” check run to pull requests.
Try the gate
EU signed-in users get the new checkout
{ region: "EU", signedIn: true, key: "u_18" }
expected trueactual true
Signed-out visitors keep the old checkout
{ region: "EU", signedIn: false }
expected falseactual false
Internal staff always see it
{ staff: true, region: "US" }
expected trueactual true
US customers stay out of the rollout
{ region: "US", signedIn: true }
expected falseactual truematched Rule 02 (region in [EU, US])
Switch between the two drafts. Publishing unlocks only when every scenario passes on the draft in front of you.
Protected environments and promotion
Production has a policy. Changing it has one too.
Admins decide per environment whether it is protected, whether it requires approval and how many approvers, and whether it requires scenario checks. New projects start with Production protected.
Relaxing needs the owner
OWNER_REQUIREDRemoving protection or loosening a protected environment's policy needs the organization owner. Admins can only tighten it.
Promotion with a record
Staging → ProductionPromote copies selected flag configurations from one environment's draft into another's. It never publishes. The record keeps the source revision, whether the source draft matched it, and the target's revision and checksums before and after.
Linked to the publish
published_revisionThe target's next publish is linked to the promotion, so you can trace a Production revision back to the Staging revision it came from.
Restore
Go back without rewriting history.
Restore loads an earlier revision's flag configurations, and the segments it used, into the draft. You publish it as a new revision through the same checks as any other change. Nothing is deleted.
- Flags added since that revision are reported, so you can decide what to do with them.
- Restore needs an editor; publishing it follows the environment's policy.
- Every revision stays readable for the life of the project.
- r185current
Raise checkout-v2 to 50% in EU
lee · 12:06
- r184Restore to draft
checkout-v2 to 25% in EU
lee · 10 Nov 09:12
- r183Restore to draft
Enable new-pricing-page for internal staff
omar · 9 Nov 16:40
audit log
12:06:14leepublished r185 · production
12:04:51leeapproved change · draft 9f3c1a
12:01:09ciscenarios 4/4 passed · commit 3e1f2a0
11:58:32mayaedited draft · checkout-v2
Audit log
Written by the database, not by the client.
Draft edits, approvals, publishes, key changes, policy changes and member changes are recorded by database triggers and server-side functions. The audit log is read-only through the API.
- 12:06:14leepublishedr185 · production
- 12:04:51leeapprovedchange · draft 9f3c1a
- 12:01:09ciscenarios4/4 passed · commit 3e1f2a0
- 11:58:32mayaediteddraft · checkout-v2
- Entries name the actor, the object and a summary, with the details as structured data.
- Rows outlive their project: deleting a project keeps its audit history.
- Audit export is available on Scale.
Release evidence
Published, reported or unknown. Never assumed.
A change page shows what was tested, who approved it, which revision it became, and what your services report running. NanoFlags keeps these states visibly distinct and never calls a release “safe”.
Published
The revision the edge serves for the environment.
Reported
A process using a key of this environment said it had revision N loaded. A report covers that process, not every instance.
Unknown
No report arrived. Telemetry may be off, blocked or sampled out. NanoFlags shows the gap instead of assuming a match.
Change opened by maya
draft 9f3c1a · base r184
4 of 4 scenarios passed
CI key · commit 3e1f2a0
Approved by lee
not the author, not a draft editor · bound to 9f3c1a
Promoted from staging r212
promotion record linked
Published r185 · signed
reported by 3 of 4 services · 1 unknown
Which plan includes what
Required approvals, scenario checks, CI run results and webhooks are on Team and Scale. Shared test sessions and audit export are on Scale. Drafts, revisions, restore and the audit log are on every plan. Publishing is never blocked by a plan: existing data stays readable.
Put a second pair of eyes on Production.
Start on Explore for free. Turn on required approvals and scenario checks when you move to Team.