Migrating to Replay

This guide migrates an SDK from release or push output mode to pull-request output mode — the mode required to enable Fern Replay. Only follow it if your SDK is currently on release or push mode and you want to switch in order to use Replay. SDKs already using pull-request mode have Replay on by default; no migration is needed.

What changes

• SDK updates arrive as PRs instead of direct pushes to main.
• Customizations to generated code survive regeneration via 3-way merge.
• Version bumps are computed from pure generator output, never contaminated by customizations.
• Publishing is decoupled from generation, so you control when to release.

Before you start

• Install the Fern GitHub App on your SDK repositories.
• Update to the latest Fern CLI: fern upgrade.
• Update to the latest SDK generator versions: fern generator upgrade.

Phase 1: Move publishing secrets to the SDK repo

Fern sets GitHub Actions secrets in your SDK repo on every generation. When you switch to pull-request output mode, that write would clobber any secrets you set directly. To avoid this, move secret ownership from the config repo to the SDK repo before flipping modes.

For each SDK repo:

1
# BEFORE
2
groups:
3
  python-sdk:
4
    generators:
5
      - name: fernapi/fern-python-sdk
6
        version: "..."
7
        github:
8
          repository: customer/python-sdk
9
          mode: pull-request
10
        output:
11
          pypi:
12
            username: $PYPI_USERNAME
13
            password: $PYPI_PASSWORD
14
15
# AFTER (remove the output/pypi block entirely)
16
groups:
17
  python-sdk:
18
    generators:
19
      - name: fernapi/fern-python-sdk
20
        version: "..."
21
        github:
22
          repository: customer/python-sdk
23
          mode: pull-request

Phase 2: Switch output mode

In generators.yml:

1
github:
2
  repository: customer/python-sdk
3
  mode: pull-request   # was: mode: release   (or: mode: push)

If you use version: AUTO, no other changes are needed. Autoversioning runs as part of the generator-cli pipeline and diffs pure generator output, so customer customizations never contaminate the version diff.

Phase 3: Decouple publishing from generation (optional)

To control publishing on your own schedule rather than on every Fern generation, keep your publish workflow out of Fern’s generation cycle:

.github/workflows/ci.yml

1
# Instead of:
2
on:
3
  push:
4
    branches: [main]
5
6
# Use:
7
on:
8
  workflow_dispatch:
9
  release:
10
    types: [published]

Phase 4: First generation with Replay

Phase 5: Validate

After the first generation and merge, confirm the following:

• A PR was created (not a direct push to main).
• No unintended package release was triggered.
• SDK code is correct and passes CI.
• .fern/replay.lock exists in the SDK repo.
• .fernignore contains replay.lock (and replay.yml).

After your first real customization, verify Replay’s behavior end-to-end:

• You edit a generated file, commit, and merge to main.
• The next fern generate detects the patch (PR body shows patches detected: 1).
• The customization survives regeneration via a clean 3-way merge.
• .fern/replay.lock shows the patch stored.

Rollback

Replay never modifies files destructively. Your main branch always has correct code, so rolling back is straightforward.

Quick disable. To stop Replay while staying in pull-request mode, set replay.enabled: false in your generators.yml (see the replay reference). The next fern generate skips the patch detection and application phase; PRs land in the same shape as before, just without the [fern-replay] commit.

Full revert to release or push mode:

1
github:
2
  repository: customer/python-sdk
3
  mode: release   # or mode: push

Troubleshooting

Known caveats

• Closed-without-merge replay PRs. If a replay PR is closed without merging, the next generation re-derives its anchor from the current branch history. No manual cleanup needed.
• Force pushes and rewritten history. Replay re-derives its scan anchor from git log on every run, so force-pushed branches continue to work and existing patches still apply correctly.