---
title: 為 OpenConnector 建立 GitHub OAuth app
description: 建立 GitHub OAuth app、設定 callback URL，並將 GitHub 連接到自部署的 OOMOL
  OpenConnector runtime。
lang: zh-TW
canonical_url: https://oomol.com/zh-tw/docs/openconnector-github-oauth-app/
markdown_url: https://oomol.com/zh-tw/docs/openconnector-github-oauth-app.md
---

# 為 OpenConnector 建立 GitHub OAuth app

當 OpenConnector 需要使用者授權的 GitHub 連線時，使用 GitHub OAuth app。OAuth app 提供瀏覽器授權流程；personal access token 適合由管理員手動設定 token 的情境。

## OpenConnector service

| Service ID | Provider | Auth type |
| --- | --- | --- |
| `github` | GitHub | OAuth2 |

OpenConnector 的 GitHub OAuth provider 可能請求 `read:user`、`user:email`、`repo`、`workflow` 和 `delete_repo` 等 scopes。只授予你計畫執行的 actions 所需的 scopes。

## 前置條件

- 一個正在運行的 OpenConnector runtime。
- 一個可以建立 OAuth apps 的 GitHub 帳號或 organization。
- 使用者在瀏覽器中開啟的 OpenConnector origin，例如 `http://localhost:3000` 或 `https://connect.example.com`。

## 第 1 步：確定 OpenConnector callback URL

在 OpenConnector origin 後拼接 `/oauth/callback`，得到 callback URL。本地測試使用 `http://localhost:3000/oauth/callback`。公開部署時，請先設定 `OOMOL_CONNECT_ORIGIN`，重啟 OpenConnector 後使用公開 callback URL，例如 `https://connect.example.com/oauth/callback`。

## 第 2 步：註冊 GitHub OAuth app

在 GitHub 中：

1. 開啟 **Settings**。
2. 開啟 **Developer settings**。
3. 開啟 **OAuth Apps**。
4. 選擇 **New OAuth App**。
5. 填寫 app name 和 homepage URL。
6. 將 **Authorization callback URL** 設定為 OpenConnector 的準確 callback URL。
7. 註冊 app。

GitHub 官方文件見 [Creating an OAuth app](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app)。GitHub OAuth app 只有一個 authorization callback URL；如果 local、staging 和 production 使用不同 callback URL，建議建立多個 app。

## 第 3 步：複製 client credentials

從 GitHub OAuth app 頁面複製：

| GitHub 欄位 | OpenConnector 欄位 |
| --- | --- |
| Client ID | `clientId` |
| Client secret | `clientSecret` |

## 第 4 步：在 OpenConnector 中儲存 GitHub client

優先使用 OpenConnector Web 控制台：

1. 開啟 OpenConnector Web 控制台，例如 `http://localhost:3000`。
2. 開啟 **Providers**，選擇 **GitHub**。
3. 點擊 **Configure OAuth Client** 或 **Edit OAuth Client**。
4. 貼上 GitHub client ID 和 client secret。
5. 點擊 **Save OAuth Client**。

## 第 5 步：連接並測試

儲存 OAuth client 後，在 GitHub provider 頁面點擊 **Connect**。批准 GitHub OAuth app，回到 OpenConnector，並確認 provider 頁面顯示帳號已連接。

可在控制台 action 列表中執行 `github.get_current_user` 做低風險測試。

## 排查建議

| 現象 | 檢查項 |
| --- | --- |
| Redirect URI mismatch | GitHub 的 authorization callback URL 必須和 `<openconnector-origin>/oauth/callback` 完全一致。 |
| 授權到了錯誤帳號 | 開始授權前登出 GitHub，或使用乾淨的瀏覽器 profile。 |
| Repo actions 失敗 | 連接可能沒有 `repo` scope，或使用者沒有目標 repository 的存取權限。 |
| Workflow actions 失敗 | 連接可能沒有 `workflow` scope。調整 requested scopes 後重新連接。 |
| Delete actions 失敗 | 除非明確需要刪除 repository，否則不要授予 `delete_repo`。 |