Weekly Bitbucket engineering health recap in Notion

Every Monday at 9am in the team's local timezone, run an engineering health recap of last week's Bitbucket activity and publish it as a Notion page. This is a lightweight recurring pulse for engineering managers who don't want to stand up a full analytics dashboard.

Inputs to configure once up front: the Bitbucket workspace slug; either "all repos" or a curated list of repo slugs to include; the Notion parent (a page id or a database id) under which recaps should be created; and the team's timezone for the "week of" label.

Step 1. Determine last week's window. Compute the previous ISO week: Monday 00:00:00 through Sunday 23:59:59 in the team's timezone. Also compute the week before that so the narrative can describe week-over-week movement.

Step 2. Pull merged pull requests for the target window. For each repository in scope, use Bitbucket "List Pull Requests" with state=MERGED and sort=-updated_on, and filter with a BBQL q on updated_on inside the target window (updated_on >= "<start>" AND updated_on <= "<end>"). Follow the HAL next cursors until exhausted. Pull the prior week's merged PRs the same way so we can compute deltas.

Step 3. Enrich each PR. For every PR in scope this week call Bitbucket "Get Pull Request Diffstat" to sum lines added and removed (that sum is the PR's size), and call Bitbucket "List Pull Request Activity" to collect approvals (each approval entry names the approver). Enrich the prior-week PRs the same way for the aggregates we compare against (count, time-to-merge, size).

Step 4. Compute the snapshot for the target week: number of PRs merged; average time from PR open (created_on) to merge (the merged activity timestamp / closed_on), reported in hours or days as appropriate; top three contributors by PRs merged (author display name plus count); top three reviewers by approvals given on merged PRs (approver display name plus count); average PR size (total lines changed per PR); and the ten largest PRs of the week by total lines changed, with title, repo, author, size, and html link.

Step 5. Compare against the prior week. Compute the same aggregate numbers for the previous week and note deltas: PRs merged (+/-), average time-to-merge (faster or slower), average size (+/-). Keep this to one short paragraph of plain English, no charts, just movement.

Step 6. Publish to Notion. Call Notion "Create a Page" under the configured parent (page or database). Title: "Engineering weekly recap - week of <YYYY-MM-DD>" using the Monday date of the target week. Body blocks in this order: (1) a short 2 to 4 sentence narrative summarising the week and the week-over-week movement; (2) a "Snapshot" section with each metric as a bullet (PRs merged, average time to merge, average PR size) showing the current value and the delta vs. last week in parentheses; (3) a "Top contributors" section listing the top three by PRs merged; (4) a "Top reviewers" section listing the top three by approvals given; (5) a "Ten largest PRs" section as a bulleted list where each item is the PR title (linked to the PR html url) followed by " - <repo> - <author> - <lines> lines".

Nuances to bake in. PR size uses added plus removed lines from the diffstat, so lockfile-heavy PRs will look huge and that's fine for a lightweight recap. When there were zero merged PRs, still publish the page and say so in the narrative rather than skipping the week. On ties for the third slot in top contributors or top reviewers, include everyone tied. If the parent is a database, map required properties (title etc.) sensibly; if it's a page, create the recap as a child page. Respect Bitbucket's 429s using the Retry-After header, and stay under Notion's ~3 requests per second — enrichment can be a lot of calls on a busy workspace.

Failure handling: if the Notion page create fails, log the full assembled recap in the run so an operator can copy it in manually. If a specific PR's diffstat or activity call fails, drop that PR from size and reviewer stats but keep it in the merged count, and note the exclusion in the run log.