Database governance built for humans and agents — controlling changes and access across every major database.
Approval steps held by service accounts and workload identities
Status: implemented in this PR · 2026-10-12
A custom approval step whose role is held only by service accounts shows "No reviewers" on the plan page, and the code comment beside that string says the step can never be approved. Both are wrong: the backend already lets a service account or workload identity approve any step whose role it holds, and a customer's ServiceNow integration does exactly that. The review UI applies a display filter the authorization model does not have. A principal that holds a step's role is an approver whatever its type: the review surfaces list it, name it, and attribute its decision the same way they do for a person. Notifications stay human-only.
Problem
A customer (2026-10-08) ends every change's approval flow with a custom role "ServiceNow Approver" held
by two service accounts: a workspace account integration bound at workspace and
project level, and a project account approver bound at project level. The plan page shows the step
as "No reviewers", so the customer asked whether the flow is supported at all.
Reproduced on a throwaway 3.24-dev instance with the same shape (Developer → Workspace DBA → ServiceNow Approver). What each surface showed before this change, from real screenshots in the PR body:
| Surface | Before | Where |
|---|---|---|
| Reviewer line under a pending or current step | "No reviewers" | ReviewApprovalFlow.tsx NodeReviewers; comment claims the step "can never be approved" (BYT-9711) |
| Folded-pending popover row | avatars omitted silently | PendingPopoverRow, candidates.length > 0 guard |
| Header "Review in progress" popover | "No reviewers" | PlanStatusAction.tsx → ReviewApprovalFlow compact |
| "Approved by …" after the SA approves via API | Approved by integration (email local part, no title, no account-type mark) |
FlowNode subtitle, ApprovedPopoverRow, ChipAvatars: getUserByIdentifier misses, unknownUser(principal) fills in |
| Activity row for the approval comment | integration approved issue |
IssueCommentActivity.tsx IssueCommentHeader, same fallback |
| Collapsed REVIEW summary | Last approved by integration |
phaseSummary.ts: local part for every principal, humans included |
| Legacy issue page (grant issues) | approver hidden: "Approved by" followed by nothing; candidates filtered to humans | IssueDetailApprovalFlow.tsx ApprovalUserText returns null for non-USER; useApprovalStep filters AccountType.USER |
The authorization side is consistent and needs no change. canReview in
backend/component/review/workflow.go resolves roles through GetUserFormattedRolesMap, which
matches serviceAccounts/{email} and workloadIdentities/{email} members directly. The customer's three
binding shapes all pass. The approval is recorded as users/<sa-email>
(common.FormatUserEmail(actor.Email)), the approval comment's creator is the SA email, the
webhook actor is the SA's UserMessage, and the audit log names the actor
serviceAccounts/<sa-email>.
Principle
Who may approve is decided by IAM, not by principal type. The UI explains that decision; it never narrows it. A step with no human holder is still a step someone can act on, and the page must say who.
Approver truth table
One row per kind of role holder. Cells that change are marked →.
| Principal | Can approve (backend) | Listed as reviewer | Mentioned in approval-requested notification | "Approved by" / activity attribution |
|---|---|---|---|---|
| End user, direct or via group | yes | yes | yes | title |
| Service account (workspace), bound at workspace IAM | yes | no → yes, badge "Service Account" | no (by design) | local part → title + badge |
| Service account (workspace), bound at project IAM | yes | no → yes | no | local part → title + badge |
Service account (project [email protected]), bound at project IAM |
yes | no → yes | no | local part → title + badge |
| Workload identity, bound at either level | yes (canReview matches workloadIdentities/) |
no → yes, badge "Workload Identity" | no | local part → title + badge |
| Deleted service account or workload identity still bound | no (cannot authenticate) | filtered like a deleted user (State.ACTIVE check) |
no | as recorded |
Self-approval and last-plan-editor rules apply to every row by email: the backend compares
issue.CreatorEmail and plan.LastPlanEditor with actor.Email, and SA emails cannot collide
with human emails because validateEndUserEmail refuses the service.bytebase.com and
workload.bytebase.com suffixes for people.
Decisions
D1 · The reviewer list is every principal holding the step's role. Project IAM plus workspace
IAM, with serviceAccounts/ and workloadIdentities/ names kept where useApprovalCandidates
used to drop them. "No reviewers" then means what it says: no principal holds the role. A listed
holder can still be barred by the self-approval or last-plan-editor rule, exactly as a person is
today; the list answers who holds the role, not who may act right now. Groups are expanded as
today, as people: the Groups page adds only users/ members. A service account written into a
group through the API can approve, because the backend matches the stored member string, but it is
not listed; that case is left alone. Rejected: keep the human filter and reword to "No human
reviewers". It still hides who can act, which is the question the customer asked.
D2 · Non-human principals resolve through their own services, never the user service.
BatchGetUsers and GetUser reject SA and WI emails (validateEndUserEmail), and one such name
fails the whole batch. The candidate hook therefore splits IAM names by prefix: users/ through
batchGetOrFetchUsers, serviceAccounts/ through fetchServiceAccount, workloadIdentities/
through fetchWorkloadIdentity. A recorded approver or creator is users/<email> whatever its
type (D5), so there the split is by email suffix, which usePrincipal.ts on the issue-detail page
already does. It becomes the shared hooks/usePrincipal.ts and serves "Approved by", the approved
chip avatars, the activity header and avatar, the header status, and the rejection banner. The plan
page makes no failing user-service call today only because it never fetches approvers. The plan and
issue lists do: they prefetch creators through batchGetOrFetchUsers, and a page holding one
SA-created plan gets a 400 for the whole batch, people included. The user store's fetch entry
points therefore skip non-human emails instead of sending them, which fixes every caller at once.
Rejected: teach BatchGetUsers to return SAs. The split services are deliberate, and the Members
page already lives with it.
D3 · The account-type mark is the existing AccountTypeBadge. It derives the type from the
email suffix, which the server enforces, so a person cannot carry a "Service Account" badge and an
SA cannot shed it. That holds once the frontend applies the server's rule: getAccountTypeByEmail
accepts any email that ends in the suffix, while IsServiceAccountEmail requires the suffix to be
the whole domain or to follow a project label and a dot, so a person at [email protected]
is a service account to the frontend alone. D2 routes fetches on this classifier, so it is
tightened to the server's rule. The badge gains a compact form with the geometry of the "Current"
badge (px-1.5 py-0 text-xs): it sits after the title and never shrinks, and the title truncates.
The legacy issue page's sidebar is too narrow for both on one line, so there the badge sits
beneath the name. The name identifies the principal and the mark only qualifies it, so the mark
never outweighs the name: it is drawn in the neutral control colors, as the Users and Service
Accounts pages already draw the account type, and at regular weight in the compact form, because
the names in the step, the reviewer list and the sidebar are regular weight. Rejected: the accent
pill the badge had on the Members page. Accent is for primary action and selected state, and in a
dense review row it read as more important than the name. Rejected: a distinct robot avatar
glyph. The Members page sets the precedent of initials avatar plus badge, and reviewers scan the
badge text, not the avatar.
D4 · A candidate of any type carries the attribution name users/<email>. issue.creator and
plan.lastPlanEditor are users/<email> for every actor, SAs included. A service account or
workload identity is therefore listed through the same User projection the Members page uses
(workloadIdentityToUser, and a serviceAccountToUser twin), so getApprovalEligibility's name
comparison holds unchanged. Naming the candidate serviceAccounts/<email> would show an SA creator
as eligible to approve its own plan when the backend refuses.
D5 · The stored approver principal stays users/<email>. Switching applyReviewAction to
common.FormatPrincipalMember was inventoried against every consumer: issue_service_converter.go
passes the string through; utils.FindNextPendingRole, FindRejectedRole and
store/issue_approval_status.go read only status and count; approvalsEqual and the staleness
check in ReviewIssue compare whole protos; store/principal.go rewrites users/<old> →
users/<new> when a user's email changes, which cannot happen to an SA (UpdateServiceAccount
accepts only title and service_key); webhooks use the actor's UserMessage, not the stored
string. Nothing needs the type in the string, because the email suffix already carries it. The
codebase has two conventions and this field belongs to the first: attribution fields
(issue.creator, plan.creator, plan.last_plan_editor, comment creators) are users/<email>
for every actor, while policy members and the audit-log actor carry the typed prefix. A new format
would need a backfill for every SA approval already stored (the customer's included) and dual-format
readers forever, for no information gain.
D6 · Notifications are unchanged. getApproversForRole keeps END_USER only and
webhook/manager.go filters mentions to end users; a machine has no IM identity to mention. The
UI's reviewer list and the notification's mention list are therefore different sets, and the
comment on getApproversForRole says so.
D7 · The legacy issue page uses the same two hooks. IssueDetailApprovalFlow.tsx still renders
grant issues (create-database, access, role) and carried its own copy of the candidate pipeline.
That copy is removed: useApprovalCandidates moves beside approvalEligibility.ts and both pages
call it. ApprovalUserText adopts the principal hook, so a role-grant request approved by an SA
no longer reads "Approved by" followed by a blank. It also stops hiding an approver who has since
been deactivated: a decided step names whoever decided it.
States of the reviewer line
| Role holders | Line | Popover |
|---|---|---|
| Humans only | avatar stack + "N reviewers" (unchanged) | rows: title, email, ineligibility note |
| Service accounts and workload identities only | avatar stack + "N reviewers" | rows carry the account-type badge |
| Mixed | humans first, current user first, then by title | same |
| Nobody | "No reviewers" | none |
| Policy not loaded | nothing (unchanged) | none |
| Holder record does not resolve | avatar from the email local part, badge still correct | row shows local part as title |
The last row is rare. GetServiceAccount and GetWorkloadIdentity need bb.serviceAccounts.get
/ bb.workloadIdentities.get, and every predefined workspace role carries both, Workspace Member
included (backend/store/predefined_roles.go). It takes a workspace that replaces Workspace
Member with a narrower custom role, or a binding that names an account that was never created.
The badge never depends on the fetch because the suffix is in the name.
Risks
R1 · Showing machines as approvers makes an existing capability visible. Nothing new becomes possible: an SA could already approve, and the audit log already records it. What changes is that a reviewer reading the page learns that a machine can close the step. That is the governed path (IAM binding, reviewed as code) and the shape Bytebase itself recommended when external approval was removed. The design does not add a project setting to forbid non-human approvers; a workspace that does not want them removes the binding.
R2 · Self-approval by the integration's own account. An SA that creates the plan through the API and holds the approver role is refused by the backend unless the project allows self-approval, exactly as a person is. D4 keeps the UI's eligibility note in step; getting it wrong would only mislead, not grant.
R3 · Spoofing the badge. Impossible by construction: the suffixes are reserved server-side for SA and WI records, and the badge reads the suffix.
R4 · Fetch noise and permission. Resolving the recorded users/<sa-email> through the user
store would add a failing request per plan view (D2). Fetching through the SA/WI services is
permitted for every predefined workspace role. Where a custom role lacks the read permission the
fetch fails silently and the row shows the local-part title. The SA and WI stores dedupe in-flight
requests and cache successes, not failures, so such a viewer pays one silent request per holder
per mount, never a loop; the user store treats a person it cannot resolve the same way. No
negative cache is added for that case.
R5 · Stale bindings. A deleted SA or WI stays in the IAM policy until an administrator removes
the binding, and it can no longer authenticate. Its record still resolves: deletion is soft, and
GetServiceAccount / GetWorkloadIdentity return it with state: DELETED. The hook applies the
State.ACTIVE filter that already drops a deleted user, so the line never lists it. The hook does
not branch on why a fetch failed, which the stores do not expose: a holder whose record does not
resolve keeps its placeholder and stays listed, as a person does today through unknownUser.
R6 · Approval-flow width. The "Approved by" subtitle is a fixed-height truncating line; the
badge is shrink-0 and the title truncates, so a long SA title never pushes the badge out of
view. The reviewer popover widens from 240px to 288px so a title keeps room beside the badge;
the vertical layout below 560px stacks the same row.
R7 · Existing stored data. Every SA approval ever recorded is users/<sa-email> and renders
correctly under D5 without migration. Customers on older versions keep seeing the local-part
fallback until they upgrade; no data changes.
Scope
| File | Change |
|---|---|
frontend/src/routes/project/useApprovalCandidates.ts (moved from plan-detail/components/review/) |
keep SA/WI names; resolve by prefix; list each as a users/<email> user; filter resolved records by state; people first |
frontend/src/hooks/usePrincipal.ts (moved from issue-detail/components/) |
shared; principalLabel names a principal by title, or by its email until a record arrives |
frontend/src/components/AccountTypeBadge.tsx |
compact form; neutral colors in place of accent, on every surface that uses it |
frontend/src/routes/project/plan-detail/components/review/ReviewApprovalFlow.tsx |
badge in CandidateRow, FlowNode subtitle, ApprovedPopoverRow; chip avatars through the hook; popover width; the BYT-9711 comment |
frontend/src/components/issue-activity/IssueCommentActivity.tsx |
CommentCreator and ActivityUserIcon take the principal and resolve it through the hook, badge after the name |
PlanStatusAction.tsx, ReviewRejectionBanner.tsx, ReviewActivityTimeline.tsx |
whoever rejected or acted, through the hook |
IssueDetailApprovalFlow.tsx, IssueDetailCommentList.tsx |
shared candidates hook in place of the local pipeline; approver identity with the badge beneath |
frontend/src/stores/app/user.ts |
batchGetOrFetchUsers and fetchUser skip non-human emails instead of sending them to the user service |
frontend/src/stores/app/serviceAccount.ts |
serviceAccountToUser |
frontend/src/types/v1/user.ts |
getAccountTypeByEmail applies the server's domain-boundary rule |
backend/component/review/evaluator.go |
comment on getApproversForRole: it returns the people to notify, not everyone who can approve |
Tests:
| File | Covers |
|---|---|
backend/component/review/workflow_test.go |
an SA approves via workspace IAM, via project IAM, and as a project SA; a WI via project IAM; each is recorded as users/<email>; an SA bound under users/ and an SA that created the issue are refused |
useApprovalCandidates.test.tsx |
SA-only role; people before machines; nobody; deleted SA dropped, unresolved SA kept; SA creator held to self-approval; SA bound as user: not listed |
ReviewApprovalFlow.test.tsx |
SA-held step shows its reviewer; no holder says "No reviewers"; a step decided by an SA shows title and badge; a person without a record falls back to the email name, unmarked |
IssueCommentActivity.test.tsx |
an SA's approval names it with the badge; a person's does not |
AccountTypeBadge.test.tsx |
nothing for a person; the type named for an SA and a WI; neither form is drawn in accent |
stores/app/user.test.ts |
a batch that contains an SA email still resolves the people in it and sends nothing for the SA; a lone SA is never asked of the user service |
types/v1/user.test.ts |
the classifier against the server's rule, including [email protected] |
tests/e2e/plan-detail/plan-detail-review.spec.ts |
in a browser: an SA-held step lists the account with its badge; after the SA approves through the API the step and the activity name it |
Not in this PR
- Mentioning non-human approvers in IM notifications.
- Fetching SA/WI records on the Members page so it shows titles instead of the local part.
- Approver-type restrictions as a project setting.
- Listing a service account that was added to a group through the API.
- Showing an SA creator's title in the plan and issue lists; they keep the local-part fallback.
- Stating the
users/{email}convention in theApprover.principalproto comments: a comment-only proto edit regenerates the API docs and can ride on a change that already touches those files.