Integrations

連接 GitHub

將您的 Atoms 專案連接到 GitHub，以便將其程式碼保存在私人儲存庫中，並在不使用 Git 指令的情況下，在 Atoms 與 GitHub 之間移動變更。

本指南說明完整的設定流程：將您的 GitHub 帳號連接到 Atoms、建立儲存庫、確認連接正常運作，以及讓您專案在 Atoms 與 GitHub 中的版本保持同步。

連接如何運作

連接 GitHub 分為 2 個階段：

連接您的 GitHub 帳號。 這會授予 Atoms 權限，讓其代表您與 GitHub 互動。
為您的專案建立儲存庫。 儲存庫是 GitHub 中的私人空間，用來儲存您專案的程式碼與變更歷史。

Atoms 目前會在已連接使用者的個人 GitHub 帳號中建立一個 新的私人儲存庫。您無法連接到現有儲存庫、無法在組織底下建立儲存庫，也無法透過連接器將其設為公開。

開始之前

在將您的專案連接到 GitHub 之前，請確認：

您的 Atoms 方案包含 GitHub 連接。如果您使用的是 Free 方案，選取 GitHub 會帶您前往 Plans 頁面。
只有 工作區擁有者 可以連接或中斷 GitHub。如果您是編輯者，請要求工作區擁有者執行此步驟。
您有 GitHub 帳號，或已準備好在設定期間建立一個。
您的瀏覽器允許來自 Atoms 的彈出式視窗。
目前沒有任何 智能體 正在處理您的專案。

您不需要 GitHub personal access token 即可連接帳號。絕對不要將 GitHub Token、密碼或其他憑證貼到 Chat 中。

連接您的 GitHub 帳號

開啟 GitHub 連接器

開啟您想要連接的專案。
點擊聊天面板右上角的專案名稱。
在出現的下拉式選單中選取 Connectors。
在可用連接器清單中找到 Github，然後點擊 connect。

您也可以開啟 Settings → Connectors → GitHub，然後選取 Connect。

開啟 Settings → Connectors，並為 GitHub 選取 Connect。

在 GitHub 中授權 Atoms

如果 Connected Account 已經顯示您想使用的 GitHub 帳號，表示它已經完成授權。您可以繼續進行 建立私人儲存庫。

Atoms 會開啟 GitHub 授權視窗。登入您想要連接的 GitHub 帳號，或在需要時建立新帳號。
檢查您是否已登入正確的 GitHub 帳號。
檢視 Atoms 要求的權限。如果您同意，請選取 Authorize Atoms-Agents。
返回 Atoms，並等待出現 Connect success 訊息。
在 Atoms 中開啟 Connectors，並確認您的 GitHub 帳號顯示為已連接。

Atoms 會要求 repo、read:user 與 workflow OAuth 權限。這些權限允許 Atoms 讀取與寫入已連接帳號可存取的公開與私人儲存庫、讀取基本個人資料資訊，以及新增或更新 GitHub Actions workflow 檔案。

此授權適用於已連接的 GitHub 帳號，並不限於為目前 Atoms 專案建立的儲存庫。Atoms 無法存取已連接帳號本身無法存取的儲存庫，而組織政策可能會施加額外限制。

檢視 GitHub 權限，並選取 Authorize Atoms-Agents。

建立私人儲存庫

在授權您的 GitHub 帳號後，請建立將用來儲存您專案程式碼的私人儲存庫。

在 Connected Account 下，確認顯示的使用者名稱與您想使用的 GitHub 帳號一致。
在 Create New Repository 下，輸入儲存庫名稱。名稱必須：
- 包含 1–100 個字元；
- 只能使用字母、數字、連字號 (-)、底線 (_) 或句點 (.)。
選取 Create。
等待出現 GitHub repository connected successfully! 訊息。

Atoms 會在已連接使用者的個人 GitHub 帳號中建立新的 私人儲存庫，將其連結到目前的 Atoms 專案，然後嘗試將專案目前的檔案上傳到 GitHub。

輸入名稱並建立新的私人儲存庫。

檢查連接是否成功

在開始依賴該儲存庫之前，請同時在 Atoms 與 GitHub 中檢查連接狀態。

在 Atoms 中，確認 Repository Status 顯示為 Connected。
在 Branches 下，確認有一個分支帶有勾選標記。這是目前連接到您 Atoms 專案的分支。如果您剛開始使用 GitHub，請保持選取此分支。
選取 View on GitHub。
在 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

在 Atoms 中完成您的變更，並等待 智能體 停止工作。
確認您正在查看專案的最新版本。
開啟 Settings → Connectors → GitHub，並確認已選取正確的分支。
選取 Push Changes。
在推送變更期間請保持頁面開啟。
當出現 Changes pushed successfully 時，選取 View on GitHub，並確認最新的專案檔案已在其中。

只有在 Atoms 有尚未傳送到 GitHub 的變更時，才可使用 Push Changes。當 智能體 正在工作，或您正在查看較舊版本的專案時，將無法使用此功能。

一旦您選取 Push Changes，變更會立即傳送到 GitHub，不會要求確認。如果同一個檔案在 Atoms 與 GitHub 中都已被修改，Atoms 中的版本會優先，並覆寫目前儲存在 GitHub 中的版本。

將更新從 GitHub 拉取到 Atoms

與推送不同，拉取變更需要先確認。如果同一個檔案在 GitHub 與 Atoms 中都已被修改，GitHub 版本會優先，並覆寫 Atoms 中目前的版本。

開啟 Settings → Connectors → GitHub。
確認 Repository Status 顯示來自 GitHub 的新變更，且已選取正確的分支。
選取 Pull Updates。
閱讀 Pull May Affect Project 警告。如果您想將 GitHub 的變更帶入目前的 Atoms 專案，請選取 Confirm。
在拉取變更期間請保持頁面開啟。
當出現 Changes pulled successfully 時，開啟 App 預覽，並測試專案中受這些變更影響的部分，以確認一切仍如預期般正常運作。

只有在所選 GitHub 分支包含尚未帶入 Atoms 的變更時，才可使用 Pull Updates。

中斷 GitHub 連接

當您不再希望 Atoms 存取已連接帳號時，請中斷 GitHub 連接。GitHub 儲存庫及其檔案仍會保留在 GitHub 中，但 Atoms 將無法再推送或拉取變更。

GitHub 授權適用於已連接的帳號。撤銷存取權會中斷每一個使用該 GitHub 帳號的 Atoms 專案，因此在繼續之前，請先檢查您的其他專案。

開啟 Settings → Connectors → GitHub。
選取 Disconnect。
在 Disconnect GitHub 確認視窗中，再次選取 Disconnect。
GitHub 應會自動開啟相關授權頁面。如果沒有，請在 GitHub 前往 Settings → Applications → Authorized OAuth Apps。
找到 Atoms，選取其列右側的 ...，然後選取 Revoke。請勿選取 Revoke all；該動作會移除此頁面上列出的每個已授權 OAuth app 的存取權。
依照 Github 所需的任何確認步驟完成操作。
返回 Atoms，重新開啟 GitHub 連接器，確認該帳號已不再連接。