PCIT API

PCIT API 遵循 REST 标准进行设计。

我们的 API 是 可预期的 以及 面向资源 的,接受 JSON-encoded 请求正文,返回 JSON-encoded 响应, 使用标准的 HTTP 响应代码。

所有请求和响应的编码均为 UTF-8。

调用说明

请求

所有的请求方式(Method)均与动词相关:

  • GET:获取资源
  • POST:创建资源
  • PUT:更新资源
  • PATCH:更新资源的一个属性
  • DELETE:删除资源
  • OPTIONS:获取客户端能对资源做什么操作的信息

参数传入方式

如无特别说明,GET 请求参数需要放到 Url Query String 中:

GET https://ci.khs1994.com/api/builds?pagesize=20

POST/PUT/PATCH 请求参数建议使用 JSON 格式将参数放到请求体中:

PUT https://ci.khs1994.com/api/v1/pets/1
Content-Type: application/json
{
  "a": 1,
  "obj": {
    "a": "string",
    "id": 1
  },
  "array": [
    "a",
    "b"
  ]
}

响应

成功响应中包含实体资源内容,如:

[
  {
    "a": "xxx",
    "b": "xxx"
  },
  {
    "c": "xxx",
    "d": "xxx"
   }
]

认证

Generated API Access Token

To authenticate against the PCIT API, you need an API access token generated by the PCIT command line client or website profile.

要想访问 API 资源,必须首先生成密钥,之后将密钥附加到请求头中。

From CLI

使用 CLI 获取密钥


$ pcit login -u YOUR_NAME -p YOUR_PASSWOD -e https://ci.domain.com

$ pcit token

Your access token is XXXXX

From Website

在网页获取密钥

Login https://ci.khs1994.com/login or https://ci.domain.com/login, Then find API access token from profile.

Access API Via Tokens

Include the token in the Authorization header of each request to https://ci.khs1994.com/api or https://ci.domain.com/api

$ curl -H "Authorization: token xxxxxxxxxxxx" \
     https://ci.khs1994.com/api/user

请求限制

为了防止拒绝服务攻击,PCIT API 制定了一定的限流策略,规则如下:

  • 访问令牌无效的请求,每分钟可请求 10 次
  • 访问令牌有效的请求,每分钟可请求 300 次

为了方便您查询当前限流的情况,你可通过响应的 Header 的 Rate Limit 参数查看,参数如下:

  • X-RateLimit-Remaining: 剩余可请求数量
  • X-RateLimit-Limit:限制可请求数量
  • X-Ratelimit-Reset: 重置限制次数时间(秒)
  • X-Ratelimit-Retry-After:触达限流后需要等待重置的时间(秒)

范例:

X-RateLimit-Remaining: 298
X-RateLimit-Limit: 300
X-Ratelimit-Reset: 580

超出限流限制会返回如下错误:

Header:
X-RateLimit-Remaining: 0
X-RateLimit-Limit: 300
X-Ratelimit-Reset: 230
X-Ratelimit-Retry-After: 360

{
  "message": "操作过于频繁,请稍后再试。"
}

错误

PCIT API 使用标准 HTTP 响应码(Status Code)来表示 API 请求。

通常,状态码:

  • 2xx 代表成功响应
  • 4xx 代表失败响应,并给出失败原因
  • 5xx 代表 PCIT 服务端内部错误

状态码说明

状态码描述
200更新/获取资源成功
201创建资源成功
204删除资源成功
400业务错误,具体参见下放业务错误代码
401认证失败,请返回 认证 检查参数是否有误
403无权限调用接口,如:未开通 API 功能
404资源不存在
405接口请求方式 Method 有误
422请求参数校验失败
429触达限流限制
500服务器应用发生了错误
502服务器无法连接
503服务器暂不可用
504服务器连接超时

业务错误说明

状态码 4xx 的业务错误可通过编码来分别处理不同的处理逻辑,响应将通过 JSON 形式返回,其中包括业务错误码 code 和错误原因 message,例如:

{
  "code": 3001,
  "type": "ERROR",
  "message": "用户名已被占用,请更改后重新提交"
}

业务错误码 code 说明如下:

  • 状态码 400
错误码描述
3000用户名或密码错误
3001用户名已被占用,请更改后重新提交
  • 状态码 422
错误码描述
2000categoryId 必填
2001categoryId 必须为 int
2002petId 必须为整数
2003pagesize 必须大于 0
2004status 不存在,必须为 placed, approevd, delivered 其中之一
2005password 必填

版本

在极少数情况下,我们需要针对某些接口做一些破坏性的修改,为了尽量避免破坏向后兼容性,我们通过修改接口版本号来实现多版本共存,不去破坏上一版本的接口参数及逻辑,以新版本接口的形式提供同一接口不同请求或返回形式。

例如,/api/v1/builds 升级后将变成 /api/v2/builds

字段类型

在文档中,我们将使用许多不同类型的数据。您可以在下方的说明列表找到它们的解释及含义。

类型定义范例
int整数,不带小数的数字。1234
float浮点数,带小数的数字。1234.12
string字符串是用于表示文本的字符序列。"CODING"
boolean布尔值,是 truefalse 中的一个,所对应的关系就是真与假的概念。true
time表示日期和时间的字符串。"2017-09-10 12:23:01"
array列表,该列表为数组,数组中的每一项的类型由中括号内的字段类型决定。["CODING", "VERY", "GOOD"]
object资源,可从对应的资源 XX 对象中找到。{"id": 1,"name": "NPC小明"}
API REFERENCE

Builds

list builds

This returns a list of builds for the current user. The result is paginated. The default limit is 100.

get/builds
响应 Response
状态码 200

参数

  • array

    build list

    • 数组成员object
    • idint

      builds id

    • branchstring

      trigger branch

    • commit_idstring

      commit sha

    • tagstring

      tag name

    • commit_messagestring

      commit message

    • comparestring

      compare url

    • commiter_namestring

      committer name

    • committer_usernamestring

      committer username

    • build_statusstring

      build status

    • event_typestring

      event type

    • pull_request_numberint

      pull request number

Example 1

成功示例

success
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
[
  {
    "id": "112",
    "branch": "gh-pages",
    "commit_id": "0fa67f2b1c0d59998b71035b402849f5075a3c60",
    "tag": null,
    "commit_message": "Deploy Git by PCIT https://ci.khs1994.com",
    "compare": "https://github.com/pcit-ce/pcit/compare/d492689de936...0fa67f2b1c0d",
    "committer_name": "pcit-ce",
    "committer_username": "pcit-deploy-robot",
    "build_status": "misconfigured",
    "event_type": "push",
    "pull_request_number": null
  },
  {
    "id": "111",
    "branch": "master",
    "commit_id": "f807efaa677757682aa7a3f226d3e799086e90dd",
    "tag": null,
    "commit_message": "Support actions\n\nSigned-off-by: Kang HuaiShuai",
    "compare": "https://github.com/pcit-ce/pcit/compare/6746c883155e...f807efaa6777",
    "committer_name": "Kang HuaiShuai",
    "committer_username": "khs1994",
    "build_status": "queued",
    "event_type": "push",
    "pull_request_number": null
  }
]

find builds By Repo

This returns a list of builds for an individual repository. The result is paginated. Each request will return 25 results.

get/repo/{git_type}/{username}/{repo.name}/builds
请求 Request

路由参数

  • git_typestring
  • usernamestring
  • repo.namestring
响应 Response
状态码 200

参数

  • array

    repo build list

    • 数组成员object
    • idint

      builds id

    • branchstring

      trigger branch

    • commit_idstring

      commit sha

    • tagstring

      tag name

    • commit_messagestring

      commit message

    • comparestring

      compare url

    • commiter_namestring

      committer name

    • committer_usernamestring

      committer username

    • build_statusstring

      build status

    • event_typestring

      event type

    • pull_request_numberint

      pull request number

    • created_atint

      created time

    • finished_atint

      finished time

Example 1

成功示例

success
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
[
  {
    "id": "112",
    "branch": "gh-pages",
    "commit_id": "0fa67f2b1c0d59998b71035b402849f5075a3c60",
    "tag": null,
    "commit_message": "Deploy Git by PCIT https://ci.khs1994.com",
    "compare": "https://github.com/pcit-ce/pcit/compare/d492689de936...0fa67f2b1c0d",
    "committer_name": "pcit-ce",
    "committer_username": "pcit-deploy-robot",
    "build_status": "misconfigured",
    "event_type": "push",
    "pull_request_number": null,
    "created_at": "1577892876",
    "finished_at": null
  },
  {
    "id": "111",
    "branch": "master",
    "commit_id": "f807efaa677757682aa7a3f226d3e799086e90dd",
    "tag": null,
    "commit_message": "Support actions\n\nSigned-off-by: Kang HuaiShuai",
    "compare": "https://github.com/pcit-ce/pcit/compare/6746c883155e...f807efaa6777",
    "committer_name": "Kang HuaiShuai",
    "committer_username": "khs1994",
    "build_status": "queued",
    "event_type": "push",
    "pull_request_number": null,
    "created_at": "1577892253",
    "finished_at": null
  }
]

find builds By Repo Current

find builds by repo current

get/repo/{git_type}/{username}/{repo.name}/build/current
请求 Request

路由参数

  • git_typestring
  • usernamestring
  • repo.namestring
响应 Response
状态码 200

参数

  • idint

    build id

  • git_typestring

    git type

  • ridint

    repo id

  • event_typestring

    event type

  • build_statusstring

    build status

  • branchstring

    branch

  • tagstring

    tag name

  • pull_request_titlestring

    pull request title

  • pull_request_numberint

    pull request number

  • pull_request_sourcestring

    pull request source repo

  • comparestring

    compare url

  • commit_idstring

    commit sha

  • commit_messagestring

    commit message

  • committer_uidint

    committer uid

  • committer_namestring

    committer name

  • committer_usernamestring

    committer username

  • committer_emailstring

    committer email

  • committer_picstring

    committer pic

  • author_uidint

    author uid

  • author_namestring

    author name

  • author_usernamestring

    author username

  • author_emailstring

    author email

  • author_picstring

    author pic

  • created_atint

    create time

  • finished_atint

    finish time

  • deleted_atint

    delete time

  • configstring

    pcit config string

  • actionstring

    action

  • check_suites_idint

    check suites id

  • internalint

    internal

  • privateboolean

    is private

  • unique_keystring

    unique key

  • jobsarray
    • 数组成员object
    • jobs.idint

      job id

    • jobs.allow_failureboolean

      allow_failure

    • jobs.statestring

      job state

    • jobs.started_atint

      starte time

    • jobs.finished_atint

      finish time

    • jobs.created_atint

      create time

    • jobs.updated_atint

      update time

    • jobs.deleted_atint

      delete time

    • jobs.build_idint

      job build id

    • jobs.build_logstring

      build log

    • jobs.check_run_idint

      github check run id

    • jobs.configstring

      config

    • jobs.env_varsstring

      env vars

    • jobs.container_configstring

      container config

Example 1

成功示例

success
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{
  "id": "112",
  "git_type": "github",
  "rid": "119219872",
  "event_type": "push",
  "build_status": "misconfigured",
  "branch": "gh-pages",
  "tag": null,
  "pull_request_title": null,
  "pull_request_number": null,
  "pull_request_source": null,
  "compare": "https://github.com/pcit-ce/pcit/compare/d492689de936...0fa67f2b1c0d",
  "commit_id": "0fa67f2b1c0d59998b71035b402849f5075a3c60",
  "commit_message": "Deploy Git by PCIT https://ci.khs1994.com",
  "committer_uid": null,
  "committer_name": "pcit-ce",
  "committer_username": "pcit-deploy-robot",
  "committer_email": "ci@khs1994.com",
  "committer_pic": null,
  "author_uid": null,
  "author_name": "pcit-ce",
  "author_username": "pcit-deploy-robot",
  "author_email": "ci@khs1994.com",
  "author_pic": null,
  "created_at": "1577892876",
  "finished_at": null,
  "deleted_at": null,
  "config": "[]",
  "action": null,
  "check_suites_id": null,
  "internal": "1",
  "private": "0",
  "unique_key": "0",
  "jobs": []
}

find single build

This returns a single build.

get/build/{build.id}
请求 Request

路由参数

  • build.idint
响应 Response
状态码 200

参数

  • idint

    build id

  • git_typestring

    git type

  • ridint

    repo id

  • event_typestring

    event type

  • build_statusstring

    build status

  • branchstring

    branch

  • tagstring

    tag name

  • pull_request_titlestring

    pull request title

  • pull_request_numberint

    pull request number

  • pull_request_sourcestring

    pull request source repo

  • comparestring

    compare url

  • commit_idstring

    commit sha

  • commit_messagestring

    commit message

  • committer_uidint

    committer uid

  • committer_namestring

    committer name

  • committer_usernamestring

    committer username

  • committer_emailstring

    committer email

  • committer_picstring

    committer pic

  • author_uidint

    author uid

  • author_namestring

    author name

  • author_usernamestring

    author username

  • author_emailstring

    author email

  • author_picstring

    author pic

  • created_atint

    create time

  • finished_atint

    finish time

  • deleted_atint

    delete time

  • configstring

    pcit config string

  • actionstring

    action

  • check_suites_idint

    check suites id

  • internalint

    internal

  • privateboolean

    is private

  • unique_keystring

    unique key

  • jobsarray
    • 数组成员object
    • jobs.idint

      job id

    • jobs.allow_failureboolean

      allow_failure

    • jobs.statestring

      job state

    • jobs.started_atint

      starte time

    • jobs.finished_atint

      finish time

    • jobs.created_atint

      create time

    • jobs.updated_atint

      update time

    • jobs.deleted_atint

      delete time

    • jobs.build_idint

      job build id

    • jobs.build_logstring

      build log

    • jobs.check_run_idint

      github check run id

    • jobs.configstring

      config

    • jobs.env_varsstring

      env vars

    • jobs.container_configstring

      container config

Example 1

成功示例

success
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
{
  "id": "100",
  "git_type": "github",
  "rid": "230709793",
  "event_type": "push",
  "build_status": "success",
  "branch": "master",
  "tag": null,
  "pull_request_title": null,
  "pull_request_number": null,
  "pull_request_source": null,
  "compare": "https://github.com/pcit-plugins/pcit-github-release/compare/3f7567e0fc43...e66c9b3cdabb",
  "commit_id": "e66c9b3cdabb4572339d430f1ee33ae22a93a976",
  "commit_message": "Sync from pcit-ce/pcit@b4a29da40a05e79d646569ef35bd4c97ae5b69a8 by PCIT",
  "committer_uid": null,
  "committer_name": "khs1994",
  "committer_username": "khs1994",
  "committer_email": "khs1994@khs1994.com",
  "committer_pic": null,
  "author_uid": null,
  "author_name": "khs1994",
  "author_username": "khs1994",
  "author_email": "khs1994@khs1994.com",
  "author_pic": null,
  "created_at": "1577627893",
  "finished_at": "1577627957",
  "deleted_at": null,
  "config": "{\"steps\":{\"github_release\":{\"image\":\"pcit\\/github_release\",\"settings\":{\"token\":\"${GITHUB_TOKEN}\",\"files\":[\"Dockerfile\",\"docker-entrypoint.sh\"],\"overwrite\":true,\"draft\":true,\"prerelease\":true,\"note\":\"nightly\",\"title\":\"nightly\",\"target_commitish\":\"refs\\/tags\\/nightly\"}}}}",
  "action": null,
  "check_suites_id": null,
  "internal": "1",
  "private": "0",
  "unique_key": "0",
  "jobs": [
    {
      "id": "131",
      "allow_failure": "0",
      "state": "success",
      "started_at": "1577627938",
      "finished_at": "1577627957",
      "created_at": "1577627936",
      "updated_at": null,
      "deleted_at": null,
      "build_id": "100",
      "build_log": "{\"clone\":\"2019-12-29T13:58:58.902387600Z + git init\\n2019-12-29T13:58:58.922934900Z Initialized empty Git repository in \\/pcit-plugins\\/pcit-github-release\\/.git\\/\\n2019-12-29T13:58:58.922967400Z + git remote add origin https:\\/\\/github.com\\/pcit-plugins\\/pcit-github-release\\n2019-12-29T13:58:58.938822500Z + git fetch --no-tags origin +refs\\/heads\\/master:\\n2019-12-29T13:59:03.221357300Z From https:\\/\\/github.com\\/pcit-plugins\\/pcit-github-release\\n2019-12-29T13:59:03.221376300Z * branch            master     -> FETCH_HEAD\\n2019-12-29T13:59:03.227303300Z  * [new branch]      master     -> origin\\/master\\n2019-12-29T13:59:03.247332400Z + git reset --hard -q e66c9b3cdabb4572339d430f1ee33ae22a93a976\\n2019-12-29T13:59:03.252979000Z + git submodule update --init --recursive\",\"github_release\":\"2019-12-29T13:59:09.247502400Z Release nightly not found\\n2019-12-29T13:59:10.092373700Z Successfully created nightly release\\n2019-12-29T13:59:12.088994500Z Successfully uploaded Dockerfile artifact\\n2019-12-29T13:59:12.821705700Z Successfully uploaded docker-entrypoint.sh artifact\"}",
      "check_run_id": "366809624",
      "config": null,
      "env_vars": "null",
      "container_config": null
    }
  ]
}

cancel build

This cancels a currently running build. It will set the build and associated jobs to "state": canceled.

post/build/{build.id}/cancel
请求 Request

路由参数

  • build.idint
状态码 200

Example 1

成功示例

restart build

This restarts a build that has completed or been canceled.

post/build/{build.id}/restart
请求 Request

路由参数

  • build.idint
状态码 200

Example 1

成功示例

Builds.log

find log

This returns a single build log.

get/job/{job.id}/log
请求 Request

路由参数

  • job.idint
响应 Response
状态码 200

参数

  • stepsstring

    step log

Example 1

成功示例

success
1
2
3
{
  "clone": "2019-12-28T12:50:09.012993700Z + git init\n2019-12-28T12:50:09.048609700Z Initialized empty Git repository in /app/pcit/.git/\n2019-12-28T12:50:09.048638100Z + git remote add origin https://github.com/pcit-ce/pcit\n2019-12-28T12:50:09.064472600Z + git fetch --no-tags --depth=25 origin +refs/heads/master:\n2019-12-28T12:50:17.371708300Z From https://github.com/pcit-ce/pcit\n2019-12-28T12:50:17.371726500Z  * branch master     -> FETCH_HEAD\n2019-12-28T12:50:17.372141600Z  * [new branch] master     -> origin/master\n2019-12-28T12:50:17.377939100Z + git reset --hard -q 41de4b3bd1dba53c4fa55987bad9f57ce91e8f7d\n2019-12-28T12:50:17.433871900Z + git submodule update --init --recursive"
}

delete log

This removes the contents of a log. It gets replace with the message: Log removed at 2017-02-13 16:00:00 UTC.

delete/job/{job.id}/log
请求 Request

路由参数

  • job.idint
状态码 204

Example 1

成功示例

Builds.job

list jobs

This returns a list of jobs a current user has access to.

get/jobs
状态码 200

Example 1

成功示例

find single job

This returns a single job.

get/job/{job.id}
请求 Request

路由参数

  • job.idint
响应 Response
状态码 200

参数

  • idint

    job id

  • allow_failureboolean

    allow_failure

  • statestring

    job state

  • started_atint

    starte time

  • finished_atint

    finish time

  • created_atint

    create time

  • updated_atint

    update time

  • deleted_atint

    delete time

  • build_idint

    job build id

  • build_logstring

    build log

  • check_run_idint

    github check run id

  • configstring

    config

  • env_varsstring

    env vars

  • container_configstring

    container config

Example 1

成功示例

successful operation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "id": "100",
  "allow_failure": "0",
  "state": "success",
  "started_at": "1577537406",
  "finished_at": "1577537724",
  "created_at": "1577537046",
  "updated_at": null,
  "deleted_at": null,
  "build_id": "52",
  "build_log": "log string",
  "check_run_id": "366020520",
  "config": null,
  "env_vars": "{\"PHP_VERSION\":\"7.2.24\",\"NGINX_VERSION\":\"1.15.8\",\"REDIS_VERSION\":\"5.0.3\",\"MYSQL_VERSION\":\"5.7.24\"}",
  "container_config": null
}

cancel job

This cancels a currently running job.

post/job/{job.id}/cancel
请求 Request

路由参数

  • job.idint
状态码 200

Example 1

成功示例

restart job

This restarts a job that has completed or been canceled.

post/job/{job.id}/restart
请求 Request

路由参数

  • job.idint
状态码 200

Example 1

成功示例

Organization

list orgs

This returns a list of organizations the current user is a member of.

get/orgs
响应 Response
状态码 200

参数

  • array
    • 数组成员object
    • idint
    • git_typestring
    • uidint
    • namestring
    • usernamestring
    • emailstring

      email

    • picstring

      pic url

    • access_tokenstring
    • refresh_tokenstring
    • org_adminstring

      org admin

    • typestring

      org or user

    • installation_idint

Example 1

成功示例

successful operation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
[
  {
    "id": "3",
    "git_type": "github",
    "uid": "31106763",
    "name": null,
    "username": "khs1994-website",
    "email": null,
    "pic": "https://avatars2.githubusercontent.com/u/31106763?v=4",
    "access_token": null,
    "refresh_token": null,
    "org_admin": "[\"16733187\"]",
    "type": "org",
    "installation_id": "0"
  },
  {
    "id": "4",
    "git_type": "github",
    "uid": "31461768",
    "name": null,
    "username": "khs1994-php",
    "email": null,
    "pic": "https://avatars0.githubusercontent.com/u/31461768?v=4",
    "access_token": null,
    "refresh_token": null,
    "org_admin": "[\"16733187\"]",
    "type": "org",
    "installation_id": "0"
  }
]

find org

This returns an individual organization.

get/org/{git_type}/{organization.name}
请求 Request

路由参数

  • git_typestring
  • organization.namestring
响应 Response
状态码 200

参数

  • idint
  • git_typestring
  • uidint
  • namestring
  • usernamestring
  • emailstring

    email

  • picstring

    pic url

  • access_tokenstring
  • refresh_tokenstring
  • org_adminstring

    org admin

  • typestring

    org or user

  • installation_idint

Example 1

成功示例

success
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "id": "2",
  "git_type": "github",
  "uid": "45250309",
  "name": "pcit-ce",
  "username": "pcit-ce",
  "email": "ci@khs1994.com",
  "pic": "https://avatars3.githubusercontent.com/u/45250309?v=4",
  "access_token": null,
  "refresh_token": null,
  "org_admin": "[\"16733187\"]",
  "type": "org",
  "installation_id": "469299"
}

Repositories

list repos

This returns a list of repositories the current user has access to.

get/repos
响应 Response
状态码 200

参数

  • array

Example 1

成功示例

success
1
[]

list owner repo

This returns a list of repositories an owner has access to.

get/repos/{git_type}/{username}
请求 Request

路由参数

  • git_typestring
  • usernamestring
响应 Response
状态码 200

参数

  • array

Example 1

成功示例

success
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
[
  {
    "rid": "119219872",
    "repo_full_name": "pcit-ce/pcit",
    "default_branch": "master",
    "git_type": "github",
    "webhooks_status": 1,
    "build_id": "111",
    "build_status": "queued",
    "commit_id": "f807efaa677757682aa7a3f226d3e799086e90dd"
  },
  {
    "rid": "230623025",
    "repo_full_name": "pcit-ce/pcit-release",
    "default_branch": "master",
    "git_type": "github",
    "webhooks_status": 1,
    "build_id": null,
    "build_status": null,
    "commit_id": "0"
  }
]

find repo

This returns an individual repository.

get/repo/{git_type}/{username}/{repo.name}
请求 Request

路由参数

  • git_typestring
  • usernamestring
  • repo.namestring
状态码 200

Example 1

成功示例

success
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "id": "1",
  "git_type": "github",
  "rid": "119219872",
  "repo_full_name": "pcit-ce/pcit",
  "webhooks_status": null,
  "build_activate": null,
  "repo_admin": "[\"16733187\"]",
  "repo_collaborators": null,
  "default_branch": "master",
  "last_sync": "1577893114",
  "secrets": null,
  "auto_merge": null
}

Repositories.activate

activate a repository

This will activate a repository, allowing its tests to be run on PCIT.

post/repo/{username}/{repo.name}/activate
请求 Request

路由参数

  • usernamestring
  • repo.namestring
状态码 200

Example 1

成功示例

deactivate a repository

This will deactivate a repository, preventing any tests from running on PCIT.

post/repo/{username}/{repo.name}/deactivate
请求 Request

路由参数

  • usernamestring
  • repo.namestring
状态码 200

Example 1

成功示例

Repositories.branches

list branches

This will return a list of branches a repository has on GitHub.

get/repo/{git_type}/{username}/{repo.name}/branches
请求 Request

路由参数

  • git_typestring
  • usernamestring
  • repo.namestring
响应 Response
状态码 200

参数

  • array

Example 1

成功示例

success
1
2
3
4
[
  "gh-pages",
  "master"
]

find branch

This will return information about an individual branch.

get/repo/{git_type}/{username}/{repo.name}/branch/{branch.name}
请求 Request

路由参数

  • git_typestring
  • usernamestring
  • repo.namestring
  • branch.namestring
响应 Response
状态码 200

参数

  • array
    • 数组成员object
    • idint

      builds id

    • branchstring

      trigger branch

    • commit_idstring

      commit sha

    • tagstring

      tag name

    • commit_messagestring

      commit message

    • comparestring

      compare url

    • commiter_namestring

      committer name

    • committer_usernamestring

      committer username

    • build_statusstring

      build status

    • event_typestring

      event type

    • pull_request_numberint

      pull request number

Example 1

成功示例

success
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
[
  {
    "id": "111",
    "branch": "master",
    "commit_id": "f807efaa677757682aa7a3f226d3e799086e90dd",
    "tag": null,
    "commit_message": "Support actions\n\nSigned-off-by: Kang HuaiShuai",
    "compare": "https://github.com/pcit-ce/pcit/compare/6746c883155e...f807efaa6777",
    "committer_name": "Kang HuaiShuai",
    "committer_username": "khs1994",
    "build_status": "queued",
    "event_type": "push"
  },
  {
    "id": "109",
    "branch": "master",
    "commit_id": "6746c883155ebb80014904211de818ee9c625338",
    "tag": null,
    "commit_message": "Support actions\n\nSigned-off-by: Kang HuaiShuai",
    "compare": "https://github.com/pcit-ce/pcit/compare/4dfb85a30c05...6746c883155e",
    "committer_name": "Kang HuaiShuai",
    "committer_username": "khs1994",
    "build_status": "failure",
    "event_type": "push"
  }
]

Repositories.caches

list repo caches

This returns all the caches for a repository.

get/repo/{username}/{repo.name}/caches
请求 Request

路由参数

  • usernamestring
  • repo.namestring
状态码 200

Example 1

成功示例

delete repo all caches

This deletes all caches for a repository.

delete/repo/{username}/{repo.name}/caches
请求 Request

路由参数

  • usernamestring
  • repo.namestring
状态码 200

Example 1

成功示例

Repositories.crons

get repo crons

This returns a list of crons for an individual repository.

get/repo/{username}/{repo.name}/crons
请求 Request

路由参数

  • usernamestring
  • repo.namestring
状态码 200

Example 1

成功示例

get single cron

This returns a single cron.

get/cron/{cron.id}
请求 Request

路由参数

  • cron.idint
状态码 200

Example 1

成功示例

delete single cron

This deletes a single cron.

delete/cron/{cron.id}
请求 Request

路由参数

  • cron.idint
状态码 200

Example 1

成功示例

get repo branch cron

This returns the cron set for the specified branch for the specified repository.

get/repo/{username}/{repo.name}/branch/{branch.name}/cron
请求 Request

路由参数

  • usernamestring
  • repo.namestring
  • branch.namestring
状态码 200

Example 1

成功示例

create repo branch cron

This creates a cron on the specified branch for the specified repository. Content-Type MUST be set in the header and an interval for the cron MUST be specified as a parameter.

post/repo/{username}/{repo.name}/branch/{branch.name}/cron
请求 Request

路由参数

  • usernamestring
  • repo.namestring
  • branch.namestring

请求 BODY

  • cron.intervalstring必填

    interval, daily, weekly or monthly

  • cron.dont_run_if_recent_build_existsboolean必填

    dont_run_if_recent_build_exists

状态码 200

Example 1

成功示例

文本
post
{{BASE_URL}}/repo/{username}/{repo.name}/branch/{branch.name}/cron

成功示例

Repositories.env_vars

repo env list

This returns a list of environment variables for an individual repository.

get/repo/{username}/{repo.name}/env_vars
请求 Request

路由参数

  • usernamestring
    username
  • repo.namestring
状态码 200

Example 1

成功示例

success
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
[
  {
    "id": "33",
    "git_type": "github",
    "rid": "119219872",
    "name": "ACCESS_TOKEN",
    "value": "abcdefg",
    "public": "0"
  },
  {
    "id": "4",
    "git_type": "github",
    "rid": "119219872",
    "name": "CODECOV_TOKEN",
    "value": "abcdefg",
    "public": "0"
  }
]

create repo env

This creates an environment variable for an individual repository.

post/repo/{username}/{repo.name}/env_vars
请求 Request

路由参数

  • usernamestring
    username
  • repo.namestring

请求 BODY

  • env_var.namestring
  • env_var.valuestring
  • env_var.publicstring
状态码 200

Example 1

成功示例

文本
post
{{BASE_URL}}/repo/{username}/{repo.name}/env_vars

成功示例

get repo single env

This returns a single environment variable.

get/repo/{username}/{repo.name}/env_var/{env_var.id}
请求 Request

路由参数

  • usernamestring
  • repo.namestring
  • env_var.idint
状态码 200

Example 1

成功示例

success
1
2
3
4
5
6
7
8
{
  "id": "4",
  "git_type": "github",
  "rid": "119219872",
  "name": "CODECOV_TOKEN",
  "value": "abcdef",
  "public": "0"
}

update repo single env

This updates a single environment variable.

post/repo/{username}/{repo.name}/env_var/{env_var.id}
请求 Request

路由参数

  • usernamestring
  • repo.namestring
  • env_var.idint
状态码 200

Example 1

成功示例

文本
post
{{BASE_URL}}/repo/{username}/{repo.name}/env_var/{env_var.id}

成功示例

delete repo single env

This deletes a single environment variable.

delete/repo/{username}/{repo.name}/env_var/{env_var.id}
请求 Request

路由参数

  • usernamestring
  • repo.namestring
  • env_var.idint
状态码 200

Example 1

成功示例

Repositories.requests

get repo request list

This will return a list of requests belonging to a repository.

get/repo/{username}/{repo.name}/requests
请求 Request

路由参数

  • usernamestring
  • repo.namestring
响应 Response
状态码 200

参数

  • idint

    builds id

  • branchstring

    trigger branch

  • commit_idstring

    commit sha

  • tagstring

    tag name

  • commit_messagestring

    commit message

  • comparestring

    compare url

  • commiter_namestring

    committer name

  • committer_usernamestring

    committer username

  • build_statusstring

    build status

  • event_typestring

    event type

  • pull_request_numberint

    pull request number

  • created_atint

    created time

  • finished_atint

    finished time

Example 1

成功示例

success
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
[
  {
    "id": "112",
    "branch": "gh-pages",
    "commit_id": "0fa67f2b1c0d59998b71035b402849f5075a3c60",
    "tag": null,
    "commit_message": "Deploy Git by PCIT https://ci.khs1994.com",
    "compare": "https://github.com/pcit-ce/pcit/compare/d492689de936...0fa67f2b1c0d",
    "committer_name": "pcit-ce",
    "committer_username": "pcit-deploy-robot",
    "build_status": "misconfigured",
    "event_type": "push",
    "pull_request_number": null,
    "created_at": "1577892876",
    "finished_at": null
  },
  {
    "id": "111",
    "branch": "master",
    "commit_id": "f807efaa677757682aa7a3f226d3e799086e90dd",
    "tag": null,
    "commit_message": "Support actions\n\nSigned-off-by: Kang HuaiShuai",
    "compare": "https://github.com/pcit-ce/pcit/compare/6746c883155e...f807efaa6777",
    "committer_name": "Kang HuaiShuai",
    "committer_username": "khs1994",
    "build_status": "queued",
    "event_type": "push",
    "pull_request_number": null,
    "created_at": "1577892253",
    "finished_at": null
  }
]

create repo single request

This will create a request for an individual repository, triggering a build to run on PCIT.

post/repo/{username}/{repo.name}/requests
请求 Request

路由参数

  • usernamestring
  • repo.namestring
状态码 200

Example 1

成功示例

get repo single request

This will return information about an individual request.

get/repo/{username}/{repo.name}/request/{request.id}
请求 Request

路由参数

  • usernamestring
  • repo.namestring
  • request.idint
响应 Response
状态码 200

参数

  • idint

    build id

  • git_typestring

    git type

  • ridint

    repo id

  • event_typestring

    event type

  • build_statusstring

    build status

  • branchstring

    branch

  • tagstring

    tag name

  • pull_request_titlestring

    pull request title

  • pull_request_numberint

    pull request number

  • pull_request_sourcestring

    pull request source repo

  • comparestring

    compare url

  • commit_idstring

    commit sha

  • commit_messagestring

    commit message

  • committer_uidint

    committer uid

  • committer_namestring

    committer name

  • committer_usernamestring

    committer username

  • committer_emailstring

    committer email

  • committer_picstring

    committer pic

  • author_uidint

    author uid

  • author_namestring

    author name

  • author_usernamestring

    author username

  • author_emailstring

    author email

  • author_picstring

    author pic

  • created_atint

    create time

  • finished_atint

    finish time

  • deleted_atint

    delete time

  • configstring

    pcit config string

  • actionstring

    action

  • check_suites_idint

    check suites id

  • internalint

    internal

  • privateboolean

    is private

  • unique_keystring

    unique key

Example 1

成功示例

success
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
{
  "id": "111",
  "git_type": "github",
  "rid": "119219872",
  "event_type": "push",
  "build_status": "queued",
  "branch": "master",
  "tag": null,
  "pull_request_title": null,
  "pull_request_number": null,
  "pull_request_source": null,
  "compare": "https://github.com/pcit-ce/pcit/compare/6746c883155e...f807efaa6777",
  "commit_id": "f807efaa677757682aa7a3f226d3e799086e90dd",
  "commit_message": "Support actions\n\nSigned-off-by: Kang HuaiShuai",
  "committer_uid": null,
  "committer_name": "Kang HuaiShuai",
  "committer_username": "khs1994",
  "committer_email": "khs1994@khs1994.com",
  "committer_pic": null,
  "author_uid": null,
  "author_name": "Kang HuaiShuai",
  "author_username": "khs1994",
  "author_email": "khs1994@khs1994.com",
  "author_pic": null,
  "created_at": "1577892253",
  "finished_at": null,
  "deleted_at": null,
  "config": "{}",
  "action": null,
  "check_suites_id": null,
  "internal": "1",
  "private": "0",
  "unique_key": "0"
}

Repositories.settings

get repo setting list

This returns a list of the settings for that repository.

get/repo/{username}/{repo.name}/settings
请求 Request

路由参数

  • usernamestring
  • repo.namestring
状态码 200

Example 1

成功示例

success
1
2
3
4
5
6
7
{
  "build_pushes": "1",
  "build_pull_requests": "1",
  "maximum_number_of_builds": "1",
  "auto_cancel_branch_builds": "0",
  "auto_cancel_pull_request_builds": "0"
}

get repo single setting

This returns a single setting.

get/repo/{username}/{repo.name}/setting/{setting.name}
请求 Request

路由参数

  • usernamestring
  • repo.namestring
  • setting.namestring
状态码 200

Example 1

成功示例

update repo single setting

This updates a single setting.

post/repo/{username}/{repo.name}/setting/{setting.name}
请求 Request

路由参数

  • usernamestring
  • repo.namestring
  • setting.namestring

请求 BODY

  • setting.valuestring
状态码 200

Example 1

成功示例

文本
post
{{BASE_URL}}/repo/{username}/{repo.name}/setting/{setting.name}

成功示例

Repositories.star

star a repo

This will star a repository based on the currently logged in user.

post/repo/{username}/{repo.name}/star
请求 Request

路由参数

  • usernamestring
  • repo.namestring
状态码 200

Example 1

成功示例

unstar a repo

This will unstar a repository based on the currently logged in user.

post/repo/{username}/{repo.name}/unstar
请求 Request

路由参数

  • usernamestring
  • repo.namestring
状态码 200

Example 1

成功示例

Repositories.status

Repositories.issues

translate issue title

translate issue title

patch/repo/{username}/{repo.name}/issues/translate/{issue.number}
请求 Request

路由参数

  • usernamestring
  • repo.namestring
  • issue.numberint
状态码 200

Example 1

成功示例

User

get token

get token by git username and password

post/user/token
请求 Request

请求 BODY

  • git_typestring
  • usernamestring
  • passwordstring
状态码 200

Example 1

成功示例

文本
post
{{BASE_URL}}/user/token

成功示例

get current user info

This will return information about the current user.

get/user
状态码 200

Example 1

成功示例

success
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "id": "1",
  "git_type": "github",
  "uid": "16733187",
  "name": null,
  "username": "khs1994",
  "email": "khs1994@khs1994.com",
  "pic": "https://avatars2.githubusercontent.com/u/16733187?v=4",
  "access_token": "abcdefg",
  "refresh_token": null,
  "org_admin": null,
  "type": "user",
  "installation_id": "0"
}

get a user info

This will return information about an individual user.

get/user/{git_type}/{username}
请求 Request

路由参数

  • git_typestring
  • usernamestring
状态码 200

Example 1

成功示例

sucess
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "id": "1",
  "git_type": "github",
  "uid": "16733187",
  "name": null,
  "username": "khs1994",
  "email": "khs1994@khs1994.com",
  "pic": "https://avatars2.githubusercontent.com/u/16733187?v=4",
  "access_token": "abcdefg",
  "refresh_token": null,
  "org_admin": null,
  "type": "user",
  "installation_id": "0"
}

sync user info

This triggers a sync on a user's account with their GitHub account.

post/user/sync
状态码 200

Example 1

成功示例

get current user active repo list

A list of all the builds in an "active" state, either created or started.

get/user/{git_type}/{owner.login}/active
请求 Request

路由参数

  • git_typestring
  • owner.loginstring
状态码 200

Example 1

成功示例

User.beta_features

get user beta features

This will return a list of beta features available to a user.

get/user/{user.name}/beta_features
请求 Request

路由参数

  • user.namestring
状态码 200

Example 1

成功示例

update user beta features

This will update a user's beta_feature.

patch/user/{user.name}/beta_feature/{beta_feature.id}
请求 Request

路由参数

  • user.namestring
  • beta_feature.idstring
状态码 200

Example 1

成功示例

delete user beta features

This will delete a user's beta feature.

delete/user/{user.name}/beta_feature/{beta_feature.id}
请求 Request

路由参数

  • user.namestring
  • beta_feature.idstring
状态码 200

Example 1

成功示例

System

get oauth client id

get oauth client id

get/ci/oauth_client_id
响应 Response
状态码 200

参数

  • urlstring

Example 1

成功示例

success
1
2
3
{
  "url": "https://github.com/settings/connections/applications/35cb33c242b808b26270"
}

get pending jobs number

get pending jobs number

get/ci/pending
状态码 200

Example 1

成功示例

get a user or org github app installation url

get a user or org github app installation url

get/ci/github_app_installation/{uid}
请求 Request

路由参数

  • uidint
响应 Response
状态码 200

参数

  • urlstring

Example 1

成功示例

success
1
2
3
{
  "url": "https://github.com/apps/pcit-ce2/installations/new/permissions?suggested_target_id=31106763"
}

get pcit github app settings url

get pcit github app settings url

get/ci/github_app_settings/{org_name}
请求 Request

路由参数

  • org_namestring
    org name
响应 Response
状态码 200

参数

  • urlstring

Example 1

成功示例

success
1
2
3
{
  "url": "https://github.com/organizations/pcit-ce/settings/installations"
}

get pcit about info

get pcit about info

get/ci/about
状态码 200

Example 1

成功示例

get pcit about changelog

get pcit about changelog

get/ci/changelog
状态码 200

Example 1

成功示例

get pcit metrics

get pcit metrics

get/metrics
响应 Response
状态码 200

参数

  • string

Example 1

成功示例

1
"string"

get pcit healthz

get pcit healthz

get/healthz
响应 Response
状态码 200

参数

  • string

Example 1

成功示例

success
1
ok

get pcit readyz

get pcit readyz

get/readyz
响应 Response
状态码 200

参数

  • string

Example 1

成功示例

success
1
ok

get pcit livez

get pcit livez

get/livez
响应 Response
状态码 200

参数

  • string

Example 1

成功示例

success
1
ok

openapi

return openapi json

get/openapi
请求 Request

QUERY

  • codingboolean

    openapi for coding.net

状态码 200

Example 1

成功示例

openapi v3

return openapi json

get/openapi/v3
请求 Request

QUERY

  • codingboolean

    openapi for coding.net

状态码 200

Example 1

成功示例

validate .pcit.yml

validate .pcit.yml

post/validate
请求 Request

请求 BODY

  • string必填
响应 Response
状态码 200

参数

  • string

    validate passed

Example 1

成功示例

文本
post
{{BASE_URL}}/validate

成功示例

文本
post
{{BASE_URL}}/validate

成功示例

validate result
1
ok

成功示例

validate result
1
2
3
4
5
6
7
8
9
10
11
[
  {
    "steps": "The property steps is required"
  },
  {
    "": "The property lanuage is not defined and the definition does not allow additional properties"
  },
  {
    "": "The property test is not defined and the definition does not allow additional properties"
  }
]