This walkthrough configures an existing GitHub fork. You need Node.js 22+, git, and an authenticated gh CLI.
Already using an earlier Patchlane version? Follow the migration guide instead.
Patchlane's generated workflows push as a GitHub App so pushes to sync/integration and the promoted base branch trigger their configured workflows. GitHub suppresses most workflow events caused by the built-in GITHUB_TOKEN, so granting that token contents: write is not sufficient. Adapted workflows may use another token source that satisfies the contract in Workflow authentication.
Create or reuse a GitHub App, install it on the fork, and grant these repository permissions:
- Contents: read and write
- Workflows: write
- Issues: read and write only when GitHub issue notifications are enabled
The App does not need Actions write permission. Disable webhooks unless the App has another use that requires them. Record its Client ID and generate a private key, then configure the repository without printing the private key:
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.pemThe generated workflows use actions/create-github-app-token to request only the permissions needed by each job. Token creation fails if the App is not installed on the fork or lacks a requested permission.
Add the upstream remote if needed:
git remote add upstream https://github.com/UPSTREAM_OWNER/UPSTREAM_REPO.gitFor the latest stable release:
UPSTREAM=UPSTREAM_OWNER/UPSTREAM_REPO
SOURCE=release:latest
SOURCE_REF=$(gh release view --repo "$UPSTREAM" --json tagName --jq .tagName)
git fetch upstream --tagsTo track a branch instead:
UPSTREAM=UPSTREAM_OWNER/UPSTREAM_REPO
SOURCE=branch:main
SOURCE_REF=upstream/main
git fetch upstream mainKeep SOURCE_REF unchanged for the remaining steps. Every patch branch must start independently from this commit.
Find the exact name: of the existing CI workflow, then create patch/sync:
git switch -c patch/sync "$SOURCE_REF"
npx patchlane init \
--upstream="$UPSTREAM" \
--source="$SOURCE" \
--patch-refs="patch/sync,patch/ci" \
--ci-workflow="CI"
git add .patchlane.yml .github/workflows
git commit -m "Add Patchlane sync automation"
git push -u origin patch/syncReplace CI with the existing workflow's exact name. Do not rename the workflow just for Patchlane.
Create patch/ci from the same source—not from patch/sync:
git switch -c patch/ci "$SOURCE_REF"Update the existing CI workflow so its push branches include both generated branches:
on:
pull_request:
push:
branches:
- main
- sync/integrationCommit and push only that CI adjustment:
git add .github/workflows
git commit -m "Run fork CI on Patchlane syncs"
git push -u origin patch/ciReturn to the branch containing .patchlane.yml:
git switch patch/sync
npx patchlane doctor
npx patchlane sync --dry-rundoctor should have no errors. It checks the generated App-token wiring and, when your local gh credentials permit it, confirms that Actions is enabled and the expected repository variable and secret exist. GitHub does not expose secret values, so this cannot prove that the uploaded private key is valid. A bootstrap warning is expected because the workflows are not on the generated base branch yet.
Validate once more without publishing:
npx patchlane bootstrapThen publish, wait for CI, and promote the exact successful SHA:
npx patchlane bootstrap --waitAfter bootstrap, scheduled syncs and automatic promotions are active. 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.
Once the configured composition is valid, agents should work from a complete workspace rather than a raw patch branch:
npx patchlane workspace create --lane patch/product
cd ../REPOSITORY-patch-product
npx patchlane workspace status --jsonMake and test linear commits in the generated worktree. Before landing, validate the projection and exact recomposition:
npx patchlane workspace land --dry-run
npx patchlane workspace landUse --push only with explicit approval. A stale lane, projection conflict, or round-trip mismatch leaves configured lane refs unchanged and should be resolved rather than bypassed.
Create each additional patch independently from the same selected source:
git switch -c patch/product "$SOURCE_REF"
# Make and commit the fork-owned product changes.
git push -u origin patch/productAdd it to patchRefs in .patchlane.yml, usually after patch/sync and patch/ci, then update patch/sync and run doctor plus sync --dry-run again.