refactor: add resolve-cli action and migrate sync-openapi to composite

Add actions/resolve-cli — a shared composite action that resolves the
fern command based on a version input (auto/latest/inherit/specific).
Actions use its fern-cmd output instead of duplicating resolution logic.

Migrate sync-openapi from a Node.js action to a thin composite that
delegates to the Fern CLI (gha pull-spec / gha sync-specs). Remove the
now-dead src/, dist/, e2e/, and build config.

Add version input to generate, upgrade, and verify actions with
appropriate defaults (auto for generate/verify, latest for upgrade).

Restore setup-cli to a simple global installer with a version input.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Swimburger

actions/generate/action.yml

@@ -3,6 +3,10 @@ description: "[ALPHA] Runs fern generate on push to main and opens SDK PRs in SD
 author: "Fern"
 
 inputs:
+  version:
+    description: "Fern CLI version to use. 'auto' respects fern.config.json and falls back to latest, 'latest' always uses the newest release, 'inherit' uses the bootstrapped binary as-is, or pin to a specific version (e.g. '0.15.0')."
+    required: false
+    default: "auto"
   fern-token:
     description: "Fern token for API access and SDK repo PR creation"
     required: true

actions/resolve-cli/action.yml

@@ -0,0 +1,55 @@
+name: Resolve Fern CLI
+description: "Resolves the Fern CLI command based on the requested version. Outputs a fern-cmd string to use in subsequent steps."
+author: "Fern"
+
+inputs:
+  version:
+    description: "Fern CLI version to use. 'auto' respects fern.config.json and falls back to latest, 'latest' always uses the newest release, 'inherit' uses whatever CLI is already on PATH, or pin to a specific version or npm tag (e.g. '0.15.0', 'beta')."
+    required: false
+    default: "auto"
+
+outputs:
+  fern-cmd:
+    description: "The resolved fern command to use in subsequent steps."
+    value: ${{ steps.resolve.outputs.fern-cmd }}
+
+runs:
+  using: composite
+  steps:
+    - name: Set FERN_RUN_ID
+      shell: bash
+      run: |
+        if [ -z "${FERN_RUN_ID}" ]; then
+          FERN_RUN_ID=$(node -e "console.log(require('crypto').randomUUID())")
+          echo "FERN_RUN_ID=${FERN_RUN_ID}" >> "$GITHUB_ENV"
+          echo "Generated new FERN_RUN_ID: ${FERN_RUN_ID}"
+        else
+          echo "Inheriting existing FERN_RUN_ID: ${FERN_RUN_ID}"
+        fi
+
+    - name: Resolve Fern CLI version
+      id: resolve
+      shell: bash
+      env:
+        VERSION: ${{ inputs.version }}
+      run: |
+        #   auto    → npx fern-api@latest (let CLI resolve from fern.config.json)
+        #   latest  → npx fern-api@latest with FERN_NO_VERSION_REDIRECTION
+        #   inherit → bare `fern` from PATH with FERN_NO_VERSION_REDIRECTION
+        #   <other> → npx fern-api@<version> with FERN_NO_VERSION_REDIRECTION
+        if [ "$VERSION" = "auto" ]; then
+          FERN_CMD="npx --yes fern-api@latest"
+        elif [ "$VERSION" = "inherit" ]; then
+          if ! command -v fern &>/dev/null; then
+            echo "::error::version is 'inherit' but fern is not on PATH."
+            exit 1
+          fi
+          FERN_CMD="fern"
+          echo "FERN_NO_VERSION_REDIRECTION=true" >> "$GITHUB_ENV"
+        else
+          FERN_CMD="npx --yes fern-api@$VERSION"
+          echo "FERN_NO_VERSION_REDIRECTION=true" >> "$GITHUB_ENV"
+        fi
+
+        echo "fern-cmd=$FERN_CMD" >> "$GITHUB_OUTPUT"
+        echo "Resolved fern command: $FERN_CMD"

actions/setup-cli/action.yml

@@ -1,5 +1,5 @@
 name: Setup Fern CLI
-description: "Install the Fern CLI in your GitHub Actions workflow. Requires Node.js and npm — add actions/setup-node before this step if your runner doesn't include them."
+description: "Install the Fern CLI globally in your GitHub Actions workflow. Requires Node.js and npm — add actions/setup-node before this step if your runner doesn't include them."
 author: "Fern"
 
 branding:
@@ -8,7 +8,7 @@ branding:
 
 inputs:
   version:
-    description: "Fern CLI version to install. Use 'latest' to always get the newest release, or pin to a specific version (e.g. '0.15.0') for reproducible builds."
+    description: "Fern CLI version to install globally. Use 'latest' to get the newest release, or pin to a specific version or npm tag (e.g. '0.15.0', 'beta')."
     required: false
     default: "latest"
 
@@ -39,11 +39,11 @@ runs:
         VERSION: ${{ inputs.version }}
       run: |
         if ! command -v npm &>/dev/null; then
-          echo "Error: npm is not available. Please add a Node.js setup step before this action."
+          echo "::error::npm is not available. Please add a Node.js setup step before this action."
           exit 1
         fi
         if ! command -v node &>/dev/null; then
-          echo "Error: node is not available. Please add a Node.js setup step before this action."
+          echo "::error::node is not available. Please add a Node.js setup step before this action."
           exit 1
         fi
 

actions/sync-openapi/action.yml

@@ -3,11 +3,15 @@ description: "Keep your Fern config up to date — pull OpenAPI specs from a URL
 author: "Fern"
 
 inputs:
+  version:
+    description: "Fern CLI version to use. Use 'latest' to always get the newest release, a specific version (e.g. '0.15.0') for reproducible builds, or 'inherit' to use whatever CLI is already installed."
+    required: false
+    default: "latest"
   token:
     description: "GitHub token with contents: write and pull-requests: write on the target repository."
     required: true
   update_from_source:
-    description: "Set to 'true' to run 'fern api update' and pull the latest spec from the URL configured in generators.yml. Use this for Case 1 (public URL). Set to 'false' to sync files between repositories (Case 2)."
+    description: "Set to 'true' to run 'fern api pull' and fetch the latest spec from the URL configured in generators.yml. Set to 'false' to sync files between repositories."
     required: false
     default: "false"
   repository:
@@ -17,17 +21,45 @@ inputs:
     description: "YAML or JSON array of file/folder mappings to sync from this repo into the target repository. Each entry must have 'from' and 'to' fields (relative to repo roots), and an optional 'exclude' list of glob patterns. Only used when update_from_source is 'false'."
     required: false
   branch:
-    description: "Branch name to create or update in the target repository. Must be a stable name — do not use dynamic or timestamped names, or PR deduplication will break. Commits accumulate on this branch across runs."
+    description: "Branch name to create or update. Must be a stable name — do not use dynamic or timestamped names, or PR deduplication will break. Defaults to 'fern/pull-spec' for update_from_source mode and 'fern/sync-specs' for sync mode."
     required: false
-    default: "fern/sync-openapi"
   auto_merge:
-    description: "Set to 'true' to push directly to the branch without opening a PR. Set to 'false' to open a PR from the branch onto main. You must use 'true' when branch is 'main'."
+    description: "Set to 'true' to push directly to the branch without opening a PR. Set to 'false' to open a PR from the branch onto main."
     required: false
     default: "false"
 
 runs:
-  using: "node20"
-  main: "dist/index.js"
+  using: composite
+  steps:
+    - name: Resolve Fern CLI
+      id: cli
+      uses: fern-api/actions/resolve-cli@main
+      with:
+        version: ${{ inputs.version }}
+
+    - name: Pull spec from origin
+      if: inputs.update_from_source == 'true'
+      shell: bash
+      env:
+        FERN_TOKEN: ${{ inputs.token }}
+      run: |
+        ${{ steps.cli.outputs.fern-cmd }} gha pull-spec \
+          --token "${{ inputs.token }}" \
+          ${{ inputs.branch != '' && format('--branch "{0}"', inputs.branch) || '' }} \
+          ${{ inputs.auto_merge == 'true' && '--auto-merge' || '' }}
+
+    - name: Sync files to target repository
+      if: inputs.update_from_source != 'true'
+      shell: bash
+      env:
+        FERN_TOKEN: ${{ inputs.token }}
+      run: |
+        ${{ steps.cli.outputs.fern-cmd }} gha sync-specs \
+          --repository "${{ inputs.repository }}" \
+          --sources "${{ inputs.sources }}" \
+          --token "${{ inputs.token }}" \
+          ${{ inputs.branch != '' && format('--branch "{0}"', inputs.branch) || '' }} \
+          ${{ inputs.auto_merge == 'true' && '--auto-merge' || '' }}
 
 branding:
   icon: "refresh-cw"