Connect to GitHub

Link a GitHub repository to your project for a bidirectional code workflow, using a fine-grained Personal Access Token.

Connecting GitHub gives your Totalum project a bidirectional sync with a repository you own. The Totalum AI agent pushes its changes to your repo automatically, and changes you push to GitHub flow back into the project. Connection uses a fine-grained Personal Access Token (PAT).

#How the two branches work

Totalum uses two branches with clear roles:

develop — the working branch. Every time the Totalum AI agent completes a job, it auto-commits the changes and pushes them to develop.
main — the production branch. When you Publish your project from Totalum, it creates and merges a pull request from develop → main, and then deploys.

Never commit directly to `main`

Work on develop and always publish from Totalum. Publishing is what promotes develop to main and deploys — committing directly to main bypasses that flow.

#The full flow

On every AI job (auto-commit → develop):

Pull the latest from develop (resolving conflicts).
Check whether there are real changes.
Generate a concise commit message from the agent's summary.
Commit and push to develop.

On Publish (deploy):

Create a pull request from develop → main.
Auto-merge it.
Deploy to production (Cloudflare).

On agent start (bidirectional pull):

Pull the latest from develop — so any commits you pushed to GitHub are picked up.
Auto-resolve conflicts, preferring your remote changes.
Sync the files into the sandbox before the agent runs.

This means you can edit code directly on GitHub (on develop), and those edits are merged into the project the next time the agent runs.

#Required token permissions

Create a fine-grained PAT scoped to the single repository, with these repository permissions:

Permission	Access	Purpose
Contents	Read and Write	Create branches and commits; push to branches
Pull requests	Read and Write	Create and merge the `develop` → `main` deploy PR
Metadata	Read	Access repository information (auto-granted)

#Create the token

Go to GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens.
Click Generate new token.
Set a name (e.g. "Totalum Integration") and an expiration.
Under Repository access, choose Only select repositories and pick your project's repo.
Grant the permissions in the table above.
Generate and copy the token (it starts with github_pat_ and is shown only once).

#Connect it

Open the GitHub option in your project (the GitHub icon at the top of the chat), enter your repository (owner/repo) and paste the token. Totalum validates the permissions, stores the token encrypted, sets up the develop and main branches, and performs the initial sync.

Empty repositories — Totalum creates develop and main automatically.
Existing repositories — both develop and main must already exist. If the repo has content with no shared git history, you choose the sync direction (push Totalum's code to GitHub, or pull GitHub's code into Totalum).

Doing this via the API?

The same flow is available programmatically — see the GitHub API endpoints.

#Notes & limits

The token is encrypted at rest and never returned in logs or responses.
If a token expires or is revoked, Totalum notifies you to reconnect with a new one.
Fine-grained PATs are limited to 50 per user and must have an expiration date; authenticated GitHub requests are rate-limited to 5,000/hour.