document github orchestration actions

fern/products/docs/docs.yml

@@ -251,6 +251,8 @@ navigation:
   - section: Developer tools
     collapsed: true
     contents:
+      - page: Orchestrate GitHub releases
+        path: ./pages/developer-tools/orchestrate-docs-releases.mdx
       - page: Cursor
         path: ./pages/developer-tools/cursor.mdx
       - page: GitLab

fern/products/docs/pages/developer-tools/orchestrate-docs-releases.mdx

@@ -0,0 +1,99 @@
+---
+title: Orchestrate releases
+description: Coordinate documentation updates across multiple repositories and releases.
+---
+
+Fern Docs supports orchestrating documentation releases based on releases from other repositories. This is useful when documenting features that depend on releases in other repositories.
+
+This requires two GitHub Actions: one in the feature repository and one in the documentation repository.
+
+<Steps>
+<Step title="Set up release notification in the feature repository">
+
+Add this GitHub Action workflow to the repository where features are released. When a new release is created with the specified tag pattern, this workflow will send a notification to your documentation repository, triggering the auto-merge process.
+
+Replace the following placeholders with your own values:
+- `<GITHUB_ACCESS_TOKEN>`: GitHub token with `repo` scope
+- `<ORG>`: Organization containing the docs repository
+- `<DOCS_REPO>`: Docs repository name
+- `<PRODUCT_RELEASE_TAG>`: Product release tag
+
+```yml title=".github/workflows/notify-docs-repo.yml"
+name: Notify Docs Repo
+on:
+  release:
+    types: [created]
+    tags:
+      - "<PRODUCT_RELEASE_TAG>@*"
+
+jobs:
+  notify-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger docs repo workflow
+        run: |
+          curl -f -X POST \
+            -H "Accept: application/vnd.github.v3+json" \
+            -H "Authorization: token ${{ secrets.<GITHUB_ACCESS_TOKEN> }}" \
+            https://api.github.com/repos/<ORG>/<DOCS_REPO>/dispatches \
+            -d '{"event_type":"<PRODUCT_RELEASE_TAG>","client_payload":{"version":"${{ github.ref_name }}"}}'
+```
+
+</Step>
+<Step title="Configure auto-merge in the documentation repository">
+
+Add this GitHub Action workflow to your documentation repository to auto-merge PRs when features are released. Replace `<PRODUCT_RELEASE_TAG>` with your product release tag.
+
+```yml title=".github/workflows/auto-merge-on-release.yml"
+name: Auto-merge on Docs Release
+on:
+  repository_dispatch:
+    types: [<PRODUCT_RELEASE_TAG>]
+
+jobs:
+  merge-dependent-prs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Find and merge dependent PRs
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const version = context.payload.client_payload.version;
+
+            // Find PRs with matching labels
+            const { data: prs } = await github.rest.pulls.list({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              state: 'open'
+            });
+
+            for (const pr of prs) {
+              const labels = pr.labels.map(l => l.name);
+              const hasLatestLabel = labels.includes('depends-on: <PRODUCT_RELEASE_TAG>@latest');
+              const hasVersionLabel = labels.includes(`depends-on: <PRODUCT_RELEASE_TAG>@${version}`);
+
+              if (hasLatestLabel || hasVersionLabel) {
+                // Check if PR is approved
+                const { data: reviews } = await github.rest.pulls.listReviews({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  pull_number: pr.number
+                });
+
+                const approved = reviews.some(r => r.state === 'APPROVED');
+
+                if (approved) {
+                  await github.rest.pulls.merge({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    pull_number: pr.number,
+                    merge_method: 'squash'
+                  });
+
+                  console.log(`Merged PR #${pr.number}: ${pr.title}`);
+                }
+              }
+            }
+```
+</Step>
+</Steps>