GitHub

GitHub is the integration most workspaces start with. The SprintLoop GitHub App is what lets a lane push a branch, open a PR, post status updates, and ingest CI signals back into the lane’s audit ledger. Without the app, lanes are read-only on GitHub; with it, they’re full collaborators.

This page covers install, scopes, repo connection, branch protection, webhook flow, and the most common gotchas.

Install the app

From inside SprintLoop: Settings → Integrations → GitHub → Install the GitHub App. You’ll be redirected to GitHub’s app install flow.

GitHub will ask you to pick:

1. Account or org. Pick whichever owns the repos you want SprintLoop to dispatch lanes against. You can install the app on multiple orgs and switch between them later.
2. Repos. Choose All repositories if you want every repo in the org connected, or Only select repositories to pick a subset. The “select” path is recommended — it limits blast radius if a lane misbehaves.

After install, you’re back in SprintLoop with a green status row for each connected repo. The app fetches the default branch, the branch protection rules, and the CI configuration in the background; this usually takes 5–15 seconds.

Required scopes

The app requests the following permissions at install time:

Scope	Why
contents: write	Push lane branches, write commits
pull_requests: write	Open PRs, post status comments
checks: read	Ingest CI status into the lane audit ledger
members: read	Show PR reviewer suggestions from your team
metadata: read	Read repo settings (default branch, branch protection)

It does not request:

• secrets — SprintLoop never reads or writes your repo secrets.
• packages — no access to GitHub Packages.
• admin:org — no access to org admin endpoints.
• delete:repo — no destructive permissions.

If your security team needs to audit, the manifest is published at https://github.com/apps/sprintloop and the scopes are visible from the app’s public page.

Repo connection

A repo is “connected” once the app is installed on it AND the workspace has it listed under Settings → Integrations → GitHub → Repos. The first install populates the list automatically; you can disconnect a repo later without uninstalling the app.

Each connected repo gets:

• A default branch (auto-detected from GitHub).
• A scope policy (default: lanes can claim any path under the repo).
• A CI ingest setting (default: checks: all).
• An optional PR template override.

Connection is per-workspace. The same repo can be connected to two SprintLoop workspaces — useful when an open-source project has separate dev and security workspaces. Lanes from different workspaces against the same repo do not share scope claims; conflicts are resolved at PR-merge time on the GitHub side.

What happens when a lane opens a PR

The full flow:

1. Owner approves the lane.
2. SprintLoop pushes the lane’s signed commits to a branch named sprintloop/<workspace-handle>/<lane-id> on the connected repo.
3. SprintLoop opens a PR via the GitHub API. PR title is the lane’s title; PR body includes the brief, the harness used, model versions, the Review Committee verdicts, and a link to the lane’s audit page.
4. GitHub fires status checks and any branch-protection-required reviewers.
5. SprintLoop ingests check results back into the lane’s chain (signed entries — each CI status is auditable).
6. When the PR is merged on GitHub (by you or another teammate), SprintLoop receives the pull_request.closed webhook, marks the lane as merged, and stamps the federation root.

The PR description is verbose by default. If your team prefers terse PRs, set a template under Settings → Integrations → GitHub → PR template. The template supports the same Liquid-ish variables the lane brief uses ({{lane.title}}, {{lane.harness}}, etc.).

Branch protection

If your repo has branch protection requiring N approvals, requiring CI green, or restricting force pushes, SprintLoop respects all of it. The lane’s sign-off is internal — it’s an attestation that the workspace owner reviewed the lane — not a GitHub review. Your branch protection rules still apply on GitHub.

A common pattern: branch protection requires one external GitHub review on top of the SprintLoop sign-off. The team gets the safety of an outside pair of eyes; the lane’s audit trail captures everything the SprintLoop reviewer agents and the workspace owner saw.

If branch protection requires a status check the lane can’t satisfy (e.g., a custom check that only runs on changes to protected paths), you’ll see a yellow banner in the lane page naming the missing check. Merge will fail until the check is satisfied or the rule is amended.

Webhooks the app subscribes to

The app subscribes to:

• pull_request — to track PR merge / close.
• push — to refresh the repo map for the Context Engine.
• check_run and check_suite — to ingest CI status.
• installation and installation_repositories — to keep the connected-repos list in sync.
• workflow_run — to attribute Actions runs to the lane that triggered them.

Webhooks deliver to https://api.sprintloop.ai/integrations/github/webhook. The endpoint verifies the GitHub signature header on every request and returns 200 in <50ms (work is queued, not done inline). If GitHub reports persistent webhook failures in your org’s settings, that’s almost always a transient issue — the app retries and self-heals — but a sustained 24h failure rate above 1% should be reported to support.

Common gotchas

“My lane pushed but no PR opened.” Check that the lane’s branch was pushed against the right base. If your repo’s default branch is develop (not main), the lane uses develop as the base unless you override per-dispatch. PR creation can also fail if a PR already exists from the same branch (we don’t double-open).

“CI is green on GitHub but the lane shows pending.” The check ingest depends on the check_suite.completed webhook. Some CI providers take 30–60s to fire it after the visible green tick. If it’s still pending after 5 minutes, the webhook didn’t reach us — re-trigger the suite from GitHub or click Re-sync CI on the lane page.

“I want to use GitLab or Bitbucket instead.” GitLab is supported via the same shape of integration — see Integrations index. Bitbucket is on the roadmap for Q3 2026.

“The app keeps asking me to re-grant permissions on a new repo.” GitHub Apps have a per-org permission grant; new repos need to be added under the app’s Configure page. We don’t auto-claim newly created repos by design — opting them in is a deliberate act.