Smart Announcement Banner for Bitbucket

Three scope levels are what makes this app different from its Jira and Confluence siblings, and the level is derived server-side from Bitbucket’s own context — never from the client. The workspace settings console publishes to everyone in the workspace; the project console reaches every repository in that project; the repository console reaches that repository only.

Readers get them in three places: a compact strip at the top of the repository source page, the full announcement centre under Repository → Apps, and a workspace-level centre under Workspace → Apps that reaches announcements outside any repository.

Smart Announcement Banner is one of three sibling apps — Jira, Confluence and Bitbucket. They are separate apps because Forge app storage is scoped to the installation: installing one app on both Jira and Confluence creates two independent installations with completely separate storage, so a single app could never deliver “publish this announcement to Jira and Confluence”. Splitting makes that platform reality the design instead of a footnote. Bitbucket was already separate for a different reason — a single Forge app cannot mix Bitbucket workspace scopes with Jira/Confluence site scopes.

Bitbucket has no true banner module. There is no equivalent of confluence:pageBanner that renders a strip above content on every page. The repository code-overview panel is the closest placement available, and it comes with two constraints worth knowing: it only appears on the repository source page — not Commits, Pull requests or Pipelines — and it is user-collapsible, with Bitbucket remembering the collapsed state. A reader who collapses it stops seeing announcements there until they expand it again. The Apps → Announcements page is the reliable fallback.

The panel runs in compact mode: when there is nothing outstanding it renders nothing at all rather than an empty state, so it never pushes a reader’s code down for no reason.

The workspace announcement centre is workspace-only, and says so. It reuses the same reader surface and component as the repository pages; the difference is entirely server-side. Project- and repository-scoped announcements are only merged when the request context carries a repository id to match them against, and a workspace page’s context carries none. The page states this rather than leaving a reader to wonder why a project notice they know about is missing.

Resolving a repository’s project. Project-scoped announcements can only reach a reader if the app knows which project their repository belongs to. Atlassian’s module docs list only repository.uuid on that surface’s context; in practice the live context also carries a top-level workspaceId, so the direct repository lookup is the path normally taken, with a UUID-query fallback for the documented case. Project membership is authorization data and repositories can move between projects, so every reader authorization decision performs a fresh lookup rather than using a stale cache.

Who this is forWhoever publishes announcements. Each console is already permission-gated by the product, so a delegated admin needs no extra grant — and gains no reach beyond their own container.

Every console manages only its own scope, and that is the point: a project or space lead can publish to their own people without a site admin in the loop. Each console states its reach under the heading, next to a scope lozenge.

1. Open the console for the level you want to publish at

   You cannot choose the level in the composer — it comes from the page you are on. That is what stops a delegated admin publishing site-wide, and it is why the composer states the reach rather than offering it as a dropdown.

   Workspace reaches everyone in every repository — outages and org-wide policy. Project reaches every repository in that project — conventions, project migrations. Repository reaches that repository only — a repo freeze, an ownership change.

2. Write the content

   Click New announcement. Title (required, 120 characters) and Message (required, 2000 characters) are the two required fields; each new line in the message becomes its own paragraph for readers.

   Pick a Type — Critical, Warning, Information, Success or Tip — by what the reader must do, not by how loud you want to be. Critical on a routine notice trains people to ignore Critical. Priority runs 1–5 and affects ordering.

   The composer shows a live preview at the top that is the real reader component fed real validated data — what you see there is exactly what readers get.

3. Decide how readers clear it

   Require acknowledgement — the reader clicks “Got it”. Recorded per person, reported in Insights, never returns. Dismissible — the reader closes it, and it returns after the snooze you set (0 hours makes the dismissal permanent for that reader). Always visible — no close control at all.

   Use Always visible sparingly: it cannot be cleared by the reader. Pin above other announcements puts this one first regardless of priority.

4. Choose who sees it

   Everyone, only these people, or everyone except these people — matched on Atlassian account ids, comma- or newline-separated. Bitbucket has no group options. It exposes no group-membership endpoint this app can read, so a group rule could never be evaluated — and rather than offer a control that silently matches nobody, it is not offered.

   “Everyone” means everyone this announcement reaches: on a delegated console that is the people in that container, not the whole site. Targeting narrows within the scope; it never widens it.

   An announcement targeted at anyone other than “Everyone” is hidden from unauthenticated readers, including exclude-modes — the app cannot confirm an anonymous reader is not one of the excluded people.

5. Set the schedule, and read the line under the fields

   Starts and Ends are optional, entered in your timezone and stored as UTC. Leave both empty to run until you pause it.

   Use the calendar button rather than typing. The date field parses typed text in your browser’s locale, so 2026-08-20 is not read as 20 August everywhere. The line under the fields always spells out the window the pickers actually resolved to — read it before saving, because a start date in the past still counts as Live and the mistake is otherwise invisible until the announcement goes out early.

6. Publish, or stage it paused

   The footer toggle reads Publish when saved / Save as paused. Saving as paused is always allowed, and is how you stage the next announcement while the current one is still running.

7. Watch Insights, and reset reads if the content changes

   Acknowledgements (deduplicated per person), people engaged (distinct readers who acknowledged, dismissed or snoozed), and per-announcement breakdowns. A dismissible announcement produces no acknowledgements, so the table reports whichever number that mode actually generates rather than a permanently-zero column.

   Reset reads starts a new engagement epoch without changing the content, re-showing the announcement to everyone who already cleared it. Use it when an announcement’s content changed materially.

The UUID-query fallback for the repository→project lookup runs on read:repository:bitbucket, which the app already holds. The more obvious /2.0/workspaces route would also work, but forge lint flags it as requiring both read:user:bitbucket and read:workspace:bitbucket — more access than a fallback justifies.

Legacy aggregate KVS records migrate idempotently on first access. Ambiguous legacy audience or scope data is paused instead of being widened to everyone.

• No group targeting. Audiences are everyone / only these people / everyone except these people. Bitbucket exposes no group-membership endpoint this app can read, so a group rule could never be evaluated. The previous version offered group targeting anyway and it matched nobody: an announcement an admin believed was live reached zero people, silently. Offering only what can actually be honoured is the fix.
• The overview panel appears only on the repository source page, and it is user-collapsible with the collapsed state remembered by Bitbucket. Apps → Announcements is the reliable fallback.
• The workspace announcement centre shows workspace-wide announcements only, because its request context carries no repository to match project- and repository-scoped announcements against. The page states this.
• A cross-app fix is three separate reviews, not one patch applied thrice.

Version history for Smart Announcement Banner for Bitbucket. The most recent release is listed first.

1. v0.1.0 Current

   First build, verified live on a real Bitbucket workspace.

   What it does

   • Three scope levels — workspace, project and repository — each with its own admin console, and each derived server-side from Bitbucket’s context.
   • Three reader surfaces: the repository code-overview panel, the repository announcement centre, and a workspace announcement centre outside any repository.
   • Five announcement types, priority and pinning, an optional call-to-action, scheduling, and three dismissal modes.
   • Project-named badges, so two same-titled notices from different projects stay distinguishable.
   • Five stable custom entity types with generation-swapped targets, engagement epochs and 90-day activity receipts, plus a daily privacy trigger.

   Found only by running it live

   • Bitbucket sends no moduleKey. The admin gate originally checked it and rejected every legitimate request. The real context carries extension.type instead, which is what the gate now uses.
   • Bitbucket REST paths 404 on a bare UUID. Scope ids are stored unwrapped because braces are not storage-key safe, but the repository endpoint needs them wrapped — so the repository→project lookup failed and project-scoped announcements reached nobody until the ids were re-wrapped for the request.

   Removed

   • Group targeting. Bitbucket exposes no group-membership endpoint this app can read, so the option had always matched nobody — silently.

   Verification

   • All three admin consoles load and are scope-isolated: the project and repository consoles each showed 0 announcements while a workspace-wide one existed.
   • A workspace announcement and a project announcement both appeared on the repository reader page, project first, each tagged with its level.
   • Acknowledging cleared only that announcement for that reader.
   • The workspace nav module renders its heading, its workspace-only note, and the same empty state as the other reader surfaces.