From e8d98808d4edea788f8e2d855a69b9cdb193f637 Mon Sep 17 00:00:00 2001
From: jonnii <me@jonnii.com>
Date: Sun, 10 May 2026 18:19:52 -0400
Subject: [PATCH] docs: align github integration page with real workflow
 template

The GitHub integration docs showed a fabricated workflow that installed
stackit from a non-existent https://get.stackit.dev URL and ran
stackit github check-lock / check-order commands that don't exist. The
real template installed by 'stackit github install' uses inline git+jq
to read metadata refs directly with no stackit binary required.

Describe what the real workflow does, point readers at the installed
file, and fix the troubleshooting steps to use commands that exist.
---
 doc/src/integrations/github.md | 53 +++++++---------------------------
 1 file changed, 11 insertions(+), 42 deletions(-)

diff --git a/doc/src/integrations/github.md b/doc/src/integrations/github.md
index 3bb761a0..e6fccf89 100644
--- a/doc/src/integrations/github.md
+++ b/doc/src/integrations/github.md
@@ -56,49 +56,20 @@ This prevents accidentally merging branches that are still being worked on or co
 
 ### Stack Order Check
 
-The action verifies that the PR is at the bottom of its stack:
+The action verifies that the PR is at the bottom of its stack. A branch is considered ready to merge when its parent is the trunk (e.g. `main`).
 
-```
-✓ Stack order check passed - PR is ready to merge
-```
-
-If there are PRs below this one in the stack:
-
-```
-✗ Stack order check failed - merge PR #42 first
-```
+If the PR is not at the bottom of the stack, the check fails with a message naming the parent branch that must merge first.
 
 This ensures stacked PRs are merged in order, maintaining clean git history.
 
 ## Workflow File
 
-The installed workflow looks like:
-
-```yaml
-name: Stackit Checks
+The installed workflow reads the stackit metadata refs directly with `git` and `jq` — no separate stackit installation is required on the runner. The two jobs are:
 
-on:
-  pull_request:
-    types: [opened, synchronize, reopened]
+- **check-lock** — fails if the branch's metadata has `lockReason` set
+- **check-stack-order** — fails if the branch's parent is not the trunk
 
-jobs:
-  stackit-checks:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Install stackit
-        run: |
-          curl -fsSL https://get.stackit.dev | bash
-
-      - name: Run lock check
-        run: stackit github check-lock
-
-      - name: Run stack order check
-        run: stackit github check-order
-```
+See `.github/workflows/stackit.yml` after running `stackit github install` for the full template.
 
 ## Customization
 
@@ -136,16 +107,14 @@ You can make either check required or optional:
 
 ### Check Failing Unexpectedly
 
-1. View the check details in the PR
-2. Run the check locally:
+1. View the check details in the PR — the inline shell script logs which condition failed and why
+2. Check branch metadata locally:
    ```bash
-   stackit github check-lock
-   stackit github check-order
+   stackit info
    ```
-
-3. Check branch metadata:
+3. View the raw metadata ref:
    ```bash
-   stackit info
+   git show "refs/stackit/metadata/$(git branch --show-current)"
    ```
 
 ## Combining with Local Hooks