feat(upgrade): implement fern automations upgrade action

[lifanzou]

Summary

Rewrites the upgrade action as a standard Node.js action that consumes fern automations upgrade --json output from the CLI. The CLI provides all domain logic (version diffing, changelog URLs, PR formatting via the pr field), so the action is pure glue: run CLI → push → create/manage PR.

Architecture:

• run-upgrade.ts: Uses @actions/exec.getExecOutput() to run the CLI, capturing stdout (JSON) and stderr (logs) separately. Timeout via Promise.race — no manual process lifecycle management needed. Parsing/validation extracted into parseUpgradeOutput() for direct unit testing.
• manage-pr.ts: Clean-slate branch model: each run resets fern/upgrade to origin/<default>, applies upgrade, force-pushes. Guards that fern/ exists before proceeding. Temp directory cleanup in try/finally. Uses --force (not --force-with-lease) because the local branch has no tracking ref.
• index.ts: Shared instrumentAction/runAction/runPostCleanup patterns matching generate, preview, verify. Validates githubToken early. Warns if CLI reports upgrades but no file changes detected (possible copy/staging bug).

Key design decisions:

• @actions/exec over raw spawn: Eliminates timeout race conditions and interval leaks. getExecOutput() handles process lifecycle and stdio routing — timeout is a simple Promise.race.
• --force push: The local branch is freshly created each run with no tracking ref. --force-with-lease would reject because there's no reflog to compare against.
• version: "latest" (not "auto"): Intentional — the upgrade action should always use the newest CLI release, regardless of fern.config.json. Differs from generate which uses "auto".

Test coverage (12 tests):

• 10 behavioral tests for parseUpgradeOutput: valid JSON, whitespace, empty stdout, invalid JSON, truncated JSON, missing cli, missing generators, non-array generators, pr: null
• 2 pr sub-field validation tests: missing fields, empty title

Review & Testing Checklist for Human

• Verify @actions/exec.getExecOutput() captures stdout/stderr correctly in a real GHA run
• Verify Promise.race timeout behaves correctly (process killed on timeout, no leaks)
• E2E: trigger upgrade workflow on a test repo and verify PR is created with correct title/body/commit
• Verify githubToken validation fires early with a clear error when token is missing

Notes

• Requires fern-api/fern#15771 (already merged, published as v5.19.0)
• E2E validated: fern-demo/sdk-preview-test-config#3 was successfully created by the action

Link to Devin session: https://app.devin.ai/sessions/0b0ff224ce294b938ff5c2f5aec943fd

---

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 11 additional findings in Devin Review.

[devin-ai-integration]

🟡 Shell glob * silently skips dotfiles when restoring upgraded fern config

On line 144, cp -r "$UPGRADE_TMP/fern/"* fern/ uses a shell glob that does not match dotfiles (files starting with .) by default in bash. The preceding cp -r fern/ "$UPGRADE_TMP/fern" on line 137 copies ALL files (including dotfiles) from the upgraded state. After switching to the clean branch, only non-dotfile entries are restored. If fern automations upgrade ever creates or modifies a dotfile at the top level of the fern/ directory (e.g., .fernignore), those changes would be silently lost in the PR.

Fix options

Either enable dotglob before the copy:

shopt -s dotglob
cp -r "$UPGRADE_TMP/fern/"* fern/
shopt -u dotglob

Or use rsync/find-based copy that includes hidden files:

cp -a "$UPGRADE_TMP/fern/." fern/

Suggested change

	cp -r "$UPGRADE_TMP/fern/"* fern/
	cp -a "$UPGRADE_TMP/fern/." fern/

---

Was this helpful? React with 👍 or 👎 to provide feedback.