GitHub

The GitHub integration links Swarmz projects to real GitHub repositories. Code generated by the agent gets pushed to your repo, commits made on GitHub flow back into the project automatically, and you can open pull requests from the editor toolbar without touching the command line.

Swarmz uses a GitHub App (swarmz-net) rather than a classic OAuth app. That means you authorize Swarmz once at the user level for identity, then install the app on each org or personal account whose repos you want to expose. The app issues short-lived installation tokens (1-hour expiry) that Swarmz refreshes per push or pull, so there's no long-lived password sitting in our database.

Setup

To add another org or account later, click Add installation on the GitHub card and run through the install flow again. You can have multiple installations under a single connection — useful if your personal repos and your work org's repos both live behind Swarmz.

Linking a repo to a project

Open a project, click GitHub in the project sidebar, then either:

• Link existing repo — pick a repo from any of your installations. Swarmz adds it as the project's git remote, sets sync_enabled = true in project_github_repos, and the next push goes straight to GitHub.
• Import existing repo — clone a repo's contents into the project's container. The agent then runs npm install and the project boots from the imported codebase.
• Create new repo — Swarmz creates a fresh repo under the installation you choose, then pushes the project's current state as the first commit.

Only one repo can be linked per project. To swap repos, unlink the current one first.

Two-way sync

Sync runs in both directions automatically once a repo is linked.

Push (project → GitHub)

Every time the agent finishes a turn that wrote files, the changes are committed inside the container and pushed to the linked repo on the default branch. You can also trigger a manual push from the editor toolbar with a custom commit message.

Internally the editor calls the github-sync edge function with action: "push". The function fetches a fresh installation token, rewrites the git remote URL with that token (https://x-access-token:<token>@github.com/<repo>.git), commits, and pushes.

Pull (GitHub → project)

Pulling happens two ways.

Webhook-driven (immediate). When something pushes to your linked repo on GitHub — a teammate, a CI bot, a merged PR — GitHub fires a push event to the github-sync webhook. Swarmz finds every project linked to that repo_full_name, checks the branch matches default_branch, and runs git pull inside each project's running container. If the container is hibernated, the pull is skipped (it'll catch up on the next wake).

Polling fallback (every 60s). While you have a project open in the editor, Swarmz polls the linked repo every 60 seconds and pulls if the remote tip has moved. This covers cases where the webhook didn't fire — installation issues, dropped events, projects on suspended workspaces.

The combination means changes from anywhere arrive within a minute, and usually within a few seconds.

Branch tracking

By default, sync targets the repo's default_branch (typically main or master). To work on a feature branch:

Switch to a feature branch called add-auth

The agent runs git checkout -b add-auth, pushes the branch, and updates project_github_repos.default_branch so future syncs follow it. Switch back with Switch to main or open a PR with:

Open a PR from add-auth into main

Swarmz uses the GitHub API (with the installation token) to create the PR and returns the URL.

Conflicts

A conflict happens when the project's working tree and the remote branch have both changed since the last sync. The conflict resolution depends on direction:

• On push — if the remote is ahead, Swarmz pulls first, attempts a merge, and if the merge clean, pushes. If the merge produces conflict markers, the push is aborted and the editor shows a banner with the conflicting files. You resolve them in the file tree and click Push again.
• On pull — if the project has uncommitted changes, the pull stages a stash, fast-forwards, then re-applies. If reapplication conflicts, the editor surfaces the conflicted files for manual resolution.

The agent can also resolve conflicts on request. Tell it Resolve the merge conflicts in src/auth.ts and it'll pick a resolution and explain the trade-off.

What's stored where

Tokens are encrypted at rest with TOKEN_ENCRYPTION_KEY. Installation tokens are minted on demand and never stored.

Disconnecting

Settings → Integrations → GitHub → Disconnect removes:

• All github_installations for your user
• All project_github_repos rows that referenced your connection
• The github_connections row itself

The repos on GitHub are not touched. If you want to also revoke the GitHub App, go to your GitHub account settings and uninstall it from each org — or click Remove next to a single installation in the Swarmz UI.