Sentinel Documentation

Appearance

仓库 API ​

代码仓库管理相关的 API 端点。

端点概览 ​

方法端点描述认证
POST/projects/{id}/repositories/imports/github导入 GitHub 仓库✅
GET/projects/{id}/repositories仓库列表✅
GET/repositories/{id}仓库详情✅
PATCH/repositories/{id}更新仓库设置✅

导入 GitHub 仓库 ​

POST /api/v1/projects/{id}/repositories/imports/github ​

将 GitHub 仓库导入到项目中。

请求 ​

http
POST /api/v1/projects/550e8400-e29b-41d4-a716-446655440000/repositories/imports/github
Authorization: Bearer <token>
Content-Type: application/json

{
  "external_id": "123456789",
  "installation_id": 12345678,
  "owner": "octocat",
  "name": "Hello-World",
  "clone_url": "https://github.com/octocat/Hello-World.git",
  "default_branch": "main",
  "visibility": "public",
  "enabled": true,
  "review_on_push": true,
  "review_on_pull_request": true
}

参数说明:

字段类型必填说明
external_idstring❌GitHub 仓库 ID
installation_idinteger❌GitHub App 安装 ID
ownerstring✅仓库所有者
namestring✅仓库名称
clone_urlstring✅Git 克隆 URL
default_branchstring✅默认分支
visibilitystring✅可见性
enabledboolean❌是否启用（默认 true）
review_on_pushboolean❌Push 时自动审查（默认 false）
review_on_pull_requestboolean❌PR 时自动审查（默认 false）

可见性值:

  • public - 公开
  • private - 私有
  • internal - 内部

响应 ​

成功 (201 Created):

json
{
  "repository_id": "650e8400-e29b-41d4-a716-446655440000",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "provider": "github",
  "external_id": "123456789",
  "installation_id": 12345678,
  "owner": "octocat",
  "name": "Hello-World",
  "full_name": "octocat/Hello-World",
  "clone_url": "https://github.com/octocat/Hello-World.git",
  "default_branch": "main",
  "visibility": "public",
  "enabled": true,
  "review_on_push": true,
  "review_on_pull_request": true,
  "created_at": "2024-01-01T12:00:00Z",
  "updated_at": "2024-01-01T12:00:00Z"
}

错误响应:

  • 400 Bad Request: 参数验证失败
  • 404 Not Found: 项目不存在
  • 409 Conflict: 仓库已存在

示例 ​

typescript
const importRepository = async (
  projectId: string,
  repoData: {
    owner: string;
    name: string;
    clone_url: string;
    default_branch: string;
    visibility: string;
  }
) => {
  const response = await fetch(
    `/api/v1/projects/${projectId}/repositories/imports/github`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(repoData),
    }
  );
  
  return response.json();
};

仓库列表 ​

GET /api/v1/projects/{id}/repositories ​

获取项目下的所有仓库。

请求 ​

http
GET /api/v1/projects/550e8400-e29b-41d4-a716-446655440000/repositories?limit=20&offset=0
Authorization: Bearer <token>

查询参数:

参数类型默认值说明
limitinteger20每页数量
offsetinteger0偏移量

响应 ​

成功 (200 OK):

json
{
  "repositories": [
    {
      "repository_id": "650e8400-e29b-41d4-a716-446655440000",
      "project_id": "550e8400-e29b-41d4-a716-446655440000",
      "provider": "github",
      "external_id": "123456789",
      "installation_id": 12345678,
      "owner": "octocat",
      "name": "Hello-World",
      "full_name": "octocat/Hello-World",
      "clone_url": "https://github.com/octocat/Hello-World.git",
      "default_branch": "main",
      "visibility": "public",
      "enabled": true,
      "review_on_push": true,
      "review_on_pull_request": true,
      "created_at": "2024-01-01T12:00:00Z",
      "updated_at": "2024-01-01T12:00:00Z"
    }
  ],
  "total": 1
}

示例 ​

typescript
const listRepositories = async (projectId: string, limit = 20, offset = 0) => {
  const response = await fetch(
    `/api/v1/projects/${projectId}/repositories?limit=${limit}&offset=${offset}`,
    {
      headers: { 'Authorization': `Bearer ${token}` },
    }
  );
  
  return response.json();
};

仓库详情 ​

GET /api/v1/repositories/{id} ​

获取仓库的详细信息。

请求 ​

http
GET /api/v1/repositories/650e8400-e29b-41d4-a716-446655440000
Authorization: Bearer <token>

响应 ​

成功 (200 OK):

json
{
  "repository_id": "650e8400-e29b-41d4-a716-446655440000",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "provider": "github",
  "external_id": "123456789",
  "installation_id": 12345678,
  "owner": "octocat",
  "name": "Hello-World",
  "full_name": "octocat/Hello-World",
  "clone_url": "https://github.com/octocat/Hello-World.git",
  "default_branch": "main",
  "visibility": "public",
  "enabled": true,
  "review_on_push": true,
  "review_on_pull_request": true,
  "created_at": "2024-01-01T12:00:00Z",
  "updated_at": "2024-01-01T12:00:00Z"
}

错误响应:

  • 404 Not Found: 仓库不存在或无权访问

更新仓库设置 ​

PATCH /api/v1/repositories/{id} ​

更新仓库配置。

请求 ​

http
PATCH /api/v1/repositories/650e8400-e29b-41d4-a716-446655440000
Authorization: Bearer <token>
Content-Type: application/json

{
  "enabled": true,
  "review_on_push": false,
  "review_on_pull_request": true,
  "default_branch": "develop"
}

参数说明:

字段类型必填说明
enabledboolean❌是否启用仓库
review_on_pushboolean❌Push 时自动审查
review_on_pull_requestboolean❌PR 时自动审查
default_branchstring❌默认分支
external_idstring❌外部 ID
installation_idinteger❌安装 ID
clone_urlstring❌克隆 URL
visibilitystring❌可见性

说明:

  • 至少提供一个字段
  • enabled 为 false 时不会触发自动审查

响应 ​

成功 (200 OK):

返回更新后的仓库对象，字段同仓库详情。

错误响应:

  • 400 Bad Request: 参数验证失败
  • 404 Not Found: 仓库不存在

示例 ​

typescript
const updateRepository = async (
  repositoryId: string,
  updates: {
    enabled?: boolean;
    review_on_push?: boolean;
    review_on_pull_request?: boolean;
  }
) => {
  const response = await fetch(`/api/v1/repositories/${repositoryId}`, {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(updates),
  });
  
  return response.json();
};

数据模型 ​

Repository 对象 ​

typescript
interface Repository {
  repository_id: string;           // UUID
  project_id: string;              // 所属项目 ID
  provider: 'github';              // 代码托管平台
  external_id?: string;            // 平台上的仓库 ID
  installation_id?: number;        // GitHub App 安装 ID
  owner: string;                   // 仓库所有者
  name: string;                    // 仓库名称
  full_name: string;               // 完整名称 (owner/name)
  clone_url: string;               // Git 克隆 URL
  default_branch: string;          // 默认分支
  visibility: 'public' | 'private' | 'internal';
  enabled: boolean;                // 是否启用
  review_on_push: boolean;         // Push 时自动审查
  review_on_pull_request: boolean; // PR 时自动审查
  created_at: string;              // 创建时间
  updated_at: string;              // 更新时间
}

自动审查配置 ​

Push 触发 ​

当 review_on_push 为 true 时：

  • 代码 Push 到默认分支触发审查
  • 通过 GitHub Webhook 自动创建分析任务
  • 任务类型默认为 code_review

PR 触发 ​

当 review_on_pull_request 为 true 时：

  • 创建或更新 PR 时触发审查
  • 自动比较 base 和 head 分支
  • 任务类型默认为 code_review
  • 结果可以作为 PR 评论发布（计划中）

禁用仓库 ​

设置 enabled: false 会：

  • 停止所有自动触发
  • 仍可手动创建分析任务
  • 不影响历史分析记录

最佳实践 ​

1. 批量导入 ​

typescript
const importMultipleRepos = async (projectId: string, repos: any[]) => {
  const results = await Promise.allSettled(
    repos.map(repo => importRepository(projectId, repo))
  );
  
  const succeeded = results.filter(r => r.status === 'fulfilled');
  const failed = results.filter(r => r.status === 'rejected');
  
  return { succeeded, failed };
};

2. 配置管理 ​

typescript
// 批量启用自动审查
const enableAutoReview = async (projectId: string) => {
  const { repositories } = await listRepositories(projectId);
  
  await Promise.all(
    repositories.map(repo =>
      updateRepository(repo.repository_id, {
        review_on_push: true,
        review_on_pull_request: true,
      })
    )
  );
};

3. 仓库同步 ​

typescript
// 从 GitHub 同步仓库信息
const syncRepository = async (
  repositoryId: string,
  githubData: { default_branch: string; visibility: string }
) => {
  return updateRepository(repositoryId, {
    default_branch: githubData.default_branch,
    visibility: githubData.visibility,
  });
};

相关端点 ​

相关文档 ​

Released under the MIT License.

Copyright © 2024-present Sentinel