---
author: OOMOL
author_url: https://oomol.com/zh-cn/about/
title: 为 OpenConnector 创建 GitHub OAuth app
description: 创建 GitHub OAuth app，配置 callback URL，并把 GitHub 连接到自部署的 OOMOL
  OpenConnector runtime。
lang: zh-CN
canonical_url: https://oomol.com/zh-cn/docs/openconnector-github-oauth-app/
markdown_url: https://oomol.com/zh-cn/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`。 |