docs: stack object in pull_request webhooks (#67)

* Initial plan

* Add CI integration guide documenting stack object in pull_request webhook events

Agent-Logs-Url: https://github.com/github/gh-stack/sessions/cf10db22-af0b-45c3-95d6-de9ef313d624

Co-authored-by: willsmythe <2503052+willsmythe@users.noreply.github.com>

* clean up webhooks content

* improve workflow code sample

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: willsmythe <2503052+willsmythe@users.noreply.github.com>
Co-authored-by: Sameen Karim <skarim@github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Author: 4 people

docs/astro.config.mjs

@@ -71,6 +71,7 @@ export default defineConfig({
 					label: 'Reference',
 					items: [
 						{ label: 'CLI Commands', slug: 'reference/cli' },
+						{ label: 'Webhooks', slug: 'reference/webhooks' },
 					],
 				},
 				{

docs/src/content/docs/faq.md

@@ -71,6 +71,35 @@ Every PR in a stack is treated as if it is targeting the **base of the stack** (
 
 GitHub Actions workflows trigger as if each PR in the stack is targeting the base of the stack (e.g., `main`). If you have a workflow configured to run on `pull_request` events targeting `main`, it will run for **every PR in the stack** — not just the bottom one.
 
+### How do I access stack metadata in my GitHub Actions workflow?
+
+For advanced use cases, you can access the stack's base ref and base SHA in workflow expressions via `github.event.pull_request.stack`. This property is only present when the PR belongs to a stack.
+
+```yaml
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Show stack info
+        if: github.event.pull_request.stack != null
+        run: |
+          echo "Stack base ref: ${{ github.event.pull_request.stack.base.ref }}"
+          echo "Stack base SHA: ${{ github.event.pull_request.stack.base.sha }}"
+
+      - name: Run a step only when the stack targets a release branch
+        if: github.event.pull_request.stack != null && startsWith(github.event.pull_request.stack.base.ref, 'release/')
+        run: echo "This stack targets a release branch"
+```
+
+| Expression | Description |
+|------------|-------------|
+| `github.event.pull_request.stack.base.ref` | The branch the entire stack ultimately targets (e.g., `main`). |
+| `github.event.pull_request.stack.base.sha` | The HEAD SHA of that target branch at the time of the event. |
+
+See the [Webhooks reference](/gh-stack/reference/webhooks/) for the full details on the `stack` object in webhook payloads.
+
 ### Do all previous PRs need to be passing checks before I can merge?
 
 Yes. In order to merge a PR in the stack, **all PRs below it** must also have passing checks and meet all merge requirements. For example, in a stack of `main <- PR1 <- PR2 <- PR3`, if you want to merge PR #3, both PR #1 and PR #2 must have passing checks, required reviews, and satisfy all branch protection rules.

docs/src/content/docs/reference/webhooks.md

@@ -0,0 +1,51 @@
+---
+title: Webhooks
+description: Reference for the stack object in pull_request webhook event payloads.
+---
+
+When a pull request belongs to a stack, GitHub adds a `stack` property to the `pull_request` object in webhook event payloads. This lets apps and integrations inspect the stack's ultimate target branch — not just the direct parent branch of the PR.
+
+The `stack` object is included in the `pull_request` webhook payload for all [pull request lifecycle events](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#pull_request).
+
+
+
+## The `stack` Object
+
+The `stack` object is nested inside the `pull_request` object and contains information about the stack's base branch:
+
+```json
+{
+  "action": "synchronize",
+  "pull_request": {
+    "number": 42,
+    "title": "Add API routes",
+    "base": {
+      "ref": "feat/auth-layer",
+      "sha": "abc123..."
+    },
+    "stack": {
+      "base": {
+        "ref": "main",
+        "sha": "def456..."
+      }
+    }
+  }
+}
+```
+
+### Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `pull_request.stack.base.ref` | `string` | The branch the entire stack ultimately targets (e.g., `main`). |
+| `pull_request.stack.base.sha` | `string` | The HEAD SHA of that target branch at the time of the event. |
+
+`pull_request.base.ref` is the direct parent branch of an individual PR (the branch below it in the stack), while `pull_request.stack.base.ref` is the ultimate target of the entire stack. These differ for all PRs in the stack except the bottom one.
+
+The `stack` object is **only present** when the pull request belongs to a stack. For standalone PRs, the field is null.
+
+## GitHub Actions
+
+GitHub Actions automatically evaluates workflow triggers using the stack's base branch. If a PR is part of a stack targeting `main`, any workflow configured to run on pull requests targeting `main` will run for every PR in the stack — no workflow changes are required.
+
+The `stack` object is also available in GitHub Actions workflow expressions via `github.event.pull_request.stack`. See [How do I access stack metadata in my GitHub Actions workflow?](/gh-stack/faq/#how-do-i-access-stack-metadata-in-my-github-actions-workflow) in the FAQ for examples.