Skip to main content

F8 — GitHub App setup

F8 is the Swiftpatch AI PR agent. Given a crash cluster in the dashboard, F8 analyzes the root cause and opens a draft pull request in your GitHub repo with a suggested fix. You review, tweak, and merge — or close if the fix isn't right.

This guide walks you through the one-time setup.

Prerequisites​

  • A repository on GitHub you have admin access to.
  • A Swiftpatch organization with F8 enabled (contact sales@swiftpatch.io to opt in).
  • The Swiftpatch CLI installed.

1. Install the Swiftpatch GitHub App​

From the dashboard:

  1. Go to Settings → Integrations → GitHub.
  2. Click Install GitHub App.
  3. You'll be redirected to GitHub. Pick the organization (or personal account) that owns the repo.
  4. Grant the app access to:
    • All repositories, or
    • Only select repositories — pick the repos you want F8 to open PRs in.
  5. The required permissions:
    • Contents: Read + write (to create branches and commits).
    • Pull requests: Read + write (to open draft PRs).
    • Metadata: Read (always required).

You'll land back on the Swiftpatch dashboard with a green "Connected" badge.

Each Swiftpatch app maps to one GitHub repo. Link them from the dashboard:

  1. Go to Apps → <your-app> → Settings → Repository.
  2. Pick the GitHub repo from the dropdown. Only repos the GitHub App has access to appear here.
  3. Set the default base branch for PRs (typically main or develop).

You can change the base branch per PR at swiftpatch pr <clusterId> --base feature-branch.

3. Open your first PR​

Find a crash cluster in the dashboard. Copy its clusterId (or use the CLI to list them):

swiftpatch ai crashes --app my-app

Then run:

swiftpatch pr crash_abc123

You'll see:

PR opened: https://github.com/your-org/your-repo/pull/42
Branch      : swiftpatch/fix/abc12345
PR number   : #42
Files       : src/reducers/user.ts, src/components/ProfileHeader.tsx
Commit      : a3f71c9b12

The PR is opened as a draft — it won't trigger CI notifications or reviewer pings until you convert it to ready.

What F8 does​

Given a crash cluster, F8:

  1. Fetches the cluster analysis from the Swiftpatch API (root cause + suggested fix diff).
  2. Via the GitHub App, creates a branch named swiftpatch/fix/<shortHash> from the base branch.
  3. Applies the diff to the branch.
  4. Commits with message auto-fix: <rootCause> and a Swiftpatch-Cluster: <clusterId> trailer.
  5. Opens a draft PR with:
    • Title: Swiftpatch AI fix: <rootCause>.
    • Body: fix summary, affected files, cluster link, confidence score.
    • Label: swiftpatch-ai (if configured).

Guardrails​

F8 has bounded authority by design:

  • File denylist — never touches lockfiles (package-lock.json, yarn.lock, Podfile.lock), CI configs (.github/workflows/*), secret-adjacent paths.
  • Max 500 lines changed per PR. Larger diffs are rejected with a message asking you to open a manual PR.
  • Max 10 PRs per repo per day. Prevents runaway loops.
  • Drafts only. F8 never opens a ready-for-review PR, never auto-merges.
  • Base branch respected. F8 creates branches off your configured base, not off HEAD of another F8 branch.

Override any of these at swiftpatch pr <clusterId> --<option> — see swiftpatch pr --help.

Dry-run mode​

Before touching anything, see what F8 would do:

swiftpatch pr crash_abc123 --dry-run

Output:

Dry run — nothing pushed.
Branch      : swiftpatch/fix/abc12345
Base        : main
Title       : Swiftpatch AI fix: null dereference in ProfileHeader
Files       : src/components/ProfileHeader.tsx

No branch is created, no commit made, no PR opened.

The legacy local flow​

Before the GitHub App, F8 ran locally via git apply. You can still use it with --local:

swiftpatch pr crash_abc123 --local

This flow:

  1. Requires you to be inside the repo's working tree.
  2. Creates a branch locally.
  3. Applies the patch with git apply.
  4. Commits.
  5. Uses gh CLI (if installed) to push and open the PR — or prints the commands for you to run.

The GitHub App flow is preferred for CI/CD and team environments. The local flow is useful if you don't want a third-party app installed on the repo.

Opting out​

Uninstall the app from GitHub's organization settings → Installed GitHub Apps → Swiftpatch → Uninstall. This immediately revokes all access.

From the Swiftpatch dashboard, disconnecting the repo stops F8 from operating on it but leaves the GitHub App installed for other repos.

Troubleshooting​

  • "Repository not accessible" — the GitHub App wasn't granted access to this repo. Re-install the app from GitHub and include the repo.
  • "Base branch not found" — your configured base branch (typically main) doesn't exist. Set a different base in the dashboard.
  • "Diff stale" — the cluster's suggested fix was generated against an older commit, and the relevant lines have moved. Regenerate the analysis from the dashboard.
  • PR body is truncated — GitHub has a 65K character limit on PR bodies. F8 trims gracefully; the full analysis is always available in the dashboard.

Next steps​

On this page