GitHub synchronization

Before connecting

GitHub synchronization connects a project to a repository you own. It requires the corresponding capability in the project owner's plan. Existing connections can still be viewed and removed when that capability is unavailable, but new connections and synchronization are blocked. This restriction does not stop the agent from editing your project or saving local file versions.

Choose a GitHub repository without a main branch and copy its full HTTPS URL. Other branches, files, and commits are allowed. Amazi creates main automatically with your project's history; you create or choose the repository yourself.

If main already exists, preserve any work you need in another branch before removing it. GitHub requires another default branch before you can delete the default main; branch protection may also restrict deletion. You can instead choose another repository. To restore access to an already connected repository, use Update connection and keep main.

Connect the project

1. Open the project's GitHub connection dialog.
2. Enter the repository's HTTPS URL.
3. Complete the GitHub authorization and installation flow for that repository.
4. Return to Amazi and check the connection status.

Amazi creates main during initial connection and synchronizes that branch. Other branches remain intact. The GitHub default branch can have another name; you can make the new main the default in GitHub after connecting.

Never paste a GitHub access token into chat to resolve an authorization problem. Use the connection flow and verify that the installation has access to the intended repository.

If connection fails, Amazi displays the reason and recovery steps. An existing main prevents a new connection, even if its latest commit matches the project. The error notification stays visible until you dismiss it.

Update an existing connection

Use Update connection in the GitHub dialog when access stops working, including after reinstalling the GitHub App. Authorize GitHub again and grant the application access to the connected repository. Amazi verifies the same repository, including after a rename, and updates the connection.

Amazi then retries synchronization: incoming changes are accepted by fast-forward, and local commits are sent when the histories allow a normal push. If the histories diverge or synchronization fails, the restored connection is kept and the synchronization error remains visible. Review the error in the GitHub dialog. Updating access does not require deleting main or clearing repository history.

What synchronization does

Before an agent task, Amazi checks remote main and accepts incoming history only when it can move forward without merging divergent changes. After a committed checkpoint, it performs a normal push. External pushes can also trigger synchronization; an active task may be interrupted before the local worktree changes.

Amazi does not automatically force-push, rebase conflicting histories, or discard local files to make synchronization succeed.

If histories diverge

A synchronization error is separate from the result of local agent work. Local work and checkpoints can succeed while the GitHub connection reports a failed synchronization.

Read the reported error and compare the local and remote histories before choosing a recovery. Ask for diagnosis first if you are unsure which changes to keep. Resolve the divergence deliberately or connect another repository without main; do not repeatedly trigger destructive Git commands to hide the error.

Disconnecting and backups

Disconnecting removes the Amazi connection, not the repository in GitHub. Deleting the Amazi project does not authorize deleting that repository either.

GitHub stores versioned project files, not a backup of database rows, object storage, or external service state. See History and restore and Database and storage before treating source synchronization as disaster recovery.