User License Cleanup & Dashboard for Bitbucket

Most user-cleanup apps stop at “here is a list of people who have not logged in — tick the boxes to deactivate them”. That list is the easy half of the problem, and acting on it blindly is how you break a production pipeline.

Billable-path clarity. For every user the app shows which access path keeps the seat billable — a direct repository grant, a project grant, an inferred group grant, or plain workspace membership — and, critically, whether the app can remove it or whether you have to do something in Atlassian admin. A seat only frees up when every path is gone, so a list of names without paths tells you nothing actionable.

Bitbucket-specific service-account safety. In Bitbucket, a large share of the busiest accounts are CI identities authenticating with app passwords or API tokens. Those never register as interactive product activity, so by the standard “last login” measure they look completely dead. This app subscribes to push and pull-request events so it can tell “nobody is using this seat” apart from “a robot is using this seat hard”.

Bitbucket is not Jira. Revoking the wrong seat here does not inconvenience someone — it fails builds, blocks deployments and can take a release train down. The intended order:

1. Never run Live before a Safe-mode pass. Read the plan, then read the skipped-by-safety-rails list underneath it.

2. Treat every “likely service account” as a real finding. Confirm ownership, then add an explicit exclusion.

3. Give the git-activity signal time to accumulate. On a fresh install that signal is empty, so lean on the quarantine list rather than on the safety window.

4. Keep the safety window at 30 days or more. Any push or PR inside the window makes a user un-flaggable regardless of login history. A nightly job that only runs monthly needs a window longer than its cadence.

5. Leave scheduled scans on “report only”. Auto-apply exists, is opt-in, and still honours every rail — but nobody reviews the plan first.

6. Know the restore path before you need it. Use it the moment a build starts failing; investigate afterwards.

Who this is forBitbucket workspace administrators. The organization API key that unlocks inactivity detection has to be created by an organization admin, who may be someone else.

Bitbucket is not Jira. Revoking the wrong seat here does not inconvenience someone — it fails builds, blocks deployments and can take a release train down. The setup order below exists for that reason, and step three is the one that protects your pipelines.

1. Create the organization API key

   Last-login data does not come from Bitbucket’s API. It comes from the Atlassian Admin (Organizations) API, which uses a credential Forge cannot mint for itself.

   At admin.atlassian.com → Settings → API keys → Create API key, give it a name and an expiry, then copy the key and the organization id — the key is shown once.

2. Store it in the app

   Workspace settings → Forge Apps → User License Cleanup → Settings. Paste the key (the org id is optional — leave it blank to auto-detect) and choose Verify and save.

   The key is validated against the API before it is stored, is written with Forge’s encrypted secret store, is never returned to the browser, and is only ever sent to api.atlassian.com. Only the last four characters are shown back to you, so you can confirm which key is installed.

   The key is optional to install but required for inactivity detection. Without it the app still maps billable paths and flags service accounts; it just cannot tell you who is idle.

3. Configure exclusions before your first live run

   This is the step that protects your pipelines. On the Excluded tab, add a rule for every CI, bot and integration account you know about.

   Prefer a user exclusion (exact account id) or a pattern exclusion for anything you cannot afford to break. Explicit exclusions survive threshold changes; heuristics do not.

4. Run a scan and read the data-source notes first

   Run scan now on the toolbar. The scan runs in the background and results appear as batches complete.

   Read the Overview tab’s honest report on which data sources actually worked before trusting any number on the page.

5. Do a Safe-mode pass, then read what was skipped

   Safe mode produces the exact same plan object that Live mode executes — there is no separate code path. Read the plan, then read the Skipped by safety rails list underneath it. That list is the app telling you what it refuses to touch, and why.

   Never run Live mode before a Safe-mode pass.

6. Treat every “likely service account” as a real finding

   The heuristic quarantines them from bulk actions rather than excluding them silently, because a wrong auto-exclusion is as bad as a wrong revocation. Confirm ownership for each, then add an explicit exclusion.

7. Apply, and know the restore path before you need it

   Live apply requires a typed confirmation. Every applied action records the permission level it removed, so Restore all applied changes on the Cleanup tab is an exact replay.

   Use it the moment a build starts failing; investigate afterwards. The app never deletes an account and never performs an irreversible operation — the worst case is a revoked permission grant, one button away from being restored.

admin:project:bitbucket is deliberately not requested, even though project-grant revocation may require it. That scope also confers project deletion, which a licence-cleanup app has no business holding. If a project-grant revocation returns 403, the action is marked failed with the API’s message and written to the audit log — it fails loudly, not silently.

• Group membership is not readable. Bitbucket exposes user groups only through the deprecated 1.0 API, which Forge apps cannot call. The app therefore cannot remove a user from a group: group-derived paths are labelled “Group grant (inferred)”, marked non-removable, and carry instructions pointing at workspace settings. Membership is inferred from effect. For a hard guarantee, use a user or pattern exclusion.
• Workspace membership cannot be removed via the API. Bitbucket does not support it; membership is managed in Atlassian admin or via SCIM. The app reports these paths and says where to go.
• Project-grant revocation is unverified against a live workspace, because the scope it may additionally require also confers project deletion and is deliberately not requested. A 403 is recorded as a failed action with the API’s message.
• The Admin API only covers managed accounts. External collaborators and contractors on personal accounts return no record, are classified unknown, and are never auto-actioned.
• Last-active data lags up to 24 hours and counts only interactive product use — which is exactly why the git-activity event triggers exist.
• Git activity starts at installation. An identity that pushed last month but not since installation has no write date yet. Do not act on the first scan of a fresh install.
• The repository access index is eventually consistent. It builds in bounded background batches and parks itself when the workspace nears its hourly API limit. Inactivity results are unaffected, and the Overview tab states where the index has got to.
• Notifications are recorded, not emailed. Forge has no first-party outbound email API. Enabling notifications still changes behaviour end to end — the first plan for a flagged user records a notice with a deadline instead of revoking anything, and every later plan refuses to touch that user until the lead time elapses. Only delivery is missing.
• CSV export renders for copy, not download. UI Kit is sandboxed with no filesystem or Blob access. The content is byte-identical to a download.
• Data Center is out of scope. This is a Forge Cloud app.

Version history for User License Cleanup & Dashboard for Bitbucket. The most recent release is listed first.

1. v1.0.0 Current

   Initial release.

   What it does

   • Inactive and never-logged-in seat detection for a Bitbucket Cloud workspace, with a per-user billable-path breakdown that says which grant to remove and whether the app can remove it.
   • Service-account detection built for Bitbucket specifically: push and pull-request product events distinguish a token-driven CI identity from an abandoned human account.
   • Safe/Live cleanup with a shared plan object, typed confirmation, and an exact restore of every applied change.
   • Exclusion rules by user, pattern and synthesised group label, with the Excluded tab showing which rule or heuristic spared each user.
   • Scheduled scans (default weekly, report only), an append-only audit log, and CSV export from any view.

   Defaults, and the reasoning

   • Inactivity threshold 90 days — long enough to survive parental leave, sabbaticals and long holidays; short enough that a quarterly audit is meaningful. 30 days produces too many false positives in engineering organisations.
   • Never-logged-in grace 14 days — an invited user who has not accepted yet is a pending invite, not waste.
   • Recent-activity safety window 30 days — longer than the slowest common CI cadence plus margin.
   • Service-account confidence threshold 50%, notification lead time 7 days, scan cadence weekly, report only.

   Deliberate omissions

   • admin:project:bitbucket is not requested, because it also confers project deletion.
   • No commit or pull-request history is read; git activity comes from product events, which cost nothing and cannot exhaust a rate limit.
   • No account is ever deleted, and no irreversible operation exists in the codebase.