ServiceAccount

A ServiceAccount is an identity that is not a person: the thing a CI pipeline, a scheduled job, or a piece of automation signs in as. You create it, scope it with ordinary RBAC, audit it, and revoke it.

apiVersion: core.ringleader.dev/v1
kind: ServiceAccount

The important part is what it does not hold: there is no password, no API key, no long-lived token stored anywhere. A service account holds a trust list — which external identities are allowed to become it. A GitHub Actions job proves who it is using the identity token GitHub already mints for it, Ringleader checks that proof against the trust list, and issues a short-lived token in return. Nothing to leak, nothing to rotate, nothing to paste into a secrets store.

Its subject is sa:<namespace>/<name> — always namespace-qualified, so two teams can both have a ci without them being the same identity anywhere.

The two objects

Inbound federation takes two objects, authored at two levels:

The split matters: registering an issuer is a tenancy decision for the whole organization, while deciding that one particular repository may become one particular robot is a day-to-day decision inside a namespace.

IdentityProvider

The trust anchor. It names the external issuer and the ceiling of what a trust rule may pin.

apiVersion: core.ringleader.dev/v1
kind: IdentityProvider
metadata:
  name: acmecorp-github     # must be, or start with, the owning org's name
spec:
  org: acmecorp
  profile: github-actions
  allowClaims: ["environment", "job_workflow_ref"]

Two rules to know before you write one:

• Its name must be the owning org’s name, or start with it followed by a hyphen. The kind is cluster-scoped, so every org wanting a provider called github would collide: acmecorp-github or acmecorp, never a bare github.
• Only an org-admin can author one. A namespace member has no access to it at all. If you signed up on your own, you already administer your personal organization, so you can register one for yourself — see Organizations.

Profiles

A profile records one ecosystem’s issuer, how audiences behave there, and — most importantly — the claims a rule must pin to name a stable identity. You cannot pin fewer; you may always pin more.

Run rl serviceaccount trust --help for the same table as your deployment sees it.

ServiceAccount

apiVersion: core.ringleader.dev/v1
kind: ServiceAccount
metadata:
  name: ci
  namespace: dev
spec:
  description: Builds and tests the platform repo
  trust:
    - provider: acmecorp-github
      match:
        repository_owner_id: "1234567"
        repository_id: "7654321"
        environment: production

Trust rules

Each entry of spec.trust is one external identity allowed to become this account.

The matching rules are deliberately blunt:

• Every claim in a rule must match (AND) for that rule to admit.
• Any rule matching admits (OR), so several pipelines can share one account.
• Matching is exact string equality. No prefixes, no wildcards, no regular expressions — an authority boundary is not a place for pattern matching.

Add a rule with the CLI rather than by hand if you like — a rule that pins too few claims for its provider’s profile is refused either way:

rl serviceaccount create ci
rl serviceaccount trust ci --provider acmecorp-github \
    --claim repository_owner_id=1234567 \
    --claim repository_id=7654321 \
    --claim environment=production

Giving it permissions

A service account holds no rights of its own. Rights come from ordinary role bindings naming its subject, exactly as they would for a person:

apiVersion: core.ringleader.dev/v1
kind: RoleBinding
metadata:
  name: ci-can-build
  namespace: dev
spec:
  subjects: ["sa:dev/ci"]
  roleRef:
    kind: GlobalRole
    name: namespace-member

You can never bind an account to more than you hold yourself, so an account is bounded by its author’s own access — before and after it is created.

Status fields

The system writes these.

The Unused condition

Every account publishes an Unused condition, answering “should someone look at this?”. Its reason says which of four situations it is:

Flagging is all it does. Nothing is ever auto-disabled or auto-deleted at any threshold — a quarterly release pipeline is not abandoned, it is quarterly. When an account genuinely is finished, set enabled: false or delete it.

The window is a fixed 30 days. It is not configurable, per account or per deployment: a threshold the owner of a forgotten account could raise until the flag stopped firing would not be worth publishing.

Suspension

An account is suspended when the person who created it no longer has permission to create one in that namespace. It stops being usable immediately, without being deleted, and status.authorityReason says so in as many words. An administrator can restore the creator’s access, or the account can be recreated by someone who does have it.

This is checked continuously, not just at creation — which is what makes “a service account never carries more than its creator could grant directly” stay true after the fact.

Listing and inspecting

rl serviceaccount get (alias sa) answers “which identities is nothing using?” directly:

rl serviceaccount get

NAME        LAST USED   STATUS      AGE
ci          14m         Ready       62d
nightly     41d         Unused      95d
old-robot   NEVER       Unused      210d
legacy-ci   3d          Disabled    1y

• LAST USED is how long ago something last signed in, or NEVER.
• STATUS is one word, most-blocking first: Suspended (the platform withdrew it), Disabled (you switched it off with enabled: false), Unused (the condition above is flagged), else Ready.

rl serviceaccount describe ci adds the full status, including who last assumed the account and under which rule. Sign-ins are also recorded as events in the namespace, so rl event get shows an Assumed entry naming the provider and rule — and an AssumptionRefused warning when something proved a real identity from a provider your org registered but matched none of your rules, which is usually a rule that needs updating.

Signing in as one

From a CI job that has an ambient workload identity, log in with no secret at all:

# .github/workflows/build.yml
permissions:
  id-token: write     # required — this is what lets the job mint its own assertion

rl auth login https://ringleader.example.com \
    --service-account dev/ci \
    --provider acmecorp-github

The CLI asks the job’s platform for an identity assertion, presents it, and gets a short-lived token back. Nothing is stored on disk that is worth stealing: what it keeps is the recipe (which origin, which provider, which account), which is useless without an ambient identity only that runner can produce.

This only works where an ambient workload identity exists. On a laptop there is nothing to exchange, so use the ordinary rl auth login.

Turning one off

Three levers, from narrowest to widest:

1. Delete a trust rule — that external identity can no longer become the account; the others still can.
2. spec.enabled: false on the account — nothing can become it, but the object and its permissions survive, ready to be switched back on.
3. spec.enabled: false on the IdentityProvider — every account trusting that issuer stops working at once. The break-glass switch for a compromised issuer.

Deleting the account removes it entirely. All four take effect on the very next sign-in attempt, not on a cache’s schedule.

See also

• Access control — the roles you bind an account to.
• Organizations — who may register an IdentityProvider.
• rl auth — login, status, and tokens.