Connect your Atoms project to GitHub to keep its code in a private repository and move changes between Atoms and GitHub without using Git commands.

This guide explains the full setup process: connecting your GitHub account to Atoms, creating the repository, confirming that the connection is working, and keeping the Atoms and GitHub versions of your project in sync.

How the connection works

There are 2 stages to connecting GitHub:

1. Connect your GitHub account. This gives Atoms permission to work with GitHub on your behalf.
2. Create a repository for your project. A repository is the private space in GitHub where your project’s code and change history are stored.

Atoms currently creates a new private repository in the connected user’s personal GitHub account. You cannot connect to an existing repository, create the repository under an organization, or make it public through the connector.

Before you start

Before connecting your project to GitHub, make sure that:

• Your Atoms plan includes GitHub connection. If you are on the Free plan, selecting GitHub will take you to the Plans page.
• Only the workspace owner can connect or disconnect GitHub. If you are an editor, ask the workspace owner to perform this step.
• You have a GitHub account or are ready to create one during setup.
• Your browser allows pop-up windows from Atoms.
• No Agents are currently working on your project.

You do not need a GitHub personal access token to connect your account. Never paste GitHub tokens, passwords, or other credentials into Chat.

Connect your GitHub account

Open the GitHub connector

1. Open the project you want to connect.
2. Click project name, at the top right of the chat panel.
3. Select Connectors in the drop down menu that appears.
4. Find Github in the list of available connectors, and click connect.

You can also open Settings → Connectors → GitHub and select Connect.

Open Settings → Connectors and select Connect for GitHub.

Authorize Atoms in GitHub

If Connected Account already shows the GitHub account you want to use, it has already been authorized. You can continue to Create a private repository.

1. Atoms opens a GitHub authorization window. Sign in to the GitHub account you want to connect to, or create a new account if needed.
2. Check that you are signed in to the correct GitHub account.
3. Review the permissions requested by Atoms. If you agree, select Authorize Atoms-Agents.
4. Return to Atoms and wait for the Connect success message.
5. In Atoms, open Connectors and confirm that your GitHub account appears as connected.

Atoms requests the repo, read:user, and workflow OAuth permissions. These allow Atoms to read and write public and private repositories that the connected account can access, read basic profile information, and add or update GitHub Actions workflow files.

This authorization applies to the connected GitHub account and is not limited to the repository created for the current Atoms project. Atoms cannot access repositories that the connected account itself cannot access, and organization policies may impose additional restrictions.

Review GitHub permissions and select Authorize Atoms-Agents.

Create a private repository

After authorizing your GitHub account, create the private repository that will store your project’s code.

1. Under Connected Account, check that the displayed username matches the GitHub account you want to use.
2. Under Create New Repository, enter a name for the repository. The name must:
   • contain 1–100 characters;
   • use only letters, numbers, hyphens (-), underscores (_), or periods (.).
3. Select Create.
4. Wait for the GitHub repository connected successfully! message.

Atoms creates a new private repository in the connected user’s personal GitHub account, links it to the current Atoms project, and then attempts to upload the project’s current files to GitHub.

Enter a name and create a new private repository.

Check that the connection worked

Check the connection in both Atoms and GitHub before relying on the repository.

1. In Atoms, confirm that Repository Status shows Connected.
2. Under Branches, check that one branch has a check mark. This is the branch currently connected to your Atoms project. If you are new to GitHub, keep this branch selected.
3. Select View on GitHub.
4. In GitHub, confirm that the repository:
   • belongs to the correct GitHub account;
   • is marked Private;
   • contains the expected project files; and
   • has at least one commit.

If the repository is empty and Push Changes is available in Atoms, select it and wait for the operation to finish. Then refresh the repository page in GitHub and check that the project files now appear.

Check the connected repository and selected branch in Atoms.

Verify the private repository and project files in GitHub.

Keep Atoms and GitHub in sync

Atoms and GitHub do not stay in sync automatically. When changes have been made on one side, use the synchronization controls to move those changes to the other.

Action	Use it when	What happens
Push Changes	You made changes in Atoms and want to send them to GitHub.	Atoms sends the current project files to the selected GitHub branch.
Pull Updates	Changes were made to the selected branch in GitHub and you want to bring them into Atoms.	Atoms updates the project with the latest changes from GitHub.

Before you push or pull changes, wait for the Agent to finish and make sure you are viewing the latest version of the project in Chat. If you opened an older version from History, return to the latest version card at the bottom of the Chat, then reopen GitHub.

If you are not on the latest version, Atoms displays You must be on the latest version to pull updates or push changes.

Before synchronizing, also check that the selected branch is the one you want to update.

If both Atoms and GitHub contain changes that you need to keep, do not synchronize them yet. Save a copy of the important work first, or ask someone familiar with GitHub to preserve the changes on a separate branch.

If Repository Status shows Upstream Changes Available, GitHub contains changes that Atoms does not yet have. Review the repository before choosing an action.

Use Pull Updates and Push Changes for the selected branch.

Push changes from Atoms to GitHub

1. Finish making your changes in Atoms and wait for the Agent to stop working.
2. Make sure you are viewing the latest version of the project.
3. Open Settings → Connectors → GitHub and check that the correct branch is selected.
4. Select Push Changes.
5. Keep the page open while the changes are being pushed.
6. When Changes pushed successfully appears, select View on GitHub and check that the latest project files are there.

Push Changes is available only when Atoms has changes that have not yet been sent to GitHub. It is unavailable while the Agent is working or when you are viewing an older version of the project.

Once you select Push Changes, the changes are sent to GitHub immediately without asking for confirmation. If the same file has been changed in both Atoms and GitHub, the version in Atoms takes priority and will overwrite the version currently stored in GitHub.

Pull updates from GitHub into Atoms

Unlike pushing, pulling changes requires confirmation first. If the same file has been changed in both GitHub and Atoms, the GitHub version takes priority and will overwrite the current version in Atoms.

1. Open Settings → Connectors → GitHub.
2. Check that Repository Status shows new changes from GitHub and that the correct branch is selected.
3. Select Pull Updates.
4. Read the Pull May Affect Project warning. If you want to bring the GitHub changes into your current Atoms project, select Confirm.
5. Keep the page open while the changes are being pulled.
6. When Changes pulled successfully appears, open the App Viewer and test the parts of your project affected by the changes to make sure everything still works as expected.

Pull Updates is available only when the selected GitHub branch contains changes that have not yet been brought into Atoms.

Disconnect GitHub

Disconnect GitHub when you no longer want Atoms to access the connected account. The GitHub repository and its files will remain in GitHub, but Atoms will no longer be able to push or pull changes.

GitHub authorization applies to the connected account. Revoking access disconnects every Atoms project that uses that GitHub account, so check your other projects before continuing.

1. Open Settings → Connectors → GitHub.
2. Select Disconnect.
3. In the Disconnect GitHub confirmation, select Disconnect again.
4. GitHub should open the relevant authorization page automatically. If it does not, in GitHub go to Settings → Applications → Authorized OAuth Apps.
5. Find Atoms, select ... at the right of its row, then select Revoke. Do not select Revoke all; that action removes access for every authorized OAuth app listed on the page.
6. Follow any confirmation steps needed from Github.
7. Return to Atoms and reopen the GitHub connector to confirm that the account is no longer connected.

Select Disconnect in the GitHub connector.

Revoke only the Atoms OAuth application in GitHub.