Connect to GitHub

Two-way sync between your project and a repository you own.

Connecting GitHub keeps a repository you own in sync with the project, both ways. It uses a fine-grained personal access token limited to that one repository. GitHub sync is included on paid plans.

#How the two branches work

Branch	What Totalum does
`develop`	Every new version — a prompt that changed code, a file saved through the API, a visual edit, a restore, an import — is committed and pushed here
`main`	On every Publish, the published code is pushed here

Your commits come back in. Push to develop and Totalum pulls your commits before the next prompt (each becomes a version); you can also pull them at once with Pull (or the API). If your commits and the agent's change touch the same lines, the agent merges them in the same run.

Work on `develop`, publish from Totalum

Commits pushed straight to main are not deployed and are overwritten by the next publish. Change code on develop, then publish from Totalum.

#Create the token

GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token.
Give it a name and an expiration.
Repository access: Only select repositories → your repository.
Repository permissions: Contents — Read and write (Metadata — Read is added automatically). That is all Totalum needs; more permissions do no harm.
Generate it and copy it (it starts with github_pat_).

#Connect it

In the platform: open the project's Code tab → Sync with GitHub. Enter the repository (owner/repo or its URL), paste the token, choose the sync direction if asked, and press Connect. Totalum checks the access, stores the token encrypted and makes the first sync:

An empty repository — Totalum creates develop and main and pushes the project.
A repository with code — develop and main must exist. If the repository has code with no shared history, choose the direction: push the project to GitHub (Totalum → GitHub), or bring the repository's code into the project (GitHub → Totalum).

The same panel shows the connection, pulls on demand (Pull from GitHub) and disconnects.

Through the API: Connect GitHub Repository with token, repositoryFullName and, for a repository with unrelated code, syncDirection; then Get GitHub Status and Pull from GitHub.

#Set up the .env to work on the code

Secrets are never committed, so a clone of the repository has no .env. Each environment has its own file with everything the app needs to run: the project key, the sign-in secret, the database environment and that environment's secrets.

File	Use it for
`.env` (development)	Working on the code. Uses the development database (the preview's data) and test payments. Start here.
`.env.prod` (live)	Only to work on the live site on purpose: it uses the live database

Platform projects: project menu → Project API keys → Run the project on your computer → Download .env (or Copy). The live file is under the same heading. The Code tab's Download project also puts both files in the ZIP.

API projects: ask for the file of one environment, or both at once:

bash

# one environment, as the file itself
curl -sf -H "api-key: $API_KEY" -o .env \
  "https://builder-api.totalum.app/api/v1/vcaas/projects/$PROJECT_ID/env?env=dev"

# both, as JSON (envDev and envProd)
curl -sf -H "api-key: $API_KEY" \
  "https://builder-api.totalum.app/api/v1/vcaas/projects/$PROJECT_ID/github/env" | jq -r '.data.envDev' > .env

See Get Project Env and Download Environment Variables. Only the account owner, or a member allowed to manage API keys, can download them.

Then work on develop:

bash

git clone https://github.com/owner/repo.git my-app && cd my-app
git checkout develop
# put the .env here
npm ci
npm run dev        # http://localhost:3100, on the development database
git commit -am "…" && git push origin develop   # Totalum pulls it before the next prompt

What the file holds:

Variable	Meaning
`TOTALUM_PROJECT_KEY`	The project key the code uses for its database and built-in features. Keep it on the server, never in `NEXT_PUBLIC_` variables
`TOTALUM_ENV`	`dev` or `live`: which database the code reaches, and where usage is counted
`BETTER_AUTH_SECRET`	Signs the sign-in sessions
`TOTALUM_PROJECT_ID`	The project id. Optional: without it the app still runs
`TOTALUM_SDK_API_URL`	Where the built-in features answer. Optional: defaults to `https://sdk-api.totalum.app`
`NEXT_PUBLIC_APP_URL`, `NODE_ENV`	The app's address and the Node mode for that environment
Your secrets	The secrets you set for that environment (for example a third-party API key)

The key in these files is the project's environment-file key. If a copy leaks, rotate it in Project API keys (or with Rotate Project Key) and download the files again; the running app is not affected.

#Good to know

The token is encrypted at rest and never returned or logged. If it expires or is revoked, the project shows that it needs reconnecting.
Branch protection rules on your repository are never changed.
Secrets are never committed: set up the .env as above.
To run the code elsewhere for good, see Move to Another Host.