GitHub

# GitHub

使用托管的 OAuth 身份验证访问 GitHub REST API。管理仓库、议题、拉取请求、提交、分支、用户等。

## 快速开始

```bash # Get authenticated user python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/github/user') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```

## 基础 URL

``` https://gateway.maton.ai/github/{native-api-path} ```

将 `{native-api-path}` 替换为实际的 GitHub API 端点路径。网关将请求代理到 `api.github.com` 并自动注入您的 OAuth 令牌。

## 身份验证

所有请求都需要在 Authorization 头中包含 Maton API 密钥：

``` Authorization: Bearer $MATON_API_KEY ```

**环境变量：** 将您的 API 密钥设置为 `MATON_API_KEY`：

```bash export MATON_API_KEY="YOUR_API_KEY" ```

### 获取您的 API 密钥

1. 登录或在 [maton.ai](https://maton.ai) 创建账户 2. 前往 [maton.ai/settings](https://maton.ai/settings) 3. 复制您的 API 密钥

## 连接管理

在 `https://ctrl.maton.ai` 管理您的 GitHub OAuth 连接。

### 列出连接

```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=github&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```

### 创建连接

```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'github'}).encode() req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```

### 获取连接

```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```

**响应：** ```json { "connection": { "connection_id": "83e7c665-60f6-4a64-816c-5e287ea8982f", "status": "ACTIVE", "creation_time": "2026-02-06T03:00:43.860014Z", "last_updated_time": "2026-02-06T03:01:06.027323Z", "url": "https://connect.maton.ai/?session_token=...", "app": "github", "metadata": {} } } ```

在浏览器中打开返回的 `url` 以完成 OAuth 授权。

### 删除连接

```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```

### 指定连接

如果您有多个 GitHub 连接，请使用 `Maton-Connection` 头指定要使用的连接：

```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/github/user') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '83e7c665-60f6-4a64-816c-5e287ea8982f') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```

如果省略，网关将使用默认（最早）的活跃连接。

## API 参考

### 用户

#### 获取已认证用户

```bash GET /github/user ```

#### 根据用户名获取用户

```bash GET /github/users/{username} ```

#### 列出用户

```bash GET /github/users?since={user_id}&per_page=30 ```

### 仓库

#### 列出用户仓库

```bash GET /github/user/repos?per_page=30&sort=updated ```

查询参数：`type`（all, owner, public, private, member）、`sort`（created, updated, pushed, full_name）、`direction`（asc, desc）、`per_page`、`page`

#### 列出组织仓库

```bash GET /github/orgs/{org}/repos?per_page=30 ```

#### 获取仓库

```bash GET /github/repos/{owner}/{repo} ```

#### 创建仓库（用户）

```bash POST /github/user/repos Content-Type: application/json

{ "name": "my-new-repo", "description": "A new repository", "private": true, "auto_init": true } ```

#### 创建仓库（组织）

```bash POST /github/orgs/{org}/repos Content-Type: application/json

{ "name": "my-new-repo", "description": "A new repository", "private": true } ```

#### 更新仓库

```bash PATCH /github/repos/{owner}/{repo} Content-Type: application/json

{ "description": "Updated description", "has_issues": true, "has_wiki": false } ```

#### 删除仓库

```bash DELETE /github/repos/{owner}/{repo} ```

### 仓库内容

#### 列出内容

```bash GET /github/repos/{owner}/{repo}/contents/{path} ```

#### 获取文件内容

```bash GET /github/repos/{owner}/{repo}/contents/{path}?ref={branch} ```

#### 创建或更新文件

```bash PUT /github/repos/{owner}/{repo}/contents/{path} Content-Type: application/json

{ "message": "Create new file", "content": "SGVsbG8gV29ybGQh", "branch": "main" } ```

注意：`content` 必须经过 Base64 编码。

#### 删除文件

```bash DELETE /github/repos/{owner}/{repo}/contents/{path} Content-Type: application/json

{ "message": "Delete file", "sha": "{file_sha}", "branch": "main" } ```

### 分支

#### 列出分支

```bash GET /github/repos/{owner}/{repo}/branches?per_page=30 ```

#### 获取分支

```bash GET /github/repos/{owner}/{repo}/branches/{branch} ```

#### 重命名分支

```bash POST /github/repos/{owner}/{repo}/branches/{branch}/rename Content-Type: application/json

{ "new_name": "new-branch-name" } ```

#### 合并分支

```bash POST /github/repos/{owner}/{repo}/merges Content-Type: application/json

{ "base": "main", "head": "feature-branch", "commit_message": "Merge feature branch" } ```

### 提交

#### 列出提交

```bash GET /github/repos/{owner}/{repo}/commits?per_page=30 ```

查询参数：`sha`（分支名或提交 SHA）、`path`（文件路径）、`author`、`committer`、`since`、`until`、`per_page`、`page`

#### 获取提交

```bash GET /github/repos/{owner}/{repo}/commits/{ref} ```

#### 比较两个提交

```bash GET /github/repos/{owner}/{repo}/compare/{base}...{head} ```

### 议题

#### 列出仓库议题

```bash GET /github/repos/{owner}/{repo}/issues?state=open&per_page=30 ```

查询参数：`state`（open, closed, all）、`labels`、`assignee`、`creator`、`mentioned`、`sort`、`direction`、`since`、`per_page`、`page`

#### 获取议题

```bash GET /github/repos/{owner}/{repo}/issues/{issue_number} ```

#### 创建议题

```bash POST /github/repos/{owner}/{repo}/issues Content-Type: application/json

{ "title": "Found a bug", "body": "Bug description here", "labels": ["bug"], "assignees": ["username"] } ```

#### 更新议题

```bash PATCH /github/repos/{owner}/{repo}/issues/{issue_number} Content-Type: application/json

{ "state": "closed", "state_reason": "completed" } ```

#### 锁定议题

```bash PUT /github/repos/{owner}/{repo}/issues/{issue_number}/lock Content-Type: application/json

{ "lock_reason": "resolved" } ```

#### 解锁议题

```bash DELETE /github/repos/{owner}/{repo}/issues/{issue_number}/lock ```

### 议题评论

#### 列出议题评论

```bash GET /github/repos/{owner}/{repo}/issues/{issue_number}/comments?per_page=30 ```

#### 创建议题评论

```bash POST /github/repos/{owner}/{repo}/issues/{issue_number}/comments Content-Type: application/json

{ "body": "This is a comment" } ```

#### 更新议题评论

```bash PATCH /github/repos/{owner}/{repo}/issues/comments/{comment_id} Content-Type: application/json

{ "body": "Updated comment" } ```

#### 删除议题评论

```bash DELETE /github/repos/{owner}/{repo}/issues/comments/{comment_id} ```

### 标签

#### 列出标签

```bash GET /github/repos/{owner}/{repo}/labels?per_page=30 ```

#### 创建标签

```bash POST /github/repos/{owner}/{repo}/labels Content-Type: application/json

{ "name": "priority:high", "color": "ff0000", "description": "High priority issues" } ```

### 里程碑

#### 列出里程碑

```bash GET /github/repos/{owner}/{repo}/milestones?state=open&per_page=30 ```

#### 创建里程碑

```bash POST /github/repos/{owner}/{repo}/milestones Content-Type: application/json

{ "title": "v1.0", "state": "open", "description": "First release", "due_on": "2026-03-01T00:00:00Z" } ```

### 拉取请求

#### 列出拉取请求

```bash GET /github/repos/{owner}/{repo}/pulls?state=open&per_page=30 ```

查询参数：`state`（open, closed, all）、`head`、`base`、`sort`、`direction`、`per_page`、`page`

#### 获取拉取请求

```bash GET /github/repos/{owner}/{repo}/pulls/{pull_number} ```

#### 创建拉取请求

```bash POST /github/repos/{owner}/{repo}/pulls Content-Type: application/json

{ "title": "New feature", "body": "Description of changes", "head": "feature-branch", "base": "main", "draft": false } ```

#### 更新拉取请求

```bash PATCH /github/repos/{owner}/{repo}/pulls/{pull_number} Content-Type: application/json

{ "title": "Updated title", "state": "closed" } ```

#### 列出拉取请求提交

```bash GET /github/repos/{owner}/{repo}/pulls/{pull_number}/commits?per_page=30 ```

#### 列出拉取请求文件

```bash GET /github/repos/{owner}/{repo}/pulls/{pull_number}/files?per_page=30 ```

#### 检查是否已合并

```bash GET /github/repos/{owner}/{repo}/pulls/{pull_number}/merge ```

#### 合并拉取请求

```bash PUT /github/repos/{owner}/{repo}/pulls/{pull_number}/merge Content-Type: application/json

{ "commit_title": "Merge pull request", "merge_method": "squash" } ```

合并方式：`merge`、`squash`、`rebase`

### 拉取请求审查

#### 列出审查

```bash GET /github/repos/{owner}/{repo}/pulls/{pull_number}/reviews?per_page=30 ```

#### 创建审查

```bash POST /github/repos/{owner}/{repo}/pulls/{pull_number}/reviews Content-Type: application/json

{ "body": "Looks good!", "event": "APPROVE" } ```

事件：`APPROVE`、`REQUEST_CHANGES`、`COMMENT`

### 搜索

#### 搜索仓库

```bash GET /github/search/repositories?q={query}&per_page=30 ```

查询示例： - `tetris+language:python` - 包含 "tetris" 的 Python 仓库 - `react+stars:>10000` - 包含 "react" 且有 10k+ stars 的仓库

#### 搜索议题

```bash GET /github/search/issues?q={query}&per_page=30 ```

查询示例： - `bug+is:open+is:issue` - 包含 "bug" 的开放议题 - `author:username+is:pr` - 特定作者的拉取请求

#### 搜索代码

```bash GET /github/search/code?q={query}&per_page=30 ```

查询示例： - `addClass+repo:facebook/react` - 在特定仓库中搜索 "addClass" - `function+extension:js` - JavaScript 函数

注意：范围广泛的查询可能会导致代码搜索超时。

#### 搜索用户

```bash GET /github/search/users?q={query}&per_page=30 ```

### 组织

#### 列出用户的组织

```bash GET /github/user/orgs?per_page=30 ```

注意：需要 `read:org` 权限范围。

#### 获取组织

```bash GET /github/orgs/{org} ```

#### 列出组织成员

```bash GET /github/orgs/{org}/members?per_page=30 ```

### 速率限制

#### 获取速率限制

```bash GET /github/rate_limit ```

响应： ```json { "rate": { "limit": 5000, "remaining": 4979, "reset": 1707200000 }, "resources": { "core": { "limit": 5000, "remaining": 4979 }, "search": { "limit": 30, "remaining": 28 } } } ```

## 分页

GitHub 使用基于页面和基于链接的分页：

```bash GET /github/repos/{owner}/{repo}/issues?per_page=30&page=2 ```

响应头包含分页链接： - `Link: <url>; rel="next", <url>; rel="last"`

常见分页参数： - `per_page`：每页结果数（最多 100，默认 30） - `page`：页码（默认 1）

某些端点使用基于游标的分页和 `since` 参数（例如列出用户）。

## 代码示例

### JavaScript

```javascript const response = await fetch( 'https://gateway.maton.ai/github/repos/owner/repo/issues?state=open&per_page=10', { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` } } ); const issues = await response.json(); ```

### Python

```python import os import requests

response = requests.get( 'https://gateway.maton.ai/github/repos/owner/repo/issues', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}, params={'state': 'open', 'per_page': 10} ) issues = response.json() ```

## 注意事项

- 仓库名称不区分大小写，但 API 会保留原始大小写 - 议题编号和 PR 编号在每个仓库中共用同一序列 - 创建/更新文件时，内容必须经过 Base64 编码 - 速率限制：认证用户每小时 5000 次请求，搜索每分钟 30 次 - 非常广泛的搜索查询可能会超时 - 某些端点需要特定的 OAuth 权限范围（例如，组织操作需要 `read:org`）。如果您收到权限范围错误，请联系 Maton 支持 ([email protected])，告知您需要的具体操作/API 以及您的使用场景 - 重要：使用 curl 命令时，如果 URL 包含括号，请使用 `curl -g` 以禁用 glob 解析 - 重要：将 curl 输出通过管道传递给 `jq` 或其他命令时，在某些 shell 环境中，像 `$MATON_API_KEY` 这样的环境变量可能无法正确展开

## 错误处理

| 状态 | 含义 | |--------|---------| | 400 | 缺少 GitHub 连接 | | 401 | Maton API 密钥无效或缺失 | | 403 | 禁止访问 - 权限或范围不足 | | 404 | 资源未找到 | | 408 | 请求超时（常见于复杂搜索） | | 422 | 验证失败 | | 429 | 达到速率限制 | | 4xx/5xx | 来自 GitHub API 的透传错误 |

### 故障排除：API 密钥问题

1. 检查是否设置了 `MATON_API_KEY` 环境变量：

```bash echo $MATON_API_KEY ```

2. 通过列出连接来验证 API 密钥是否有效：

```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```

### 故障排除：应用名称无效

1. 确保您的 URL 路径以 `github` 开头。例如：

- 正确：`https://gateway.maton.ai/github/user` - 错误：`https://gateway.maton.ai/api.github.com/user`

## 资源

- [GitHub REST API 文档](https://docs.github.com/en/rest) - [仓库 API](https://docs.github.com/en/rest/repos/repos) - [议题 API](https://docs.github.com/en/rest/issues/issues) - [拉取请求 API](https://docs.github.com/en/rest/pulls/pulls) - [搜索 API](https://docs.github.com/en/rest/search/search) - [速率限制](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting) - [Maton 社区](https://discord.com/invite/dBfFAcefs2) - [Maton 支持](mailto:[email protected])