feat(upgrade): implement fern-upgrade GitHub Action

Implements end-to-end fern-upgrade action that automates Fern CLI and
generator version upgrades. Runs `fern upgrade` and `fern generator
upgrade`, detects changes by diffing config files before/after, and
opens or updates a shared PR on the `fern/upgrade` branch.

- Add version-diff module for parsing fern.config.json and generators.yml
- Add PR management with clean-slate branch strategy (force push)
- Add PR title/body generation with changelog links from FDR
- Add github-token input with default GITHUB_TOKEN fallback
- Add CLI version resolution (auto/latest/inherit/specific)
- Stub telemetry (FER-9668) and automation config (FER-9669) as TODOs

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: 2 people

actions/upgrade/README.md

@@ -0,0 +1,74 @@
+# upgrade
+
+**[ALPHA]** Automatically upgrades Fern CLI and generator versions and opens or updates a pull request with the changes.
+
+## How it works
+
+1. Resolves and runs the Fern CLI based on the `version` input
+2. Runs `fern upgrade --yes` to bump the CLI version in `fern.config.json`
+3. Runs `fern generator upgrade --yes` to bump generator versions in `generators.yml`
+4. Detects what changed by comparing config files before and after
+5. If changes were detected, pushes to the `fern/upgrade` branch and creates or updates a PR
+
+The action uses a **single open PR model** — if a PR already exists on the `fern/upgrade` branch, it updates the PR title and body. Each run resets the branch to the latest default branch HEAD (clean slate).
+
+## Usage
+
+```yaml
+name: Fern Upgrade
+on:
+  schedule:
+    - cron: '0 6 * * *'   # Daily at 6am UTC
+  workflow_dispatch: {}     # Manual trigger + registry webhook support
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: fern-upgrade
+  cancel-in-progress: false
+
+jobs:
+  upgrade:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: fern-api/fern-github-actions/actions/upgrade@v1
+        with:
+          fern-token: ${{ secrets.FERN_TOKEN }}
+```
+
+> **Important:** The `concurrency` block is strongly recommended to prevent race conditions if multiple upgrade runs are triggered simultaneously.
+
+## Inputs
+
+| Input | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `version` | No | `latest` | Fern CLI version to use. `auto` respects `fern.config.json`, `latest` always uses newest, `inherit` uses CLI from PATH, or pin a specific version. |
+| `fern-token` | **Yes** | — | Fern authentication token |
+| `github-token` | No | `${{ github.token }}` | GitHub token for PR creation and push access |
+
+## Outputs
+
+| Output | Description |
+|--------|-------------|
+| `run-id` | UUIDv4 for this upgrade run |
+| `pr-url` | URL of the created or updated PR (empty if no changes) |
+| `cli-upgraded` | `true` or `false` — whether the CLI version was bumped |
+| `generators-upgraded` | JSON array of `{generator, from, to}` for each upgraded generator |
+
+## PR format
+
+**Title:** `chore: upgrade fern (0.25.0 → 0.30.0) and generators`
+
+**Body** includes:
+- CLI version change
+- Generator version table with changelog links
+- Links to generator changelogs on [buildwithfern.com](https://buildwithfern.com)
+
+## Permissions
+
+The workflow requires:
+- `contents: write` — to push the `fern/upgrade` branch
+- `pull-requests: write` — to create and update PRs

actions/upgrade/action.yml

@@ -8,19 +8,27 @@ inputs:
     required: false
     default: "latest"
   fern-token:
-    description: "Fern token for API access and PR creation"
+    description: "Fern token for API access and CLI authentication"
     required: true
+  github-token:
+    description: "GitHub token for PR creation and push access. Falls back to default GITHUB_TOKEN."
+    required: false
+    default: ${{ github.token }}
 
 outputs:
   run-id:
     description: "UUIDv4 for this upgrade run"
   pr-url:
     description: "URL of the created or updated upgrade PR (empty if no changes)"
   cli-upgraded:
-    description: "Whether the Fern CLI version was upgraded"
+    description: "Whether the Fern CLI version was upgraded (true/false)"
   generators-upgraded:
     description: "JSON array of {generator, from, to} for each upgraded generator"
 
 runs:
   using: "node20"
   main: "dist/index.js"
+
+branding:
+  icon: "refresh-cw"
+  color: "green"