Agora

You're viewing the docs for Flags 0.x. The latest is 1.x (rc). Go to the 1.x (rc) docs

Operations

Approvals, permissions, audit, environments, scheduled changes, gradual rollouts and stale-flag cleanup.

Permissions

Decide who may change flags with authorize. Wire @adonis-agora/authz here:

config/flags.ts
authorize: async (actor, action, { environment }) => {
  const user = await User.find(actor.id)
  return user ? authz.for(user).can(`flags.${action}`, { environment }) : false
},

action is read, write or approve.

Approvals

approvals: { environments: ['production'] },

Changes to production become change requests. Someone else approves them — the requester cannot approve their own. The request is validated again against the current ruleset when approved.

Approvals need to know who is acting. Where approvals are on, an anonymous actor (the console with nobody signed in and no actor configured) is refused.

node ace flags:requests:list --env=production   # pending
node ace flags:requests:approve <id>
node ace flags:requests:reject <id> --note "not before Black Friday"

Audit

Every change is recorded with who made it, the value before and after, the change request that carried it and the ruleset version it produced. See it per flag in the console, or with node ace flags:audit:list --key=<flag>.

Environments

One store can hold several environments. Each process reads one (environment, default production).

node ace flags:set new_player on --env=staging
node ace flags:promote staging production --dry-run
node ace flags:promote staging production --force
node ace flags:export --env=production --out=flags.json
node ace flags:import flags.json --env=staging --force

Scheduled changes and gradual rollouts

import flags from '@adonis-agora/flags/services/main'

await flags.admin.scheduleRollout('new_player', [
  { at: new Date('2026-12-01T09:00:00Z'), percent: 10 },
  { at: new Date('2026-12-03T09:00:00Z'), percent: 50 },
  { at: new Date('2026-12-05T09:00:00Z'), percent: 100 },
], { id: 'alice' })

Or schedule enable/disable (the kill switch) for a date. The worker applies each step once.

node ace flags:schedules:create new_player --steps='[{"at":"2026-12-01T09:00:00Z","percent":10},{"at":"2026-12-03T09:00:00Z","percent":50}]'
node ace flags:schedules:create new_player --kind=disable --at=2026-12-24T00:00:00Z
node ace flags:schedules:list --flag=new_player

Cleaning up

node ace flags:stale   # unused for 30 days, past expiresAt, serving one value for 30 days, or undeclared
node ace flags:refs    # where each flag is used in the code

Evaluation counts are kept per flag and day (no per-request I/O) to know what is still used.

On this page

Partner

Your product as the official integration for Flags, right here.

Become a partner →