将你的 Atoms 项目连接到 GitHub，以便将其代码保存在私有仓库中，并且无需使用 Git 命令即可在 Atoms 和 GitHub 之间同步更改。

本指南将说明完整的设置流程：将你的 GitHub 账户连接到 Atoms、创建仓库、确认连接正常工作，以及让项目在 Atoms 和 GitHub 中的版本保持同步。

连接如何工作

连接 GitHub 分为 2 个阶段：

1. 连接你的 GitHub 账户。 这会授予 Atoms 代表你与 GitHub 协作的权限。
2. 为你的项目创建一个仓库。 仓库是 GitHub 中用于存储项目代码和变更历史的私有空间。

Atoms 当前会在已连接用户的个人 GitHub 账户中创建一个 新的私有仓库 。你不能连接到现有仓库、不能在组织名下创建仓库，也不能通过该连接器将其设为公开。

开始之前

在将你的项目连接到 GitHub 之前，请确认：

• 你的 Atoms 套餐包含 GitHub connection。如果你使用的是 Free 套餐，选择 GitHub 会将你带到 Plans 页面。
• 只有 workspace owner 才能连接或断开 GitHub。如果你是编辑者，请让工作区所有者执行此步骤。
• 你拥有一个 GitHub 账户，或已准备好在设置过程中创建一个。
• 你的浏览器允许来自 Atoms 的弹出窗口。
• 当前没有任何 智能体 正在处理你的项目。

你无需 GitHub personal access token 即可连接你的账户。切勿将 GitHub Token、密码或其他凭据粘贴到 Chat 中。

连接你的 GitHub 账户

打开 GitHub 连接器

1. 打开你想要连接的项目。
2. 点击聊天面板右上角的项目名称。
3. 在出现的下拉菜单中选择 Connectors。
4. 在可用连接器列表中找到 Github，然后点击 connect。<strong> </strong>

你也可以打开 Settings → Connectors → GitHub，然后选择 Connect。

打开 Settings → Connectors，并为 GitHub 选择 Connect。

在 GitHub 中授权 Atoms

如果 Connected Account 已显示你想使用的 GitHub 账户，则说明它已经完成授权。你可以继续执行 创建私有仓库。

1. Atoms 会打开一个 GitHub 授权窗口。登录你想连接的 GitHub 账户，或在需要时创建一个新账户。
2. 检查你登录的是否是正确的 GitHub 账户。
3. 查看 Atoms 请求的权限。如果你同意，请选择 Authorize Atoms-Agents。
4. 返回 Atoms，并等待出现 Connect success 消息。
5. 在 Atoms 中，打开 Connectors 并确认你的 GitHub 账户显示为已连接。

Atoms 会请求 repo、read:user 和 workflow OAuth 权限。这些权限允许 Atoms 读取和写入已连接账户可访问的公开和私有仓库、读取基本个人资料信息，以及添加或更新 GitHub Actions workflow 文件。

此授权适用于已连接的 GitHub 账户，并不仅限于为当前 Atoms 项目创建的仓库。Atoms 无法访问该已连接账户本身无权访问的仓库，组织策略也可能施加额外限制。

查看 GitHub 权限并选择 Authorize Atoms-Agents。

创建私有仓库

在授权你的 GitHub 账户后，创建将用于存储项目代码的私有仓库。

1. 在 Connected Account 下，检查显示的用户名是否与你想使用的 GitHub 账户一致。
2. 在 Create New Repository 下，输入仓库名称。名称必须：
   • 包含 1–100 个字符；
   • 仅使用字母、数字、连字符 (-)、下划线 (_) 或句点 (.)。
3. 选择 Create。
4. 等待出现 GitHub repository connected successfully! 消息。

Atoms 会在已连接用户的个人 GitHub 账户中创建一个新的 私有仓库 ，将其链接到当前 Atoms 项目，然后尝试将项目当前文件上传到 GitHub。

输入名称并创建新的私有仓库。

检查连接是否成功

在开始依赖该仓库之前，请同时在 Atoms 和 GitHub 中检查连接状态。

1. 在 Atoms 中，确认 Repository Status 显示为 Connected。
2. 在 Branches 下，检查是否有一个分支带有勾选标记。这是当前与你的 Atoms 项目连接的分支。如果你刚开始使用 GitHub，请保持选择此分支。
3. 选择 View on GitHub。
4. 在 GitHub 中，确认该仓库：
   • 属于正确的 GitHub 账户；
   • 被标记为 Private；
   • 包含预期的项目文件；并且
   • 至少有一个 commit。

如果仓库为空，并且 Atoms 中显示 Push Changes 可用，请选择它并等待操作完成。然后刷新 GitHub 中的仓库页面，并检查项目文件是否已显示。

在 Atoms 中检查已连接的仓库和所选分支。

在 GitHub 中验证私有仓库和项目文件。

保持 Atoms 和 GitHub 同步

Atoms 和 GitHub 不会自动保持同步。当某一侧发生更改时，请使用同步控件将这些更改同步到另一侧。

Action	Use it when	What happens
Push Changes	你在 Atoms 中进行了更改，并希望将其发送到 GitHub。	Atoms 会将当前项目文件发送到所选的 GitHub 分支。
Pull Updates	GitHub 中所选分支发生了更改，而你希望将这些更改拉取到 Atoms。	Atoms 会使用 GitHub 中的最新更改更新项目。

在推送或拉取更改之前，请等待 智能体 完成工作，并确保你在 Chat 中查看的是项目的最新版本。如果你从 History 打开了较旧版本，请返回 Chat 底部的最新版本卡片，然后重新打开 GitHub。

如果你当前不是最新版本，Atoms 会显示 You must be on the latest version to pull updates or push changes.

在同步之前，还请检查所选分支是否是你想更新的分支。

如果 Atoms 和 GitHub 两边都包含你需要保留的更改，请先不要同步。请先保存重要工作的副本，或请熟悉 GitHub 的人员将这些更改保存在单独的分支中。

如果 Repository Status 显示 Upstream Changes Available，则表示 GitHub 中存在 Atoms 尚未获取的更改。在选择操作之前，请先检查仓库。

对所选分支使用 Pull Updates 和 Push Changes。

将更改从 Atoms 推送到 GitHub

1. 在 Atoms 中完成你的更改，并等待 智能体 停止工作。
2. 确保你查看的是项目的最新版本。
3. 打开 Settings → Connectors → GitHub 并检查是否选择了正确的分支。
4. 选择 Push Changes。
5. 在更改推送期间保持页面打开。
6. 当出现 Changes pushed successfully 时，选择 View on GitHub 并检查最新项目文件是否已显示在那里。

只有当 Atoms 中存在尚未发送到 GitHub 的更改时，Push Changes 才可用。当 智能体 正在工作或你正在查看项目的旧版本时，它不可用。

一旦你选择 Push Changes，更改会立即发送到 GitHub，而不会要求确认。<strong> </strong>如果同一个文件在 Atoms 和 GitHub 中都被修改过，则 Atoms 中的版本优先，并会覆盖 GitHub 中当前存储的版本。

将 GitHub 中的更新拉取到 Atoms

与推送不同，拉取更改需要先确认。如果同一个文件在 GitHub 和 Atoms 中都被修改过，则 GitHub 版本优先，并会覆盖 Atoms 中的当前版本。

1. 打开 Settings → Connectors → GitHub。
2. 检查 Repository Status 是否显示来自 GitHub 的新更改，并确认已选择正确的分支。
3. 选择 Pull Updates。
4. 阅读 Pull May Affect Project 警告。如果你想将 GitHub 中的更改拉取到当前 Atoms 项目中，请选择 Confirm。
5. 在更改拉取期间保持页面打开。
6. 当出现 Changes pulled successfully 时，打开 App 预览 并测试项目中受这些更改影响的部分，以确保一切仍按预期运行。

只有当所选 GitHub 分支包含尚未拉取到 Atoms 的更改时，Pull Updates 才可用。

断开 GitHub

当你不再希望 Atoms 访问已连接账户时，请断开 GitHub。GitHub 仓库及其文件仍会保留在 GitHub 中，但 Atoms 将无法再推送或拉取更改。

GitHub 授权适用于已连接的账户。撤销访问权限会断开所有使用该 GitHub 账户的 Atoms 项目，因此在继续之前请检查你的其他项目。

1. 打开 Settings → Connectors → GitHub。
2. 选择 Disconnect。
3. 在 Disconnect GitHub 确认框中，再次选择 Disconnect。
4. GitHub 应会自动打开相关授权页面。如果没有，请在 GitHub 中前往 Settings → Applications → Authorized OAuth Apps。
5. 找到 Atoms，选择其所在行右侧的 <strong>...</strong>，然后选择 Revoke。不要选择 Revoke all；该操作会移除页面中列出的所有已授权 OAuth 应用的访问权限。
6. 按照 Github 要求完成所有必要的确认步骤。
7. 返回 Atoms 并重新打开 GitHub 连接器，以确认该账户已不再连接。

在 GitHub 连接器中选择 Disconnect。

仅在 GitHub 中撤销 Atoms OAuth 应用。