Skip to content

: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.

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.md
index 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.md
index 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.md
new file mode 100644
index 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.js
new file mode 100644
index 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 = buildComment
diff --git a/.github/scripts/thank-fork-contributor.test.js b/.github/scripts/thank-fork-contributor.test.js
new file mode 100644
index 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.yml
index 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 PR
runs-on: ubuntu-24.04
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 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.md
index 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.