:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
chore(devex): re-create fork prs and thank contributors on merge (#122642)
Raúl Negrón-Otero945c2ab39b31
diff --git a/.agents/skills/merging-prs/SKILL.md b/.agents/skills/merging-prs/SKILL.mdindex e29e2578ae0a..d9cb45c9aecb 100644--- a/.agents/skills/merging-prs/SKILL.md+++ b/.agents/skills/merging-prs/SKILL.md@@ -55,7 +55,7 @@ gh pr view <n> --json state,isDraft,mergeable,reviewDecision,statusCheckRollup,b- **Failing required checks** (`statusCheckRollup`) → the queue will just reject it. Report which checks are red and stop; fix them first. **Pending** checks are fine — the queue waits for them. To work out _why_ a check is red, use `/debugging-ci-failures`.- **Merge conflicts** (`mergeable == "CONFLICTING"`) → report and stop; merge `master` in first.-- **Head is on a fork** (`isCrossRepository == true`) → backend CI ran on GitHub Actions, so the required check is on the head as usual. Depot's optional checks are absent; that is expected and needs no action.+- **Head is on a fork** (`isCrossRepository == true`) → Depot CI starts no backend run for a fork, so `Backend CI on Depot / Test results` stays pending and the queue cannot merge it. Report that and stop. After review, a PostHog engineer re-creates the change on a branch in this repository with `/recreating-fork-prs`.- **Missing approval** (`reviewDecision == "REVIEW_REQUIRED"`, or a stamphog approval was dismissed) → ask stamphog for a review. Stamphog is the automated review-and-approve flow ([the engine README](../../../products/stamphog/packages/pr-approval-agent/README.md)): on an `APPROVED` verdict the Stamphog app posts the approval that satisfies the required review. Use the MCP route first, and the label only when MCP is not available.- **MCP (first choice).** Call the PostHog MCP tool `stamphog-review-runs-create` with `repository` (the `$REPO` slug) and `pr_number`. It returns the run at once, with status `queued`. Poll `stamphog-review-runs-get` with the run `id` until `status` is `completed`, `gated`, `failed`, or `superseded`. Read `verdict` and `reasoning` there, not on GitHub. `created: false` means a run already covers the current head, so do not request again until the head moves. A request covers one head: after you push, request again.- **Refusals.** A `409 not_reviewable` means stamphog does not review this PR at all (a draft, closed, bot-authored, from outside the repo, or an author without write access). The message says which. The label cannot help there, so report it.diff --git a/.agents/skills/posthog-desktop/SKILL.md b/.agents/skills/posthog-desktop/SKILL.mdindex 53976ec465c7..981b29b2114e 100644--- a/.agents/skills/posthog-desktop/SKILL.md+++ b/.agents/skills/posthog-desktop/SKILL.md@@ -40,7 +40,7 @@ Step outside only when one of these is true:`.github/scripts/desktop/`, and the exclusion entries in `pnpm-workspace.yaml`,`pyproject.toml`, `pytest.ini`, `package.json` (`lint:css`), `frontend/jest.config.ts`,`.dockerignore`, `.oxlintrc.json`, `.oxfmtrc.json`, `.config/.markdownlint-cli2.jsonc`,- `.github/workflows/ci-{frontend,storybook,backend}.yml` (+ `.depot/workflows/ci-backend.yml`).+ `.github/workflows/ci-{frontend,storybook}.yml`, `.depot/workflows/ci-backend.yml`.Touch these only to keep an exclusion correct; say so when you do.4. **The agent runtime changes.** `@posthog/agent`, `agent-contracts`, `enricher`, `git` and`harness` live in a sibling workspace at `packages/agent/` (same toolchain, own lockfile),diff --git a/.agents/skills/recreating-fork-prs/SKILL.md b/.agents/skills/recreating-fork-prs/SKILL.mdnew file mode 100644index 000000000000..10614ac1c200--- /dev/null+++ b/.agents/skills/recreating-fork-prs/SKILL.md@@ -0,0 +1,113 @@+---+name: recreating-fork-prs+description: >+ Re-creates a reviewed pull request from a fork on a branch in PostHog/posthog,+ so it can get the required checks and merge, while the contributor stays the+ commit author and GitHub credits them on the squash commit. Use when a fork PR+ fails with "Depot CI does not run fork pull requests", when its+ `Backend CI on Depot / Test results` check stays pending, or when someone asks+ how to merge, land, carry over, or take over a contributor or community PR.+ Not for pull requests opened from a branch in this repository.+---++# Re-creating fork pull requests++Depot CI never runs code from a fork, so a fork PR never gets the required `Backend CI on Depot / Test results` check and cannot merge.+A maintainer re-creates the reviewed change on a branch in this repository.+[Pull requests from forks](../../../docs/published/handbook/engineering/fork-pull-requests.md) has the reasons.++A branch in this repository is trusted: secret-gated CI steps run with its code in control.+Push only the commits you reviewed.+The push and the new PR act in the user's name. Get the user's go-ahead for each one.++```text+- [ ] 1. Pin the fork PR's head SHA, then review it+- [ ] 2. Rebuild the change on a new branch+- [ ] 3. Compare the branch with the reviewed SHA+- [ ] 4. Open the new PR+```++## 1. Pin, then review++```sh+gh pr view <n> --json headRefOid,author,isCrossRepository+```++Review the code at that `headRefOid`.+When the review ends, run the command again.+If `headRefOid` changed, the contributor pushed during the review: review the new commits and pin the new SHA.+Every later step uses the pinned SHA, never the fork's branch name.++## 2. Rebuild the change++GitHub serves fork commits by SHA from this repository:++```sh+git fetch origin master <sha>+git switch -c <branch> origin/master+```++List who wrote the commits. GitHub credits an author only when the commit email is linked to their account, and an empty `login` means it is not:++```sh+gh pr view <n> --json commits --jq '.commits[].authors[] | {login, email}'+```++When one person wrote every commit (merges from master aside), squash.+Use their linked email, or else the PR author's no-reply address:++```sh+gh api users/<login> --jq '"\(.id)+\(.login)@users.noreply.github.com"'+git merge --squash <sha>+git commit --author="<name> <email>"+```++When several people wrote commits, cherry-pick, so each author keeps credit:++```sh+git cherry-pick --no-merges "$(git merge-base origin/master <sha>)..<sha>"+```++An empty commit, such as one pushed only to rerun CI, stops the cherry-pick. Drop it with `git cherry-pick --skip`.++A conflict can mean that master already has part of the change, from another PR or an earlier re-creation.+Search master for it before you resolve the conflict, and stop if the fork PR is no longer needed.++Both paths keep the contributor as author and make you the committer.+Every branch here requires signed commits, so contributor commits cannot be pushed as they are.+Your commits carry your signature when `commit.gpgsign` is on.++## 3. Compare before the first push++A push to this repository cannot be taken back, so check the branch first.+Run this before you add your own commits:++```sh+{+ git diff --name-only --no-renames -z "$(git merge-base origin/master <sha>)" <sha>+ git diff --name-only --no-renames -z origin/master HEAD+} | xargs -0 git diff <sha> HEAD --+```++No output means the branch matches the reviewed code in every file that the fork PR or the new branch changes.+Each remaining hunk is a master change made after the fork branched, or a conflict resolution, or a fix the contributor made inside a merge commit that `--no-merges` dropped.+Read each hunk and know which kind it is.++Then add your own fixes as separate commits, so the history shows which part is theirs.++## 4. Open the new PR++Write the body with `/writing-pr-descriptions` and the repo template. Then add:++- In Problem: "Contributed by @<login> in #<n>, which cannot merge because backend CI does not run for fork PRs."+- Anywhere in the body, this hidden marker, exactly: `<!-- fork-pr: <n> @<login> -->`. It is not a leftover template comment, so keep it through later body edits.+- The `Closes #<issue>` line from the fork PR.+- Screenshots linked from the fork PR, not uploaded again.+- In Agent context: cherry-picked or squashed, and which commits are your follow-ups.++Do not add a `Co-authored-by` trailer.+The merge queue squash-merges, and GitHub adds a `Co-authored-by` line for every commit author other than the PR author.++When the new PR merges, the `Thank fork contributor` job in `.github/workflows/pr-closed.yml` reads the marker.+It comments on the fork PR with a link to the merged PR, then closes the fork PR.+Leave the fork PR open until then.diff --git a/.github/scripts/thank-fork-contributor.js b/.github/scripts/thank-fork-contributor.jsnew file mode 100644index 000000000000..466481351107--- /dev/null+++ b/.github/scripts/thank-fork-contributor.js@@ -0,0 +1,111 @@+// Runs through actions/github-script when a pull request merges. If its body+// carries the hidden marker that the recreating-fork-prs skill writes+// ("<!-- fork-pr: <n> @<login> -->"), it tells the contributor on fork PR #<n>+// where their change landed, then closes that PR.++const THANKS_MARKER = '<!-- fork-contribution-landed -->'+const FORK_PR_MARKER = /<!-- fork-pr: (\d+) @([A-Za-z0-9-]+) -->/+const HANDBOOK_URL = 'https://posthog.com/handbook/engineering/fork-pull-requests'++function parseContribution(body) {+ const match = FORK_PR_MARKER.exec(body || '')+ return match ? { forkPrNumber: Number(match[1]), login: match[2] } : null+}++function sameLogin(a, b) {+ return typeof a === 'string' && typeof b === 'string' && a.toLowerCase() === b.toLowerCase()+}++// The merged PR body is written by a maintainer, but a typo in the PR number+// must not post on someone else's pull request.+function skipReason(forkPr, login) {+ if (!forkPr) {+ return 'pull request not found'+ }+ if (!forkPr.isCrossRepository) {+ return 'not opened from a fork'+ }+ if (!sameLogin(forkPr.author?.login, login)) {+ return `opened by ${forkPr.author?.login}, not ${login}`+ }+ return null+}++function alreadyTold(forkPr) {+ return forkPr.comments.nodes.some((comment) => comment.body.includes(THANKS_MARKER))+}++function buildComment({ login, mergedPrNumber, credited }) {+ const coAuthor = credited ? ', with you as co-author' : ''+ return `${THANKS_MARKER}\nThank you for your contribution @${login}! Fork PRs can't run our backend CI, so we merged your change through #${mergedPrNumber}${coAuthor} ([why](${HANDBOOK_URL})).`+}++const MERGED_PR_QUERY = `query($owner: String!, $name: String!, $number: Int!) {+ repository(owner: $owner, name: $name) {+ pullRequest(number: $number) {+ body+ mergeCommit { authors(first: 50) { nodes { user { login } } } }+ }+ }+}`++const FORK_PR_QUERY = `query($owner: String!, $name: String!, $number: Int!) {+ repository(owner: $owner, name: $name) {+ pullRequest(number: $number) {+ state+ isCrossRepository+ author { login }+ comments(last: 100) { nodes { body } }+ }+ }+}`++async function fetchPullRequest(github, query, variables) {+ try {+ const data = await github.graphql(query, variables)+ return data.repository.pullRequest+ } catch (error) {+ // A number that names an issue or nothing at all is a typo in the PR body, not a job failure.+ if (error.errors?.every((entry) => entry.type === 'NOT_FOUND')) {+ return null+ }+ throw error+ }+}++module.exports = async ({ github, context, core }) => {+ const { owner, repo } = context.repo+ const mergedPrNumber = context.payload.pull_request.number++ const mergedPr = await fetchPullRequest(github, MERGED_PR_QUERY, { owner, name: repo, number: mergedPrNumber })+ const contribution = parseContribution(mergedPr.body)+ if (!contribution) {+ core.info(`#${mergedPrNumber} has no fork-pr marker`)+ return+ }+ const { login, forkPrNumber } = contribution++ const forkPr = await fetchPullRequest(github, FORK_PR_QUERY, { owner, name: repo, number: forkPrNumber })+ const reason = skipReason(forkPr, login)+ if (reason) {+ core.warning(`Skipping #${forkPrNumber}: ${reason}`)+ return+ }++ if (!alreadyTold(forkPr)) {+ const credited = mergedPr.mergeCommit.authors.nodes.some((author) => sameLogin(author.user?.login, login))+ const body = buildComment({ login, mergedPrNumber, credited })+ await github.rest.issues.createComment({ owner, repo, issue_number: forkPrNumber, body })+ core.info(`Told @${login} on #${forkPrNumber} (credited: ${credited})`)+ }+ if (forkPr.state === 'OPEN') {+ await github.rest.pulls.update({ owner, repo, pull_number: forkPrNumber, state: 'closed' })+ core.info(`Closed #${forkPrNumber}`)+ }+}++module.exports.THANKS_MARKER = THANKS_MARKER+module.exports.parseContribution = parseContribution+module.exports.skipReason = skipReason+module.exports.alreadyTold = alreadyTold+module.exports.buildComment = buildCommentdiff --git a/.github/scripts/thank-fork-contributor.test.js b/.github/scripts/thank-fork-contributor.test.jsnew file mode 100644index 000000000000..aadd0c7b2290--- /dev/null+++ b/.github/scripts/thank-fork-contributor.test.js@@ -0,0 +1,101 @@+// Run with: node --test .github/scripts/thank-fork-contributor.test.js++const test = require('node:test')+const assert = require('node:assert/strict')++const thankForkContributor = require('./thank-fork-contributor')+const { THANKS_MARKER, parseContribution, skipReason, buildComment } = thankForkContributor++const forkPr = (overrides = {}) => ({+ state: 'OPEN',+ isCrossRepository: true,+ author: { login: 'Jane-Doe' },+ comments: { nodes: [] },+ ...overrides,+})++const MERGED_PR = {+ body: '<!-- fork-pr: 1001 @Jane-Doe -->',+ mergeCommit: { authors: { nodes: [{ user: { login: 'Jane-Doe' } }] } },+}++function fakeGithub(forkPrResult) {+ const calls = []+ return {+ calls,+ graphql: async (query, { number }) => {+ if (number === 1001) {+ if (forkPrResult instanceof Error) {+ throw forkPrResult+ }+ return { repository: { pullRequest: forkPrResult } }+ }+ return { repository: { pullRequest: MERGED_PR } }+ },+ rest: {+ issues: { createComment: async (args) => calls.push(['comment', args.issue_number]) },+ pulls: { update: async (args) => calls.push(['close', args.pull_number]) },+ },+ }+}++const context = { repo: { owner: 'PostHog', repo: 'posthog' }, payload: { pull_request: { number: 1002 } } }+const core = { info: () => {}, warning: () => {} }++test.describe('thank-fork-contributor', () => {+ for (const [body, expected] of [+ [+ '## Problem\n\n<!-- fork-pr: 1001 @Jane-Doe -->\n- Contributed by @Jane-Doe in #1001.',+ { forkPrNumber: 1001, login: 'Jane-Doe' },+ ],+ ['- Contributed by @Jane-Doe in #1001, which cannot merge.', null],+ [null, null],+ ]) {+ test(`parseContribution(${JSON.stringify(body)})`, () => {+ assert.deepEqual(parseContribution(body), expected)+ })+ }++ for (const [name, pr, expected] of [+ ['fork PR by the contributor', forkPr(), null],+ ['login differs only in case', forkPr({ author: { login: 'jane-doe' } }), null],+ ['missing PR', null, 'pull request not found'],+ ['same-repo PR', forkPr({ isCrossRepository: false }), 'not opened from a fork'],+ ['fork PR by someone else', forkPr({ author: { login: 'someone' } }), 'opened by someone, not Jane-Doe'],+ ]) {+ test(`skipReason: ${name}`, () => {+ assert.equal(skipReason(pr, 'Jane-Doe'), expected)+ })+ }++ test('buildComment claims co-author credit only when GitHub gives it', () => {+ const args = { login: 'Jane-Doe', mergedPrNumber: 1002 }+ assert.match(buildComment({ ...args, credited: true }), /co-author/)+ assert.doesNotMatch(buildComment({ ...args, credited: false }), /co-author/)+ })++ const notFound = Object.assign(new Error('not found'), { errors: [{ type: 'NOT_FOUND' }] })+ for (const [name, forkPrResult, expectedCalls] of [+ [+ 'open fork PR gets a comment and is closed',+ forkPr(),+ [+ ['comment', 1001],+ ['close', 1001],+ ],+ ],+ [+ 'a rerun after a failed close only closes',+ forkPr({ comments: { nodes: [{ body: THANKS_MARKER }] } }),+ [['close', 1001]],+ ],+ ['a closed fork PR only gets the comment', forkPr({ state: 'CLOSED' }), [['comment', 1001]]],+ ['a PR number that does not exist is skipped', notFound, []],+ ]) {+ test(name, async () => {+ const github = fakeGithub(forkPrResult)+ await thankForkContributor({ github, context, core })+ assert.deepEqual(github.calls, expectedCalls)+ })+ }+})diff --git a/.github/workflows/pr-closed.yml b/.github/workflows/pr-closed.ymlindex e1f514386e26..9fbf6a961a8f 100644--- a/.github/workflows/pr-closed.yml+++ b/.github/workflows/pr-closed.yml@@ -55,6 +55,38 @@ jobs:}});+ thank-fork-contributor:+ name: Thank fork contributor+ runs-on: ubuntu-24.04+ timeout-minutes: 5+ if: >+ github.event.pull_request.head.repo.full_name == github.repository &&+ github.event.pull_request.merged == true &&+ contains(github.event.pull_request.body, '<!-- fork-pr: ')+ steps:+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2+ with:+ sparse-checkout: .github/scripts/thank-fork-contributor.js+ sparse-checkout-cone-mode: false++ - name: Get app token+ id: app-token+ uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1+ with:+ client-id: ${{ vars.GH_APP_POSTHOG_SCHEDULED_ACTIONS_APP_ID }}+ private-key: ${{ secrets.GH_APP_POSTHOG_SCHEDULED_ACTIONS_PRIVATE_KEY }}+ permission-issues: write+ permission-pull-requests: write++ - name: Thank the contributor on the fork PR+ uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0+ with:+ github-token: ${{ steps.app-token.outputs.token }}+ retries: 3+ script: |+ const thankForkContributor = require('./.github/scripts/thank-fork-contributor.js')+ await thankForkContributor({ github, context, core })+report-pr-age:name: Report age of PRruns-on: ubuntu-24.04diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex fd758202786b..0f2787448109 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -18,7 +18,7 @@ We welcome contributions. A few quick notes so you know how we operate:- The current week's [Support Hero](https://posthog.com/handbook/engineering/support-hero) for the owning team is usually the first point of contact, but customer support takes priority. Reviews can be delayed when support load is high.- Expect acknowledgement when we have bandwidth; thorough reviews may come later. It's fine if this takes a few days to a couple of weeks depending on load.- We sometimes close PRs that are out of scope, would add long-term maintenance burden, or go stale. You're always welcome to reopen with updates.-- Fork pull requests run backend CI on GitHub Actions; Depot's optional checks do not appear on them. See [Pull requests from forks](docs/published/handbook/engineering/fork-pull-requests.md).+- Fork pull requests get no backend CI run, so they cannot merge as they are. After review, a PostHog engineer re-creates the change on a branch in this repository. You stay the author of your commits, and the merged commit lists you as a co-author. See [Pull requests from forks](docs/published/handbook/engineering/fork-pull-requests.md).Before we do a full review, please:diff --git a/docs/published/handbook/engineering/fork-pull-requests.md b/docs/published/handbook/engineering/fork-pull-requests.mdindex d77be8480b57..8acae3a24236 100644--- a/docs/published/handbook/engineering/fork-pull-requests.md+++ b/docs/published/handbook/engineering/fork-pull-requests.md@@ -18,3 +18,8 @@ What a fork contributor sees:Never push a fork's head to a branch inside this repository before it is reviewed.An in-repo branch is trusted: every secret-gated step runs, with the fork's code in control of the job.Review the fork PR as it is, then re-create it in-repo.++Re-creating keeps the contributor's credit when their commits keep them as author.+The merge queue squash-merges, and GitHub adds a `Co-authored-by` line for each commit author, which counts on their profile when the email is linked to their account.+When the re-created PR merges, a bot comments on the fork PR with a link to the merged PR and closes it.+The [`recreating-fork-prs` skill](https://github.com/PostHog/posthog/blob/master/.agents/skills/recreating-fork-prs/SKILL.md) has the steps.