GitHub with DevFlow: setup, scope and limits

DevFlow connects each workspace to GitHub with one OAuth token and uses it to clone repositories, push task branches and open pull requests. It then follows each pull request until it is merged or closed. Setup is 2 steps in Workspace Settings → Repositories.

Kind

Source control

Where to set it up

Workspace Settings → Repositories

Plan

All plans

Agent roles

None directly

Verified

1 Oct 2026

Setup steps

1. Connect the workspace. As a workspace owner, open the Repositories tab of Workspace Settings, click "Connect GitHub" and approve the repo scope.
2. Add repositories. Back in DevFlow, the panel reads "Connected as" followed by the account name. "Add Repository", disabled until then, now searches the repositories that account can reach.

What it does

The connection is an OAuth App authorization with the repo scope, not a GitHub App. The token belongs to the workspace rather than to each member, and every clone, fetch and push for that workspace's repositories uses it. Without a connection, pushes and pull requests stop and the status poller skips the workspace's tasks until an owner connects again.

Each task works on its own branch, named devflow/<short_task_id>, in a separate worktree. When a person marks the task done, DevFlow squashes the branch to a single commit whose subject follows Conventional Commits, unless the repository declares its own commit convention, and doubles as the pull request title. It then pushes the branch and opens the pull request.

The pull request body includes a "Verification evidence" section: the models used, verifier outcomes, build gates, the security scan summary and the human approvals. Result screenshots captured for the task are embedded inline through long-lived signed links, and body, evidence and images together stay under GitHub's 64 KB limit.

Rework force-pushes the branch and refreshes the existing body, and the title only when it changed. A poller reads the state of each done task's pull request every 60 seconds and records it as merged or closed.

While a pull request is open, the same poller records whether it has merge conflicts with its base branch, once mergeability has been computed. A task that spans several repositories changes status only when all of its pull requests are closed or merged, and one merged pull request is enough to mark it merged.

After a task is done, its worktree stays on disk for 7 days by default so the diff can still be reviewed. A later rework of a cleaned-up task rebuilds the worktree from the pushed branch.

For Conventional Commits subjects, the squash subject also carries a ticket reference when the task title or description has one: the first Jira or Linear key, a #N number, or an issue URL. If a cleaned-up task's pushed branch has been deleted, a later rework rebuilds its worktree from the default branch instead.

The workspace's GitHub access and refresh tokens are stored encrypted with AES-256-GCM.

Requirements

• GitHub OAuth is configured on the DevFlow server by its operator: an OAuth App whose callback is <base>/api/auth/github/callback, with its client ID and secret in GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET. Until both are set, the connect link answers that OAuth is not configured.
• The owner role in the DevFlow workspace to connect or disconnect; other members only see the connection status.
• An account whose repo scope covers every repository the workspace will use, private ones included.

Limits

• One token per workspace: connecting again replaces it, and "Disconnect" removes it for every member.
• DevFlow does not import GitHub issues; work enters as tasks, for example created by hand, from a chat thread or from a Sentry item.

Sources

Every fact above comes from these files in the DevFlow repository.

• internal/github/oauth.go
• internal/github/client.go
• internal/api/handlers_auth.go
• internal/api/pr_poller.go
• internal/api/server.go
• internal/db/queries.go
• internal/secrets/secrets.go
• internal/api/handlers_readiness.go
• web/src/lib/components/GitHubConnect.svelte
• web/src/lib/components/WorkspaceSettings.svelte
• CLAUDE.md
• internal/agent/ticket_ref.go
• internal/api/handlers_implementation.go