Skip to content

Latest commit

 

History

History
183 lines (126 loc) · 9.31 KB

migrations.md

File metadata and controls

183 lines (126 loc) · 9.31 KB

Patchlane Migration Guide

Follow the section for the version you are adopting. Migration notes are listed newest first.

0.5

Patchlane 0.5 requires every version-1 .patchlane.yml file to define allowedWorkflows and updates generated workflows to authenticate with a GitHub App. Patchlane implicitly includes its generated sync-upstream.yml and promote-tested-sync.yml workflows, so list only repository-specific workflows.

1. Inventory the composed workflow tree

Inspect the workflows on the current generated base branch and review the configured patch branches for workflow additions or deletions:

git fetch origin
git ls-tree -r --name-only origin/main -- .github/workflows

Decide which workflows should remain after Patchlane composes the upstream source and every configured patch. Include CI, documentation, maintenance, and local reusable workflows only when they are intentionally retained. Every target referenced through uses: ./.github/workflows/<file> must also be present and allowed.

Do not add these generated workflows explicitly; Patchlane allows and requires them automatically:

  • sync-upstream.yml
  • promote-tested-sync.yml

2. Add the required allowlist

Update .patchlane.yml on the patch branch that owns Patchlane configuration, normally patch/sync:

version: 1
upstream: upstream-org/upstream-repo
source: release:latest
baseBranch: main
syncBranch: sync/integration
patchRefs:
    - patch/sync
    - patch/ci
    - patch/product
ciWorkflow: CI
allowedWorkflows:
    - ci.yml

Use allowedWorkflows: [] when the composed tree should contain only Patchlane's generated workflows. Add patches that delete unwanted upstream workflows rather than allowing them merely because they currently exist.

3. Choose workflow authentication

Inspect the existing workflows and choose how the fork should authenticate before replacing or adapting them. The token must be able to push repository contents, update workflow files, and start downstream workflows. Enable issue access when GitHub issue notifications are configured. Do not use github.token or secrets.GITHUB_TOKEN: pushes made by the built-in GITHUB_TOKEN do not start the required downstream workflow runs.

The latest 0.5 workflows use actions/create-github-app-token. For this default, create or reuse a GitHub App installed on the fork with Contents read/write and Workflows write, plus Issues read/write when notifications are enabled. Configure its credentials using the standard names:

FORK=OWNER/REPOSITORY
gh variable set PATCHLANE_APP_CLIENT_ID --repo "$FORK" --body "YOUR_APP_CLIENT_ID"
gh secret set PATCHLANE_APP_PRIVATE_KEY --repo "$FORK" < /path/to/app-private-key.pem

Alternatively, preserve an established authentication source or use another source selected by the maintainer. Patchlane accepts a token exposed by an action or run step as ${{ steps.<id>.outputs.<name> }}, or a suitable App or user token stored as ${{ secrets.<name> }}. Checkout and every Patchlane command in the job must use the exact same expression. Keep the selected source's existing inputs and secret names; do not request a client ID or duplicate private-key secret unless that source requires them.

Update both workflow files to the latest 0.5 structure without overwriting the selected authentication implementation. Doctor validates custom token wiring but cannot inspect how the token is created or which capabilities it has. Confirm the selected authentication with the first workflow-driven published sync, including the downstream CI run and promotion.

4. Validate before rollout

After pushing the updated patch refs, validate with Patchlane 0.5:

npx patchlane@0.5 doctor
npx patchlane@0.5 sync --dry-run

Doctor should identify every unexpected or missing workflow by filename. The dry run validates the actual output after all configured patches are replayed without changing the local or remote sync branch.

5. Roll out through a tested promotion

Update the Patchlane version selector in the sync and promotion workflows as part of the same configuration patch. From that patch branch, use the latest 0.5 client for the first policy-enforced rebuild and promotion:

npx patchlane@0.5 bootstrap --wait

This validates the allowlist before publishing sync/integration, waits for CI on the exact published SHA, revalidates that SHA, and then promotes it. Confirm afterward that the generated base contains the intended workflow set and that scheduled syncs use the new Patchlane version. On the first workflow-driven sync that publishes a new integration SHA, confirm that authentication succeeds, CI runs as a push for that SHA, and promotion updates the base branch.

6. Optionally enable maintainer notifications

Failure notifications are opt-in. Existing configurations that omit notifications keep their current behavior and require no notification-specific migration.

To enable notifications, add the provider configuration to the patch branch that owns .patchlane.yml:

notifications:
    githubIssues:
        assignees:
            - maintainer
        labels:
            - patchlane
            - automation-failure
        events:
            - sync-failed
            - ci-failed
            - promotion-failed
        closeOnRecovery: true

Update both generated workflow files from the 0.5 templates in the same patch:

  • sync-upstream.yml must request permission-issues: write for its App token, report sync-failed after a failed sync, and optionally report recovery after success.
  • promote-tested-sync.yml must request permission-issues: write in jobs that report issues, report unsuccessful CI workflow runs, report failed promotions, and optionally report each recovery.

Do not add only the configuration block: existing workflow files do not invoke patchlane notify, and patchlane doctor reports missing issues: write permissions. Keep notification steps on continue-on-error so a GitHub API or assignment failure cannot replace the original automation result.

Run doctor, then roll the configuration and workflow changes forward through bootstrap --wait as described above. Confirm that configured labels exist and that each assignee can be assigned to issues in the fork.

0.4

Existing Patchlane forks can migrate without rebuilding their patch strategy or interrupting scheduled syncs. Legacy workflow environment variables remain supported, so migration can be rolled out through the existing sync and promotion flow.

1. Translate the existing workflow configuration

Read the current sync workflow and map its environment variables into .patchlane.yml:

Legacy environment variable .patchlane.yml field
UPSTREAM_OWNER and UPSTREAM_REPO upstream: owner/repo
Non-empty RELEASE_SELECTOR source: release:<selector>
Blank RELEASE_SELECTOR plus UPSTREAM_REF source: branch:<ref>
BASE_BRANCH baseBranch
SYNC_BRANCH syncBranch
PATCH_REFS patchRefs
Promotion workflow's workflow_run.workflows value ciWorkflow

For example:

version: 1
upstream: upstream-org/upstream-repo
source: release:latest
baseBranch: main
syncBranch: sync/integration
patchRefs:
    - patch/sync
    - patch/ci
    - patch/product
ciWorkflow: CI

Do not infer the source from the checked-out branch or a version file. Preserve the source behavior already configured in the workflow unless you intentionally want to change it.

2. Update patch/sync

Add .patchlane.yml to the existing patch/sync branch. Adapt the new generated sync and promotion workflows while preserving:

  • existing branch names and patch order
  • the exact existing CI workflow name
  • repository-specific schedules and workflow conventions
  • any intentional workflow-dispatch inputs

Avoid patchlane init --force for migration unless replacing the existing workflows is intentional. Incremental edits are easier to review and preserve local customization.

Commit and push the updated patch/sync branch.

3. Validate before rollout

From patch/sync, run:

npx patchlane@0.4 doctor
npx patchlane@0.4 sync --dry-run

doctor should resolve the same upstream source and patch order as the legacy workflow. Review every warning before publishing.

4. Roll the config onto the generated base

If the existing sync and promotion workflows are already active on the generated base, trigger the existing sync workflow. Its legacy environment variables remain compatible with Patchlane 0.4, and the resulting tested promotion will place .patchlane.yml and the updated workflows on the base branch.

If the promotion workflow is not yet present on the base branch, use the explicit bootstrap flow instead:

npx patchlane@0.4 bootstrap
npx patchlane@0.4 bootstrap --wait

After promotion, confirm that scheduled syncs load their defaults from .patchlane.yml. Legacy environment variables may remain temporarily as per-run overrides, but remove duplicated committed values once the config-backed workflow is active.