此版本的 GitHub Enterprise 已停止服务 2021-09-23. 即使针对重大安全问题,也不会发布补丁。 要获得更好的性能、改进的安全性和新功能,请升级到 GitHub Enterprise 的最新版本。 如需升级方面的帮助,请联系 GitHub Enterprise 支持

本文内容

GitHub Enterprise 管理

You can use these GitHub Enterprise Cloud endpoints to administer your enterprise account. Among the tasks you can perform with this API are many relating to GitHub Actions.

端点 URL

REST API 端点— 管理控制台 API 端点除外— 是以下 URL 的前缀:

http(s)://[hostname]/api/v3

管理控制台 API 端点是唯一以主机名为前缀的端点:

http(s)://hostname/

身份验证

GitHub Enterprise Server 安装设施的 API 端点接受与 GitHub.com 相同的身份验证方法。 您可以使用 OAuth 令牌(可使用授权 API 创建)或基本身份验证来验证自己。 OAuth 令牌用于企业特定的端点时必须具有 site_admin OAuth 作用域

企业管理 API 端点只有经过身份验证的 GitHub Enterprise Server 站点管理员可以访问,但管理控制台 API 例外,它需要管理控制台密码

版本信息

每个 API 的响应标头中都会返回企业的当前版本:X-GitHub-Enterprise-Version: enterprise-server@2.22.0 您也可以通过调用元端点来读取当前版本。

GitHub Actions

List self-hosted runner groups for an enterprise

Lists all self-hosted runner groups for an enterprise.

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

get /enterprises/{enterprise}/actions/runner-groups

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

per_page integer query

Results per page (max 100)

Default: 30
page integer query

Page number of the results to fetch.

Default: 1

代码示例

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runner-groups
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprises/{enterprise}/actions/runner-groups', {
  enterprise: 'enterprise'
})

Response

Status: 200 OK
{
  "total_count": 3,
  "runner_groups": [
    {
      "id": 1,
      "name": "Default",
      "visibility": "all",
      "default": true,
      "runners_url": "https://api.github.com/enterprises/octo-corp/actions/runner_groups/1/runners",
      "allows_public_repositories": false
    },
    {
      "id": 2,
      "name": "octo-runner-group",
      "visibility": "selected",
      "default": false,
      "selected_organizations_url": "https://api.github.com/enterprises/octo-corp/actions/runner_groups/2/organizations",
      "runners_url": "https://api.github.com/enterprises/octo-corp/actions/runner_groups/2/runners",
      "allows_public_repositories": true
    },
    {
      "id": 3,
      "name": "expensive-hardware",
      "visibility": "private",
      "default": false,
      "runners_url": "https://api.github.com/enterprises/octo-corp/actions/runner_groups/3/runners",
      "allows_public_repositories": true
    }
  ]
}

Create a self-hosted runner group for an enterprise

Creates a new self-hosted runner group for an enterprise.

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

post /enterprises/{enterprise}/actions/runner-groups

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

name string body

Required. Name of the runner group.

visibility string body

Visibility of a runner group. You can select all organizations or select individual organization. Can be one of: all or selected

selected_organization_ids array of integers body

List of organization IDs that can access the runner group.

runners array of integers body

List of runner IDs to add to the runner group.

代码示例

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runner-groups \
  -d '{"name":"name"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /enterprises/{enterprise}/actions/runner-groups', {
  enterprise: 'enterprise',
  name: 'name'
})

Response

Status: 201 Created
{
  "id": 2,
  "name": "octo-runner-group",
  "visibility": "selected",
  "default": false,
  "selected_organizations_url": "https://api.github.com/enterprises/octo-corp/actions/runner-groups/2/organizations",
  "runners_url": "https://api.github.com/enterprises/octo-corp/actions/runner-groups/2/runners",
  "allows_public_repositories": false
}

Get a self-hosted runner group for an enterprise

Gets a specific self-hosted runner group for an enterprise.

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

get /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_group_id integer path

Unique identifier of the self-hosted runner group.

代码示例

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runner-groups/42
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}', {
  enterprise: 'enterprise',
  runner_group_id: 42
})

Response

Status: 200 OK
{
  "id": 2,
  "name": "octo-runner-group",
  "visibility": "selected",
  "default": false,
  "selected_organizations_url": "https://api.github.com/enterprises/octo-corp/actions/runner-groups/2/organizations",
  "runners_url": "https://api.github.com/enterprises/octo-corp/actions/runner-groups/2/runners",
  "allows_public_repositories": false
}

Update a self-hosted runner group for an enterprise

Updates the name and visibility of a self-hosted runner group in an enterprise.

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

patch /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_group_id integer path

Unique identifier of the self-hosted runner group.

name string body

Name of the runner group.

visibility string body

Visibility of a runner group. You can select all organizations or select individual organizations. Can be one of: all or selected

Default: all

代码示例

Shell
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runner-groups/42 \
  -d '{"name":"name"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}', {
  enterprise: 'enterprise',
  runner_group_id: 42,
  name: 'name'
})

Response

Status: 200 OK
{
  "id": 2,
  "name": "Expensive hardware runners",
  "visibility": "selected",
  "default": false,
  "selected_organizations_url": "https://api.github.com/enterprises/octo-corp/actions/runner-groups/2/organizations",
  "runners_url": "https://api.github.com/enterprises/octo-corp/actions/runner-groups/2/runners",
  "allows_public_repositories": true
}

Delete a self-hosted runner group from an enterprise

Deletes a self-hosted runner group for an enterprise.

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

delete /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_group_id integer path

Unique identifier of the self-hosted runner group.

代码示例

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runner-groups/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}', {
  enterprise: 'enterprise',
  runner_group_id: 42
})

Response

Status: 204 No Content

List organization access to a self-hosted runner group in an enterprise

Lists the organizations with access to a self-hosted runner group.

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

get /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/organizations

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_group_id integer path

Unique identifier of the self-hosted runner group.

per_page integer query

Results per page (max 100)

Default: 30
page integer query

Page number of the results to fetch.

Default: 1

代码示例

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runner-groups/42/organizations
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/organizations', {
  enterprise: 'enterprise',
  runner_group_id: 42
})

Response

Status: 200 OK
{
  "total_count": 1,
  "organizations": [
    {
      "login": "octocat",
      "id": 161335,
      "node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
      "url": "https://api.github.com/orgs/octo-org",
      "repos_url": "https://api.github.com/orgs/octo-org/repos",
      "events_url": "https://api.github.com/orgs/octo-org/events",
      "hooks_url": "https://api.github.com/orgs/octo-org/hooks",
      "issues_url": "https://api.github.com/orgs/octo-org/issues",
      "members_url": "https://api.github.com/orgs/octo-org/members{/member}",
      "public_members_url": "https://api.github.com/orgs/octo-org/public_members{/member}",
      "avatar_url": "https://github.com/images/error/octocat_happy.gif",
      "description": "A great organization"
    }
  ]
}

Set organization access for a self-hosted runner group in an enterprise

Replaces the list of organizations that have access to a self-hosted runner configured in an enterprise.

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

put /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/organizations

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_group_id integer path

Unique identifier of the self-hosted runner group.

selected_organization_ids array of integers body

Required. List of organization IDs that can access the runner group.

代码示例

Shell
curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runner-groups/42/organizations \
  -d '{"selected_organization_ids":[42]}'
JavaScript (@octokit/core.js)
await octokit.request('PUT /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/organizations', {
  enterprise: 'enterprise',
  runner_group_id: 42,
  selected_organization_ids: [
    42
  ]
})

Response

Status: 204 No Content

Add organization access to a self-hosted runner group in an enterprise

Adds an organization to the list of selected organizations that can access a self-hosted runner group. The runner group must have visibility set to selected. For more information, see "Create a self-hosted runner group for an enterprise."

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

put /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/organizations/{org_id}

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_group_id integer path

Unique identifier of the self-hosted runner group.

org_id integer path

Unique identifier of an organization.

代码示例

Shell
curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runner-groups/42/organizations/42
JavaScript (@octokit/core.js)
await octokit.request('PUT /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/organizations/{org_id}', {
  enterprise: 'enterprise',
  runner_group_id: 42,
  org_id: 42
})

Response

Status: 204 No Content

Remove organization access to a self-hosted runner group in an enterprise

Removes an organization from the list of selected organizations that can access a self-hosted runner group. The runner group must have visibility set to selected. For more information, see "Create a self-hosted runner group for an enterprise."

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

delete /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/organizations/{org_id}

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_group_id integer path

Unique identifier of the self-hosted runner group.

org_id integer path

Unique identifier of an organization.

代码示例

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runner-groups/42/organizations/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/organizations/{org_id}', {
  enterprise: 'enterprise',
  runner_group_id: 42,
  org_id: 42
})

Response

Status: 204 No Content

List self-hosted runners in a group for an enterprise

Lists the self-hosted runners that are in a specific enterprise group.

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

get /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/runners

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_group_id integer path

Unique identifier of the self-hosted runner group.

per_page integer query

Results per page (max 100)

Default: 30
page integer query

Page number of the results to fetch.

Default: 1

代码示例

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runner-groups/42/runners
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/runners', {
  enterprise: 'enterprise',
  runner_group_id: 42
})

Response

Status: 200 OK
{
  "total_count": 2,
  "runners": [
    {
      "id": 23,
      "name": "linux_runner",
      "os": "linux",
      "status": "online",
      "busy": true
    },
    {
      "id": 24,
      "name": "mac_runner",
      "os": "macos",
      "status": "offline",
      "busy": false
    }
  ]
}

Set self-hosted runners in a group for an enterprise

Replaces the list of self-hosted runners that are part of an enterprise runner group.

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

put /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/runners

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_group_id integer path

Unique identifier of the self-hosted runner group.

runners array of integers body

Required. List of runner IDs to add to the runner group.

代码示例

Shell
curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runner-groups/42/runners \
  -d '{"runners":[42]}'
JavaScript (@octokit/core.js)
await octokit.request('PUT /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/runners', {
  enterprise: 'enterprise',
  runner_group_id: 42,
  runners: [
    42
  ]
})

Response

Status: 204 No Content

Add a self-hosted runner to a group for an enterprise

Adds a self-hosted runner to a runner group configured in an enterprise.

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

put /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/runners/{runner_id}

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_group_id integer path

Unique identifier of the self-hosted runner group.

runner_id integer path

Unique identifier of the self-hosted runner.

代码示例

Shell
curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runner-groups/42/runners/42
JavaScript (@octokit/core.js)
await octokit.request('PUT /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/runners/{runner_id}', {
  enterprise: 'enterprise',
  runner_group_id: 42,
  runner_id: 42
})

Response

Status: 204 No Content

Remove a self-hosted runner from a group for an enterprise

Removes a self-hosted runner from a group configured in an enterprise. The runner is then returned to the default group.

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

delete /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/runners/{runner_id}

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_group_id integer path

Unique identifier of the self-hosted runner group.

runner_id integer path

Unique identifier of the self-hosted runner.

代码示例

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runner-groups/42/runners/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/runners/{runner_id}', {
  enterprise: 'enterprise',
  runner_group_id: 42,
  runner_id: 42
})

Response

Status: 204 No Content

List self-hosted runners for an enterprise

Lists all self-hosted runners configured for an enterprise.

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

get /enterprises/{enterprise}/actions/runners

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

per_page integer query

Results per page (max 100)

Default: 30
page integer query

Page number of the results to fetch.

Default: 1

代码示例

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runners
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprises/{enterprise}/actions/runners', {
  enterprise: 'enterprise'
})

Response

Status: 200 OK
{
  "total_count": 2,
  "runners": [
    {
      "id": 23,
      "name": "linux_runner",
      "os": "linux",
      "status": "online",
      "busy": true
    },
    {
      "id": 24,
      "name": "mac_runner",
      "os": "macos",
      "status": "offline",
      "busy": false
    }
  ]
}

List runner applications for an enterprise

Lists binaries for the runner application that you can download and run.

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

get /enterprises/{enterprise}/actions/runners/downloads

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

代码示例

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runners/downloads
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprises/{enterprise}/actions/runners/downloads', {
  enterprise: 'enterprise'
})

Response

Status: 200 OK
[
  {
    "os": "osx",
    "architecture": "x64",
    "download_url": "https://github.com/actions/runner/releases/download/v2.164.0/actions-runner-osx-x64-2.164.0.tar.gz",
    "filename": "actions-runner-osx-x64-2.164.0.tar.gz"
  },
  {
    "os": "linux",
    "architecture": "x64",
    "download_url": "https://github.com/actions/runner/releases/download/v2.164.0/actions-runner-linux-x64-2.164.0.tar.gz",
    "filename": "actions-runner-linux-x64-2.164.0.tar.gz"
  },
  {
    "os": "linux",
    "architecture": "arm",
    "download_url": "https://github.com/actions/runner/releases/download/v2.164.0/actions-runner-linux-arm-2.164.0.tar.gz",
    "filename": "actions-runner-linux-arm-2.164.0.tar.gz"
  },
  {
    "os": "win",
    "architecture": "x64",
    "download_url": "https://github.com/actions/runner/releases/download/v2.164.0/actions-runner-win-x64-2.164.0.zip",
    "filename": "actions-runner-win-x64-2.164.0.zip"
  },
  {
    "os": "linux",
    "architecture": "arm64",
    "download_url": "https://github.com/actions/runner/releases/download/v2.164.0/actions-runner-linux-arm64-2.164.0.tar.gz",
    "filename": "actions-runner-linux-arm64-2.164.0.tar.gz"
  }
]

Create a registration token for an enterprise

Returns a token that you can pass to the config script. The token expires after one hour.

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

Example using registration token

Configure your self-hosted runner, replacing TOKEN with the registration token provided by this endpoint.

./config.sh --url https://github.com/enterprises/octo-enterprise --token TOKEN
post /enterprises/{enterprise}/actions/runners/registration-token

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

代码示例

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runners/registration-token
JavaScript (@octokit/core.js)
await octokit.request('POST /enterprises/{enterprise}/actions/runners/registration-token', {
  enterprise: 'enterprise'
})

Response

Status: 201 Created
{
  "token": "LLBF3JGZDX3P5PMEXLND6TS6FCWO6",
  "expires_at": "2020-01-22T12:13:35.123-08:00"
}

Create a remove token for an enterprise

Returns a token that you can pass to the config script to remove a self-hosted runner from an enterprise. The token expires after one hour.

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

Example using remove token

To remove your self-hosted runner from an enterprise, replace TOKEN with the remove token provided by this endpoint.

./config.sh remove --token TOKEN
post /enterprises/{enterprise}/actions/runners/remove-token

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

代码示例

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runners/remove-token
JavaScript (@octokit/core.js)
await octokit.request('POST /enterprises/{enterprise}/actions/runners/remove-token', {
  enterprise: 'enterprise'
})

Response

Status: 201 Created
{
  "token": "AABF3JGZDX3P5PMEXLND6TS6FCWO6",
  "expires_at": "2020-01-29T12:13:35.123-08:00"
}

Get a self-hosted runner for an enterprise

Gets a specific self-hosted runner configured in an enterprise.

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

get /enterprises/{enterprise}/actions/runners/{runner_id}

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_id integer path

Unique identifier of the self-hosted runner.

代码示例

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runners/42
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprises/{enterprise}/actions/runners/{runner_id}', {
  enterprise: 'enterprise',
  runner_id: 42
})

Response

Status: 200 OK
{
  "id": 23,
  "name": "mac_runner",
  "os": "macos",
  "status": "online",
  "busy": true
}

Delete a self-hosted runner from an enterprise

Forces the removal of a self-hosted runner from an enterprise. You can use this endpoint to completely remove the runner when the machine you were using no longer exists.

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

delete /enterprises/{enterprise}/actions/runners/{runner_id}

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_id integer path

Unique identifier of the self-hosted runner.

代码示例

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runners/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /enterprises/{enterprise}/actions/runners/{runner_id}', {
  enterprise: 'enterprise',
  runner_id: 42
})

Response

Status: 204 No Content

管理统计

管理统计 API 提供有关安装设施的各种指标。 它只适用于经过身份验证的站点管理员。普通用户尝试访问它时会收到 404 响应。

Get all statistics

get /enterprise/stats/all

代码示例

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprise/stats/all
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/stats/all')

Response

Status: 200 OK
{
  "repos": {
    "total_repos": 212,
    "root_repos": 194,
    "fork_repos": 18,
    "org_repos": 51,
    "total_pushes": 3082,
    "total_wikis": 15
  },
  "hooks": {
    "total_hooks": 27,
    "active_hooks": 23,
    "inactive_hooks": 4
  },
  "pages": {
    "total_pages": 36
  },
  "orgs": {
    "total_orgs": 33,
    "disabled_orgs": 0,
    "total_teams": 60,
    "total_team_members": 314
  },
  "users": {
    "total_users": 254,
    "admin_users": 45,
    "suspended_users": 21
  },
  "pulls": {
    "total_pulls": 86,
    "merged_pulls": 60,
    "mergeable_pulls": 21,
    "unmergeable_pulls": 3
  },
  "issues": {
    "total_issues": 179,
    "open_issues": 83,
    "closed_issues": 96
  },
  "milestones": {
    "total_milestones": 7,
    "open_milestones": 6,
    "closed_milestones": 1
  },
  "gists": {
    "total_gists": 178,
    "private_gists": 151,
    "public_gists": 25
  },
  "comments": {
    "total_commit_comments": 6,
    "total_gist_comments": 28,
    "total_issue_comments": 366,
    "total_pull_request_comments": 30
  }
}

Get comment statistics

get /enterprise/stats/comments

代码示例

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprise/stats/comments
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/stats/comments')

Response

Status: 200 OK

Get gist statistics

get /enterprise/stats/gists

代码示例

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprise/stats/gists
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/stats/gists')

Response

Status: 200 OK

Get hooks statistics

get /enterprise/stats/hooks

代码示例

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprise/stats/hooks
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/stats/hooks')

Response

Status: 200 OK

Get issue statistics

get /enterprise/stats/issues

代码示例

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprise/stats/issues
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/stats/issues')

Response

Status: 200 OK

Get milestone statistics

get /enterprise/stats/milestones

代码示例

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprise/stats/milestones
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/stats/milestones')

Response

Status: 200 OK

Get organization statistics

get /enterprise/stats/orgs

代码示例

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprise/stats/orgs
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/stats/orgs')

Response

Status: 200 OK

Get pages statistics

get /enterprise/stats/pages

代码示例

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprise/stats/pages
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/stats/pages')

Response

Status: 200 OK

Get pull request statistics

get /enterprise/stats/pulls

代码示例

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprise/stats/pulls
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/stats/pulls')

Response

Status: 200 OK

Get repository statistics

get /enterprise/stats/repos

代码示例

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprise/stats/repos
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/stats/repos')

Response

Status: 200 OK

Get users statistics

get /enterprise/stats/users

代码示例

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprise/stats/users
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/stats/users')

Response

Status: 200 OK

全局 web 挂钩

全局 web 挂钩安装在企业上。 您可以使用全局 web 挂钩来自动监视、响应或实施针对企业上的用户、组织、团队和仓库的规则。 全局 web 挂钩可以订阅组织用户仓库团队成员成员身份复刻ping 事件类型。

此 API 只适用于经过身份验证的站点管理员。普通用户尝试访问它时会收到 404 响应。 要了解如何配置全局 web 挂钩,请参阅关于全局 web 挂钩

List global webhooks

get /admin/hooks

参数

Name Type In Description
accept string header

This API is under preview and subject to change.查看预览通知

accept string header

This API is under preview and subject to change.

Default: application/vnd.github.superpro-preview+json
per_page integer query

Results per page (max 100)

Default: 30
page integer query

Page number of the results to fetch.

Default: 1

代码示例

Shell
curl \
  -H "Accept: application/vnd.github.superpro-preview+json" \
  http(s)://{hostname}/api/v3/admin/hooks
JavaScript (@octokit/core.js)
await octokit.request('GET /admin/hooks', {
  mediaType: {
    previews: [
      'superpro'
    ]
  }
})

Response

Status: 200 OK
[
  {
    "type": "Global",
    "id": 1,
    "name": "web",
    "active": true,
    "events": [
      "organization",
      "user"
    ],
    "config": {
      "url": "https://example.com",
      "content_type": "json",
      "insecure_ssl": "0",
      "secret": "********"
    },
    "updated_at": "2017-12-07T00:14:59Z",
    "created_at": "2017-12-07T00:14:59Z",
    "url": "https://api.github.com/admin/hooks/1",
    "ping_url": "https://api.github.com/admin/hooks/1/pings"
  }
]

预览通知

The Global Webhooks API is currently available for developers to preview. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.superpro-preview+json
☝️此标头必填.

Create a global webhook

post /admin/hooks

参数

Name Type In Description
accept string header

This API is under preview and subject to change.查看预览通知

accept string header

This API is under preview and subject to change.

Default: application/vnd.github.superpro-preview+json
name string body

Required. Must be passed as "web".

config object body

Required. Key/value pairs to provide settings for this webhook.

Properties of the config object
url (string)

Required. The URL to which the payloads will be delivered.

content_type (string)

The media type used to serialize the payloads. Supported values include json and form. The default is form.

secret (string)

If provided, the secret will be used as the key to generate the HMAC hex digest value in the X-Hub-Signature header.

insecure_ssl (string)

Determines whether the SSL certificate of the host for url will be verified when delivering payloads. Supported values include 0 (verification is performed) and 1 (verification is not performed). The default is 0. We strongly recommend not setting this to 1 as you are subject to man-in-the-middle and other attacks.

events array of strings body

The events that trigger this webhook. A global webhook can be triggered by user and organization events. Default: user and organization.

active boolean body

Determines if notifications are sent when the webhook is triggered. Set to true to send notifications.

Default: true

代码示例

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.superpro-preview+json" \
  http(s)://{hostname}/api/v3/admin/hooks \
  -d '{"name":"name","config":{"url":"url","content_type":"content_type","secret":"secret","insecure_ssl":"insecure_ssl"}}'
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/hooks', {
  name: 'name',
  config: {
    url: 'url',
    content_type: 'content_type',
    secret: 'secret',
    insecure_ssl: 'insecure_ssl'
  },
  mediaType: {
    previews: [
      'superpro'
    ]
  }
})

Response

Status: 201 Created
{
  "type": "Global",
  "id": 1,
  "name": "web",
  "active": true,
  "events": [
    "organization",
    "user"
  ],
  "config": {
    "url": "https://example.com",
    "content_type": "json",
    "insecure_ssl": "0",
    "secret": "********"
  },
  "updated_at": "2017-12-07T00:14:59Z",
  "created_at": "2017-12-07T00:14:59Z",
  "url": "https://api.github.com/admin/hooks/1",
  "ping_url": "https://api.github.com/admin/hooks/1/pings"
}

预览通知

The Global Webhooks API is currently available for developers to preview. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.superpro-preview+json
☝️此标头必填.

Get a global webhook

get /admin/hooks/{hook_id}

参数

Name Type In Description
accept string header

This API is under preview and subject to change.查看预览通知

accept string header

This API is under preview and subject to change.

Default: application/vnd.github.superpro-preview+json
hook_id integer path

代码示例

Shell
curl \
  -H "Accept: application/vnd.github.superpro-preview+json" \
  http(s)://{hostname}/api/v3/admin/hooks/42
JavaScript (@octokit/core.js)
await octokit.request('GET /admin/hooks/{hook_id}', {
  hook_id: 42,
  mediaType: {
    previews: [
      'superpro'
    ]
  }
})

Response

Status: 200 OK
{
  "type": "Global",
  "id": 1,
  "name": "web",
  "active": true,
  "events": [
    "organization",
    "user"
  ],
  "config": {
    "url": "https://example.com",
    "content_type": "json",
    "insecure_ssl": "0",
    "secret": "********"
  },
  "updated_at": "2017-12-07T00:14:59Z",
  "created_at": "2017-12-07T00:14:59Z",
  "url": "https://api.github.com/admin/hooks/1",
  "ping_url": "https://api.github.com/admin/hooks/1/pings"
}

预览通知

The Global Webhooks API is currently available for developers to preview. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.superpro-preview+json
☝️此标头必填.

Update a global webhook

Parameters that are not provided will be overwritten with the default value or removed if no default exists.

patch /admin/hooks/{hook_id}

参数

Name Type In Description
accept string header

This API is under preview and subject to change.查看预览通知

accept string header

This API is under preview and subject to change.

Default: application/vnd.github.superpro-preview+json
hook_id integer path
config object body

Key/value pairs to provide settings for this webhook.

Properties of the config object
url (string)

Required. The URL to which the payloads will be delivered.

content_type (string)

The media type used to serialize the payloads. Supported values include json and form. The default is form.

secret (string)

If provided, the secret will be used as the key to generate the HMAC hex digest value in the X-Hub-Signature header.

insecure_ssl (string)

Determines whether the SSL certificate of the host for url will be verified when delivering payloads. Supported values include 0 (verification is performed) and 1 (verification is not performed). The default is 0. We strongly recommend not setting this to 1 as you are subject to man-in-the-middle and other attacks.

events array of strings body

The events that trigger this webhook. A global webhook can be triggered by user and organization events. Default: user and organization.

active boolean body

Determines if notifications are sent when the webhook is triggered. Set to true to send notifications.

Default: true

代码示例

Shell
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.superpro-preview+json" \
  http(s)://{hostname}/api/v3/admin/hooks/42 \
  -d '{"config":{"url":"url","content_type":"content_type","secret":"secret","insecure_ssl":"insecure_ssl"}}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /admin/hooks/{hook_id}', {
  hook_id: 42,
  config: {
    url: 'url',
    content_type: 'content_type',
    secret: 'secret',
    insecure_ssl: 'insecure_ssl'
  },
  mediaType: {
    previews: [
      'superpro'
    ]
  }
})

Response

Status: 200 OK
{
  "type": "Global",
  "id": 1,
  "name": "web",
  "active": true,
  "events": [
    "organization"
  ],
  "config": {
    "url": "https://example.com",
    "content_type": "form",
    "insecure_ssl": "0"
  },
  "updated_at": "2017-12-07T00:14:59Z",
  "created_at": "2017-12-07T00:14:59Z",
  "url": "https://api.github.com/admin/hooks/1",
  "ping_url": "https://api.github.com/admin/hooks/1/pings"
}

预览通知

The Global Webhooks API is currently available for developers to preview. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.superpro-preview+json
☝️此标头必填.

Delete a global webhook

delete /admin/hooks/{hook_id}

参数

Name Type In Description
accept string header

This API is under preview and subject to change.查看预览通知

accept string header

This API is under preview and subject to change.

Default: application/vnd.github.superpro-preview+json
hook_id integer path

代码示例

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.superpro-preview+json" \
  http(s)://{hostname}/api/v3/admin/hooks/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /admin/hooks/{hook_id}', {
  hook_id: 42,
  mediaType: {
    previews: [
      'superpro'
    ]
  }
})

Response

Status: 204 No Content

预览通知

The Global Webhooks API is currently available for developers to preview. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.superpro-preview+json
☝️此标头必填.

Ping a global webhook

This will trigger a ping event to be sent to the webhook.

post /admin/hooks/{hook_id}/pings

参数

Name Type In Description
accept string header

This API is under preview and subject to change.查看预览通知

accept string header

This API is under preview and subject to change.

Default: application/vnd.github.superpro-preview+json
hook_id integer path

代码示例

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.superpro-preview+json" \
  http(s)://{hostname}/api/v3/admin/hooks/42/pings
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/hooks/{hook_id}/pings', {
  hook_id: 42,
  mediaType: {
    previews: [
      'superpro'
    ]
  }
})

Response

Status: 204 No Content

预览通知

The Global Webhooks API is currently available for developers to preview. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.superpro-preview+json
☝️此标头必填.

LDAP

您可以使用 LDAP API 来更新 GitHub Enterprise Server 用户或团队与其关联的 LDAP 条目之间的帐户关系,或者排队新同步。

通过 LDAP 映射端点,您可以更新用户或团队所映射的识别名称 (DN) 。 请注意,LDAP 端点通常只在您的 GitHub Enterprise Server 设备启用了 LDAP 同步时才有效。 启用了 LDAP 后,即使禁用 LDAP 同步,也可以使用更新用户的 LDAP 映射端点。

Update LDAP mapping for a team

Updates the distinguished name (DN) of the LDAP entry to map to a team. LDAP synchronization must be enabled to map LDAP entries to a team. Use the Create a team endpoint to create a team with LDAP mapping.

If you pass the hellcat-preview media type, you can also update the LDAP mapping of a child team.

patch /admin/ldap/teams/{team_id}/mapping

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.查看预览通知

team_id integer path
ldap_dn string body

Required. The distinguished name (DN) of the LDAP entry to map to a team.

代码示例

Shell
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/ldap/teams/42/mapping \
  -d '{"ldap_dn":"ldap_dn"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /admin/ldap/teams/{team_id}/mapping', {
  team_id: 42,
  ldap_dn: 'ldap_dn'
})

Response

Status: 200 OK
{
  "ldap_dn": "cn=Enterprise Ops,ou=teams,dc=github,dc=com",
  "id": 1,
  "node_id": "MDQ6VGVhbTE=",
  "url": "https://api.github.com/teams/1",
  "html_url": "https://github.com/orgs/github/teams/justice-league",
  "name": "Justice League",
  "slug": "justice-league",
  "description": "A great team.",
  "privacy": "closed",
  "permission": "admin",
  "members_url": "https://api.github.com/teams/1/members{/member}",
  "repositories_url": "https://api.github.com/teams/1/repos",
  "parent": null
}

预览通知

The Nested Teams API is currently available for developers to preview. See the blog post for full details. To access the API, you must provide a custom media type in the Accept header:

application/vnd.github.hellcat-preview+json

Sync LDAP mapping for a team

Note that this API call does not automatically initiate an LDAP sync. Rather, if a 201 is returned, the sync job is queued successfully, and is performed when the instance is ready.

post /admin/ldap/teams/{team_id}/sync

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

team_id integer path

代码示例

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/ldap/teams/42/sync
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/ldap/teams/{team_id}/sync', {
  team_id: 42
})

Response

Status: 201 Created
{
  "status": "queued"
}

Update LDAP mapping for a user

patch /admin/ldap/users/{username}/mapping

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

username string path
ldap_dn string body

Required. The distinguished name (DN) of the LDAP entry to map to a team.

代码示例

Shell
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/ldap/users/USERNAME/mapping \
  -d '{"ldap_dn":"ldap_dn"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /admin/ldap/users/{username}/mapping', {
  username: 'username',
  ldap_dn: 'ldap_dn'
})

Response

Status: 200 OK
{
  "ldap_dn": "uid=asdf,ou=users,dc=github,dc=com",
  "login": "octocat",
  "id": 1,
  "node_id": "MDQ6VXNlcjE=",
  "avatar_url": "https://github.com/images/error/octocat_happy.gif",
  "gravatar_id": "",
  "url": "https://api.github.com/users/octocat",
  "html_url": "https://github.com/octocat",
  "followers_url": "https://api.github.com/users/octocat/followers",
  "following_url": "https://api.github.com/users/octocat/following{/other_user}",
  "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
  "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
  "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
  "organizations_url": "https://api.github.com/users/octocat/orgs",
  "repos_url": "https://api.github.com/users/octocat/repos",
  "events_url": "https://api.github.com/users/octocat/events{/privacy}",
  "received_events_url": "https://api.github.com/users/octocat/received_events",
  "type": "User",
  "site_admin": false,
  "name": "monalisa octocat",
  "company": "GitHub",
  "blog": "https://github.com/blog",
  "location": "San Francisco",
  "email": "octocat@github.com",
  "hireable": false,
  "bio": "There once was...",
  "twitter_username": "monatheoctocat",
  "public_repos": 2,
  "public_gists": 1,
  "followers": 20,
  "following": 0,
  "created_at": "2008-01-14T04:33:35Z",
  "updated_at": "2008-01-14T04:33:35Z",
  "private_gists": 81,
  "total_private_repos": 100,
  "owned_private_repos": 100,
  "disk_usage": 10000,
  "collaborators": 8,
  "two_factor_authentication": true,
  "plan": {
    "name": "Medium",
    "space": 400,
    "private_repos": 20,
    "collaborators": 0
  }
}

Sync LDAP mapping for a user

Note that this API call does not automatically initiate an LDAP sync. Rather, if a 201 is returned, the sync job is queued successfully, and is performed when the instance is ready.

post /admin/ldap/users/{username}/sync

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

username string path

代码示例

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/ldap/users/USERNAME/sync
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/ldap/users/{username}/sync', {
  username: 'username'
})

Response

Status: 201 Created
{
  "status": "queued"
}

许可

许可 API 提供有关企业许可的信息。 它只适用于经过身份验证的站点管理员。普通用户尝试访问它时会收到 404 响应。

Get license information

get /enterprise/settings/license

代码示例

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprise/settings/license
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/settings/license')

Response

Status: 200 OK
{
  "seats": 1400,
  "seats_used": 1316,
  "seats_available": 84,
  "kind": "standard",
  "days_until_expiration": 365,
  "expire_at": "2016/02/06 12:41:52 -0600"
}

管理控制台

管理控制台 API 可帮助您管理 GitHub Enterprise Server 安装设施。

在对管理控制台进行 API 调用时,必须明确设置端口号。 如果在企业上启用了 TLS,则端口号为 8443;否则,端口号为 8080

如果您不想提供端口号,则需要将工具配置为自动遵循重定向。

使用 curl 时,您可能还需要添加 -k 标志,因为 GitHub Enterprise Server 在您添加自己的 TLS 证书之前会使用自签名证书。

身份验证

您需要将管理控制台密码作为身份验证令牌传递给除 /setup/api/start 之外的每个管理控制台 API 端点。

使用 api_key 参数在每个请求中发送此令牌。 例如:

$ curl -L 'https://hostname:admin_port/setup/api?api_key=your-amazing-password'

还可以使用标准 HTTP 身份验证发送此令牌。 例如:

$ curl -L 'https://api_key:your-amazing-password@hostname:admin_port/setup/api'

Get the configuration status

This endpoint allows you to check the status of the most recent configuration process:

Note that you may need to wait several seconds after you start a process before you can check its status.

The different statuses are:

StatusDescription
PENDINGThe job has not started yet
CONFIGURINGThe job is running
DONEThe job has finished correctly
FAILEDThe job has finished unexpectedly
get /setup/api/configcheck

代码示例

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/setup/api/configcheck
JavaScript (@octokit/core.js)
await octokit.request('GET /setup/api/configcheck')

Response

Status: 200 OK
{
  "status": "running",
  "progress": [
    {
      "status": "DONE",
      "key": "Appliance core components"
    },
    {
      "status": "DONE",
      "key": "GitHub utilities"
    },
    {
      "status": "DONE",
      "key": "GitHub applications"
    },
    {
      "status": "CONFIGURING",
      "key": "GitHub services"
    },
    {
      "status": "PENDING",
      "key": "Reloading appliance services"
    }
  ]
}

Start a configuration process

This endpoint allows you to start a configuration process at any time for your updated settings to take effect:

post /setup/api/configure

代码示例

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/setup/api/configure
JavaScript (@octokit/core.js)
await octokit.request('POST /setup/api/configure')

Response

Status: 202 Accepted

Get the maintenance status

Check your installation's maintenance status:

get /setup/api/maintenance

代码示例

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/setup/api/maintenance
JavaScript (@octokit/core.js)
await octokit.request('GET /setup/api/maintenance')

Response

Status: 200 OK
{
  "status": "scheduled",
  "scheduled_time": "Tuesday, January 22 at 15:34 -0800",
  "connection_services": [
    {
      "name": "git operations",
      "number": 0
    },
    {
      "name": "mysql queries",
      "number": 233
    },
    {
      "name": "resque jobs",
      "number": 54
    }
  ]
}

Enable or disable maintenance mode

Note: The request body for this operation must be submitted as application/x-www-form-urlencoded data. You can submit a parameter value as a string, or you can use a tool such as curl to submit a parameter value as the contents of a text file. For more information, see the curl documentation.

post /setup/api/maintenance

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

maintenance string body

Required. A JSON string with the attributes enabled and when.

The possible values for enabled are true and false. When it's false, the attribute when is ignored and the maintenance mode is turned off. when defines the time period when the maintenance was enabled.

The possible values for when are now or any date parseable by mojombo/chronic.

代码示例

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/setup/api/maintenance \
  --data-urlencode maintenance=maintenance
JavaScript (@octokit/core.js)
await octokit.request('POST /setup/api/maintenance', {
  maintenance: 'maintenance'
})

Response

Status: 200 OK
{
  "status": "scheduled",
  "scheduled_time": "Tuesday, January 22 at 15:34 -0800",
  "connection_services": [
    {
      "name": "git operations",
      "number": 0
    },
    {
      "name": "mysql queries",
      "number": 233
    },
    {
      "name": "resque jobs",
      "number": 54
    }
  ]
}

Get settings

get /setup/api/settings

代码示例

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/setup/api/settings
JavaScript (@octokit/core.js)
await octokit.request('GET /setup/api/settings')

Response

Status: 200 OK
{
  "enterprise": {
    "private_mode": false,
    "public_pages": false,
    "subdomain_isolation": true,
    "signup_enabled": false,
    "github_hostname": "ghe.local",
    "identicons_host": "dotcom",
    "http_proxy": null,
    "auth_mode": "default",
    "expire_sessions": false,
    "admin_password": null,
    "configuration_id": 1401777404,
    "configuration_run_count": 4,
    "avatar": {
      "enabled": false,
      "uri": ""
    },
    "customer": {
      "name": "GitHub",
      "email": "stannis@themannis.biz",
      "uuid": "af6cac80-e4e1-012e-d822-1231380e52e9",
      "secret_key_data": "-----BEGIN PGP PRIVATE KEY BLOCK-----\nVersion: GnuPG v1.4.10 (GNU/Linux)\n\nlQcYBE5TCgsBEACk4yHpUcapplebaumBMXYMiLF+nCQ0lxpx...\n-----END PGP PRIVATE KEY BLOCK-----\n",
      "public_key_data": "-----BEGIN PGP PUBLIC KEY BLOCK-----\nVersion: GnuPG v1.4.10 (GNU/Linux)\n\nmI0ETqzZYgEEALSe6snowdenXyqvLfSQ34HWD6C7....\n-----END PGP PUBLIC KEY BLOCK-----\n"
    },
    "license": {
      "seats": 0,
      "evaluation": false,
      "perpetual": false,
      "unlimited_seating": true,
      "support_key": "ssh-rsa AAAAB3N....",
      "ssh_allowed": true,
      "cluster_support": false,
      "expire_at": "2016-04-27T00:00:00-07:00"
    },
    "github_ssl": {
      "enabled": false,
      "cert": null,
      "key": null
    },
    "ldap": {
      "host": null,
      "port": 0,
      "base": [],
      "uid": null,
      "bind_dn": null,
      "password": null,
      "method": "Plain",
      "search_strategy": "detect",
      "user_groups": [],
      "admin_group": null,
      "virtual_attribute_enabled": false,
      "recursive_group_search": false,
      "posix_support": true,
      "user_sync_emails": false,
      "user_sync_keys": false,
      "user_sync_interval": 4,
      "team_sync_interval": 4,
      "sync_enabled": false,
      "reconciliation": {
        "user": null,
        "org": null
      },
      "profile": {
        "uid": "uid",
        "name": null,
        "mail": null,
        "key": null
      }
    },
    "cas": {
      "url": null
    },
    "saml": {
      "sso_url": null,
      "certificate": null,
      "certificate_path": null,
      "issuer": null,
      "idp_initiated_sso": false,
      "disable_admin_demote": false
    },
    "github_oauth": {
      "client_id": "12313412",
      "client_secret": "kj123131132",
      "organization_name": "Homestar Runners",
      "organization_team": "homestarrunners/characters"
    },
    "smtp": {
      "enabled": true,
      "address": "smtp.example.com",
      "authentication": "plain",
      "port": "1234",
      "domain": "blah",
      "username": "foo",
      "user_name": "mr_foo",
      "enable_starttls_auto": true,
      "password": "bar",
      "discard-to-noreply-address": true,
      "support_address": "enterprise@github.com",
      "support_address_type": "email",
      "noreply_address": "noreply@github.com"
    },
    "ntp": {
      "primary_server": "0.pool.ntp.org",
      "secondary_server": "1.pool.ntp.org"
    },
    "timezone": null,
    "snmp": {
      "enabled": false,
      "community": ""
    },
    "syslog": {
      "enabled": false,
      "server": null,
      "protocol_name": "udp"
    },
    "assets": null,
    "pages": {
      "enabled": true
    },
    "collectd": {
      "enabled": false,
      "server": null,
      "port": 0,
      "encryption": null,
      "username": null,
      "password": null
    },
    "mapping": {
      "enabled": true,
      "tileserver": null,
      "basemap": "company.map-qsz2zrvs",
      "token": null
    },
    "load_balancer": null
  },
  "run_list": [
    "recipe[enterprise-configure]"
  ]
}

Set settings

For a list of the available settings, see the Get settings endpoint.

Note: The request body for this operation must be submitted as application/x-www-form-urlencoded data. You can submit a parameter value as a string, or you can use a tool such as curl to submit a parameter value as the contents of a text file. For more information, see the curl documentation.

put /setup/api/settings

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

settings string body

Required. A JSON string with the new settings. Note that you only need to pass the specific settings you want to modify. For a list of the available settings, see the Get settings endpoint.

代码示例

Shell
curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/setup/api/settings \
  --data-urlencode settings=settings
JavaScript (@octokit/core.js)
await octokit.request('PUT /setup/api/settings', {
  settings: 'settings'
})

Response

Status: 204 No Content

Get all authorized SSH keys

get /setup/api/settings/authorized-keys

代码示例

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/setup/api/settings/authorized-keys
JavaScript (@octokit/core.js)
await octokit.request('GET /setup/api/settings/authorized-keys')

Response

Status: 200 OK
[
  {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
    "pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
  },
  {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
    "pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
  },
  {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
    "pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
  }
]

Add an authorized SSH key

Note: The request body for this operation must be submitted as application/x-www-form-urlencoded data. You can submit a parameter value as a string, or you can use a tool such as curl to submit a parameter value as the contents of a text file. For more information, see the curl documentation.

post /setup/api/settings/authorized-keys

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

authorized_key string body

Required. The public SSH key.

代码示例

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/setup/api/settings/authorized-keys \
  --data-urlencode authorized_key=authorized_key
JavaScript (@octokit/core.js)
await octokit.request('POST /setup/api/settings/authorized-keys', {
  authorized_key: 'authorized_key'
})

Response

Status: 201 Created
[
  {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
    "pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
  },
  {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
    "pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
  },
  {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
    "pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
  }
]

Remove an authorized SSH key

Note: The request body for this operation must be submitted as application/x-www-form-urlencoded data. You can submit a parameter value as a string, or you can use a tool such as curl to submit a parameter value as the contents of a text file. For more information, see the curl documentation.

delete /setup/api/settings/authorized-keys

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

authorized_key string body

Required. The public SSH key.

代码示例

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/setup/api/settings/authorized-keys \
  --data-urlencode authorized_key=authorized_key
JavaScript (@octokit/core.js)
await octokit.request('DELETE /setup/api/settings/authorized-keys', {
  authorized_key: 'authorized_key'
})

Response

Status: 200 OK
[
  {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
    "pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
  },
  {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
    "pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
  },
  {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
    "pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
  }
]

Create a GitHub license

When you boot a GitHub instance for the first time, you can use the following endpoint to upload a license.

Note that you need to POST to /setup/api/configure to start the actual configuration process.

When using this endpoint, your GitHub instance must have a password set. This can be accomplished two ways:

  1. If you're working directly with the API before accessing the web interface, you must pass in the password parameter to set your password.
  2. If you set up your instance via the web interface before accessing the API, your calls to this endpoint do not need the password parameter.

Note: The request body for this operation must be submitted as application/x-www-form-urlencoded data. You can submit a parameter value as a string, or you can use a tool such as curl to submit a parameter value as the contents of a text file. For more information, see the curl documentation.

post /setup/api/start

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

license string body

Required. The content of your .ghl license file.

password string body

You must provide a password only if you are uploading your license for the first time. If you previously set a password through the web interface, you don't need this parameter.

settings string body

An optional JSON string containing the installation settings. For a list of the available settings, see the Get settings endpoint.

代码示例

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/setup/api/start \
  --data-urlencode license=license
JavaScript (@octokit/core.js)
await octokit.request('POST /setup/api/start', {
  license: 'license'
})

Response

Status: 202 Accepted

Upgrade a license

This API upgrades your license and also triggers the configuration process.

Note: The request body for this operation must be submitted as application/x-www-form-urlencoded data. You can submit a parameter value as a string, or you can use a tool such as curl to submit a parameter value as the contents of a text file. For more information, see the curl documentation.

post /setup/api/upgrade

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

license string body

The content of your new .ghl license file.

代码示例

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/setup/api/upgrade \
  --data-urlencode license=license
JavaScript (@octokit/core.js)
await octokit.request('POST /setup/api/upgrade', {
  license: 'license'
})

Response

Status: 202 Accepted

组织

组织管理 API 允许您在企业上创建组织。 它只适用于经过身份验证的站点管理员。普通用户尝试访问它时会收到 404 响应。

Create an organization

post /admin/organizations

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

login string body

Required. The organization's username.

admin string body

Required. The login of the user who will manage this organization.

profile_name string body

The organization's display name.

代码示例

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/organizations \
  -d '{"login":"login","admin":"admin"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/organizations', {
  login: 'login',
  admin: 'admin'
})

Response

Status: 201 Created
{
  "login": "github",
  "id": 1,
  "node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
  "url": "https://api.github.com/orgs/github",
  "repos_url": "https://api.github.com/orgs/github/repos",
  "events_url": "https://api.github.com/orgs/github/events",
  "hooks_url": "https://api.github.com/orgs/github/hooks",
  "issues_url": "https://api.github.com/orgs/github/issues",
  "members_url": "https://api.github.com/orgs/github/members{/member}",
  "public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
  "avatar_url": "https://github.com/images/error/octocat_happy.gif",
  "description": "A great organization"
}

Update an organization name

patch /admin/organizations/{org}

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path
login string body

Required. The organization's new name.

代码示例

Shell
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/organizations/ORG \
  -d '{"login":"login"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /admin/organizations/{org}', {
  org: 'org',
  login: 'login'
})

Response

Status: 202 Accepted
{
  "message": "Job queued to rename organization. It may take a few minutes to complete.",
  "url": "https://<hostname>/api/v3/organizations/1"
}

组织预接收挂钩

组织预接收挂钩 API 允许您查看和修改组织可用的预接收挂钩的实施。

对象属性

名称类型描述
name字符串挂钩的名称。
enforcement字符串此仓库中挂钩的实施状态。
allow_downstream_configuration布尔值仓库是否可以覆盖实施。
configuration_url字符串设置实施的端点 URL。

enforcement 的可能值包括 enableddisabledtestingdisabled 表示预接收挂钩不会运行。 enabled 表示它将运行并拒绝会导致非零状态的任何推送。 testing 表示脚本将运行,但不会导致任何推送被拒绝。

configuration_url 可能是此端点或此挂钩的全局配置的链接。 只有站点管理员才能访问全局配置。

List pre-receive hooks for an organization

List all pre-receive hooks that are enabled or testing for this organization as well as any disabled hooks that can be configured at the organization level. Globally disabled pre-receive hooks that do not allow downstream configuration are not listed.

get /orgs/{org}/pre-receive-hooks

参数

Name Type In Description
accept string header

This API is under preview and subject to change.查看预览通知

org string path
per_page integer query

Results per page (max 100)

Default: 30
page integer query

Page number of the results to fetch.

Default: 1
direction string query

One of asc (ascending) or desc (descending).

Default: desc
sort string query

The sort order for the response collection.

Default: created

代码示例

Shell
curl \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/orgs/ORG/pre-receive-hooks
JavaScript (@octokit/core.js)
await octokit.request('GET /orgs/{org}/pre-receive-hooks', {
  org: 'org',
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 200 OK
[
  {
    "id": 42,
    "name": "Check Commits",
    "enforcement": "disabled",
    "configuration_url": "https://github.example.com/api/v3/admin/pre-receive-hooks/42",
    "allow_downstream_configuration": true
  }
]

Notes

预览通知

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️此标头必填.

Get a pre-receive hook for an organization

get /orgs/{org}/pre-receive-hooks/{pre_receive_hook_id}

参数

Name Type In Description
accept string header

This API is under preview and subject to change.查看预览通知

org string path
pre_receive_hook_id integer path

pre_receive_hook_id parameter

代码示例

Shell
curl \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/orgs/ORG/pre-receive-hooks/42
JavaScript (@octokit/core.js)
await octokit.request('GET /orgs/{org}/pre-receive-hooks/{pre_receive_hook_id}', {
  org: 'org',
  pre_receive_hook_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 200 OK
{
  "id": 42,
  "name": "Check Commits",
  "enforcement": "disabled",
  "configuration_url": "https://github.example.com/api/v3/admin/pre-receive-hooks/42",
  "allow_downstream_configuration": true
}

Notes

预览通知

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️此标头必填.

Update pre-receive hook enforcement for an organization

For pre-receive hooks which are allowed to be configured at the org level, you can set enforcement and allow_downstream_configuration

patch /orgs/{org}/pre-receive-hooks/{pre_receive_hook_id}

参数

Name Type In Description
accept string header

This API is under preview and subject to change.查看预览通知

org string path
pre_receive_hook_id integer path

pre_receive_hook_id parameter

enforcement string body

The state of enforcement for the hook on this repository.

allow_downstream_configuration boolean body

Whether repositories can override enforcement.

代码示例

Shell
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/orgs/ORG/pre-receive-hooks/42 \
  -d '{"enforcement":"enforcement"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /orgs/{org}/pre-receive-hooks/{pre_receive_hook_id}', {
  org: 'org',
  pre_receive_hook_id: 42,
  enforcement: 'enforcement',
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 200 OK
{
  "id": 42,
  "name": "Check Commits",
  "enforcement": "enabled",
  "configuration_url": "https://github.example.com/api/v3/orgs/octocat/pre-receive-hooks/42",
  "allow_downstream_configuration": false
}

Notes

预览通知

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️此标头必填.

Remove pre-receive hook enforcement for an organization

Removes any overrides for this hook at the org level for this org.

delete /orgs/{org}/pre-receive-hooks/{pre_receive_hook_id}

参数

Name Type In Description
accept string header

This API is under preview and subject to change.查看预览通知

org string path
pre_receive_hook_id integer path

pre_receive_hook_id parameter

代码示例

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/orgs/ORG/pre-receive-hooks/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /orgs/{org}/pre-receive-hooks/{pre_receive_hook_id}', {
  org: 'org',
  pre_receive_hook_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 200 OK
{
  "id": 42,
  "name": "Check Commits",
  "enforcement": "disabled",
  "configuration_url": "https://github.example.com/api/v3/admin/pre-receive-hooks/42",
  "allow_downstream_configuration": true
}

Notes

预览通知

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️此标头必填.

预接收环境

预接收环境 API 允许您创建、列出、更新和删除预接收挂钩的环境。 它只适用于经过身份验证的站点管理员。普通用户尝试访问它时会收到 404 响应。

对象属性

预接收环境

名称类型描述
name字符串UI 中显示的环境名称。
image_url字符串将要下载并解压缩的 tarball 的 URL。
default_environment布尔值这是否是 GitHub Enterprise Server 附带的默认环境。
download对象此环境的下载状态。
hooks_count整数使用此环境的预接收挂钩数量。

预接收环境下载

名称类型描述
state字符串最近下载的状态。
downloaded_at字符串最近下载开始的时间。
message字符串在失败时生成任何错误消息。

state 的可能值包括 not_startedin_progresssuccessfailed

List pre-receive environments

get /admin/pre-receive-environments

参数

Name Type In Description
accept string header

This API is under preview and subject to change.查看预览通知

per_page integer query

Results per page (max 100)

Default: 30
page integer query

Page number of the results to fetch.

Default: 1
direction string query

One of asc (ascending) or desc (descending).

Default: desc
sort string query Default: created

代码示例

Shell
curl \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/admin/pre-receive-environments
JavaScript (@octokit/core.js)
await octokit.request('GET /admin/pre-receive-environments', {
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 200 OK
[
  {
    "id": 1,
    "name": "Default",
    "image_url": "githubenterprise://internal",
    "url": "https://github.example.com/api/v3/admin/pre-receive-environments/1",
    "html_url": "https://github.example.com/admin/pre-receive-environments/1",
    "default_environment": true,
    "created_at": "2016-05-20T11:35:45-05:00",
    "hooks_count": 14,
    "download": {
      "url": "https://github.example.com/api/v3/admin/pre-receive-environments/1/downloads/latest",
      "state": "not_started",
      "downloaded_at": "2016-05-26T07:42:53-05:00",
      "message": null
    }
  },
  {
    "id": 2,
    "name": "DevTools Hook Env",
    "image_url": "https://my_file_server/path/to/devtools_env.tar.gz",
    "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2",
    "html_url": "https://github.example.com/admin/pre-receive-environments/2",
    "default_environment": false,
    "created_at": "2016-05-20T11:35:45-05:00",
    "hooks_count": 1,
    "download": {
      "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2/downloads/latest",
      "state": "success",
      "downloaded_at": "2016-05-26T07:42:53-05:00",
      "message": null
    }
  }
]

预览通知

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️此标头必填.

Create a pre-receive environment

post /admin/pre-receive-environments

参数

Name Type In Description
accept string header

This API is under preview and subject to change.查看预览通知

name string body

Required. The new pre-receive environment's name.

image_url string body

Required. URL from which to download a tarball of this environment.

代码示例

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/admin/pre-receive-environments \
  -d '{"name":"name","image_url":"image_url"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/pre-receive-environments', {
  name: 'name',
  image_url: 'image_url',
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 201 Created
{
  "id": 2,
  "name": "DevTools Hook Env",
  "image_url": "https://my_file_server/path/to/devtools_env.tar.gz",
  "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2",
  "html_url": "https://github.example.com/admin/pre-receive-environments/2",
  "default_environment": false,
  "created_at": "2016-05-20T11:35:45-05:00",
  "hooks_count": 1,
  "download": {
    "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2/downloads/latest",
    "state": "not_started",
    "downloaded_at": null,
    "message": null
  }
}

预览通知

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️此标头必填.

Get a pre-receive environment

get /admin/pre-receive-environments/{pre_receive_environment_id}

参数

Name Type In Description
accept string header

This API is under preview and subject to change.查看预览通知

pre_receive_environment_id integer path

代码示例

Shell
curl \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/admin/pre-receive-environments/42
JavaScript (@octokit/core.js)
await octokit.request('GET /admin/pre-receive-environments/{pre_receive_environment_id}', {
  pre_receive_environment_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 200 OK
{
  "id": 2,
  "name": "DevTools Hook Env",
  "image_url": "https://my_file_server/path/to/devtools_env.tar.gz",
  "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2",
  "html_url": "https://github.example.com/admin/pre-receive-environments/2",
  "default_environment": false,
  "created_at": "2016-05-20T11:35:45-05:00",
  "hooks_count": 1,
  "download": {
    "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2/downloads/latest",
    "state": "not_started",
    "downloaded_at": null,
    "message": null
  }
}

预览通知

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️此标头必填.

Update a pre-receive environment

You cannot modify the default environment. If you attempt to modify the default environment, you will receive a 422 Unprocessable Entity response.

patch /admin/pre-receive-environments/{pre_receive_environment_id}

参数

Name Type In Description
accept string header

This API is under preview and subject to change.查看预览通知

pre_receive_environment_id integer path
name string body

This pre-receive environment's new name.

image_url string body

URL from which to download a tarball of this environment.

代码示例

Shell
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/admin/pre-receive-environments/42 \
  -d '{"name":"name"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /admin/pre-receive-environments/{pre_receive_environment_id}', {
  pre_receive_environment_id: 42,
  name: 'name',
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 200 OK
{
  "id": 2,
  "name": "DevTools Hook Env",
  "image_url": "https://my_file_server/path/to/devtools_env.tar.gz",
  "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2",
  "html_url": "https://github.example.com/admin/pre-receive-environments/2",
  "default_environment": false,
  "created_at": "2016-05-20T11:35:45-05:00",
  "hooks_count": 1,
  "download": {
    "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2/downloads/latest",
    "state": "success",
    "downloaded_at": "2016-05-26T07:42:53-05:00",
    "message": null
  }
}

Client Errors

Status: 422 Unprocessable Entity
{
  "message": "Validation Failed",
  "errors": [
    {
      "resource": "PreReceiveEnvironment",
      "code": "custom",
      "message": "Cannot modify or delete the default environment"
    }
  ]
}

预览通知

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️此标头必填.

Delete a pre-receive environment

If you attempt to delete an environment that cannot be deleted, you will receive a 422 Unprocessable Entity response.

The possible error messages are:

  • Cannot modify or delete the default environment
  • Cannot delete environment that has hooks
  • Cannot delete environment when download is in progress
delete /admin/pre-receive-environments/{pre_receive_environment_id}

参数

Name Type In Description
accept string header

This API is under preview and subject to change.查看预览通知

pre_receive_environment_id integer path

代码示例

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/admin/pre-receive-environments/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /admin/pre-receive-environments/{pre_receive_environment_id}', {
  pre_receive_environment_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 204 No Content

Client Errors

Status: 422 Unprocessable Entity
{
  "message": "Validation Failed",
  "errors": [
    {
      "resource": "PreReceiveEnvironment",
      "code": "custom",
      "message": "Cannot modify or delete the default environment"
    }
  ]
}

预览通知

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️此标头必填.

Start a pre-receive environment download

Triggers a new download of the environment tarball from the environment's image_url. When the download is finished, the newly downloaded tarball will overwrite the existing environment.

If a download cannot be triggered, you will receive a 422 Unprocessable Entity response.

The possible error messages are:

  • Cannot modify or delete the default environment
  • Can not start a new download when a download is in progress
post /admin/pre-receive-environments/{pre_receive_environment_id}/downloads

参数

Name Type In Description
accept string header

This API is under preview and subject to change.查看预览通知

pre_receive_environment_id integer path

代码示例

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/admin/pre-receive-environments/42/downloads
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/pre-receive-environments/{pre_receive_environment_id}/downloads', {
  pre_receive_environment_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 202 Accepted
{
  "url": "https://github.example.com/api/v3/admin/pre-receive-environments/3/downloads/latest",
  "state": "not_started",
  "downloaded_at": null,
  "message": null
}

Client Errors

Status: 422 Unprocessable Entity
{
  "message": "Validation Failed",
  "errors": [
    {
      "resource": "PreReceiveEnvironment",
      "code": "custom",
      "message": "Can not start a new download when a download is in progress"
    }
  ]
}

预览通知

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️此标头必填.

Get the download status for a pre-receive environment

In addition to seeing the download status at the "Get a pre-receive environment" endpoint, there is also this separate endpoint for just the download status.

get /admin/pre-receive-environments/{pre_receive_environment_id}/downloads/latest

参数

Name Type In Description
accept string header

This API is under preview and subject to change.查看预览通知

pre_receive_environment_id integer path

代码示例

Shell
curl \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/admin/pre-receive-environments/42/downloads/latest
JavaScript (@octokit/core.js)
await octokit.request('GET /admin/pre-receive-environments/{pre_receive_environment_id}/downloads/latest', {
  pre_receive_environment_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 200 OK
{
  "url": "https://github.example.com/api/v3/admin/pre-receive-environments/3/downloads/latest",
  "state": "success",
  "downloaded_at": "2016-05-26T07:42:53-05:00",
  "message": null
}

预览通知

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️此标头必填.

预接收挂钩

预接收挂钩 API 允许您创建、列出、更新和删除预接收挂钩。 它只适用于经过身份验证的站点管理员。普通用户尝试访问它时会收到 404 响应。

对象属性

预接收挂钩

名称类型描述
name字符串挂钩的名称。
script字符串挂钩运行的脚本。
script_repository对象保存脚本的 GitHub 仓库。
environment对象执行脚本的预接收环境。
enforcement字符串此挂钩的实施状态。
allow_downstream_configuration布尔值是否可以在组织或仓库级别上覆盖实施。

enforcement 的可能值包括 enableddisabledtestingdisabled 表示预接收挂钩不会运行。 enabled 表示它将运行并拒绝会导致非零状态的任何推送。 testing 表示脚本将运行,但不会导致任何推送被拒绝。

List pre-receive hooks

get /admin/pre-receive-hooks

参数

Name Type In Description
accept string header

This API is under preview and subject to change.查看预览通知

per_page integer query

Results per page (max 100)

Default: 30
page integer query

Page number of the results to fetch.

Default: 1
direction string query

One of asc (ascending) or desc (descending).

Default: desc
sort string query

One of created (when the repository was starred) or updated (when it was last pushed to) or name.

Default: created

代码示例

Shell
curl \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/admin/pre-receive-hooks
JavaScript (@octokit/core.js)
await octokit.request('GET /admin/pre-receive-hooks', {
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 200 OK
[
  {
    "id": 1,
    "name": "Check Commits",
    "enforcement": "disabled",
    "script": "scripts/commmit_check.sh",
    "script_repository": {
      "id": 595,
      "full_name": "DevIT/hooks",
      "url": "https://github.example.com/api/v3/repos/DevIT/hooks",
      "html_url": "https://github.example.com/DevIT/hooks"
    },
    "environment": {
      "id": 2,
      "name": "DevTools Hook Env",
      "image_url": "https://my_file_server/path/to/devtools_env.tar.gz",
      "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2",
      "html_url": "https://github.example.com/admin/pre-receive-environments/2",
      "default_environment": false,
      "created_at": "2016-05-20T11:35:45-05:00",
      "hooks_count": 1,
      "download": {
        "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2/downloads/latest",
        "state": "success",
        "downloaded_at": "2016-05-26T07:42:53-05:00",
        "message": null
      }
    },
    "allow_downstream_configuration": false
  }
]

预览通知

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️此标头必填.

Create a pre-receive hook

post /admin/pre-receive-hooks

参数

Name Type In Description
accept string header

This API is under preview and subject to change.查看预览通知

name string body

Required. The name of the hook.

script string body

Required. The script that the hook runs.

script_repository object body

Required. The GitHub repository where the script is kept.

environment object body

Required. The pre-receive environment where the script is executed.

enforcement string body

The state of enforcement for this hook. default: disabled

allow_downstream_configuration boolean body

Whether enforcement can be overridden at the org or repo level. default: false

代码示例

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/admin/pre-receive-hooks \
  -d '{"name":"name","script":"script","script_repository":{},"environment":{}}'
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/pre-receive-hooks', {
  name: 'name',
  script: 'script',
  script_repository: {},
  environment: {},
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 201 Created
{
  "id": 1,
  "name": "Check Commits",
  "enforcement": "disabled",
  "script": "scripts/commmit_check.sh",
  "script_repository": {
    "id": 595,
    "full_name": "DevIT/hooks",
    "url": "https://github.example.com/api/v3/repos/DevIT/hooks",
    "html_url": "https://github.example.com/DevIT/hooks"
  },
  "environment": {
    "id": 2,
    "name": "DevTools Hook Env",
    "image_url": "https://my_file_server/path/to/devtools_env.tar.gz",
    "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2",
    "html_url": "https://github.example.com/admin/pre-receive-environments/2",
    "default_environment": false,
    "created_at": "2016-05-20T11:35:45-05:00",
    "hooks_count": 1,
    "download": {
      "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2/downloads/latest",
      "state": "success",
      "downloaded_at": "2016-05-26T07:42:53-05:00",
      "message": null
    }
  },
  "allow_downstream_configuration": false
}

预览通知

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️此标头必填.

Get a pre-receive hook

get /admin/pre-receive-hooks/{pre_receive_hook_id}

参数

Name Type In Description
accept string header

This API is under preview and subject to change.查看预览通知

pre_receive_hook_id integer path

pre_receive_hook_id parameter

代码示例

Shell
curl \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/admin/pre-receive-hooks/42
JavaScript (@octokit/core.js)
await octokit.request('GET /admin/pre-receive-hooks/{pre_receive_hook_id}', {
  pre_receive_hook_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 200 OK
{
  "id": 1,
  "name": "Check Commits",
  "enforcement": "disabled",
  "script": "scripts/commmit_check.sh",
  "script_repository": {
    "id": 595,
    "full_name": "DevIT/hooks",
    "url": "https://github.example.com/api/v3/repos/DevIT/hooks",
    "html_url": "https://github.example.com/DevIT/hooks"
  },
  "environment": {
    "id": 2,
    "name": "DevTools Hook Env",
    "image_url": "https://my_file_server/path/to/devtools_env.tar.gz",
    "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2",
    "html_url": "https://github.example.com/admin/pre-receive-environments/2",
    "default_environment": false,
    "created_at": "2016-05-20T11:35:45-05:00",
    "hooks_count": 1,
    "download": {
      "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2/downloads/latest",
      "state": "success",
      "downloaded_at": "2016-05-26T07:42:53-05:00",
      "message": null
    }
  },
  "allow_downstream_configuration": false
}

预览通知

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️此标头必填.

Update a pre-receive hook

patch /admin/pre-receive-hooks/{pre_receive_hook_id}

参数

Name Type In Description
accept string header

This API is under preview and subject to change.查看预览通知

pre_receive_hook_id integer path

pre_receive_hook_id parameter

name string body

The name of the hook.

script string body

The script that the hook runs.

script_repository object body

The GitHub repository where the script is kept.

environment object body

The pre-receive environment where the script is executed.

enforcement string body

The state of enforcement for this hook.

allow_downstream_configuration boolean body

Whether enforcement can be overridden at the org or repo level.

代码示例

Shell
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/admin/pre-receive-hooks/42 \
  -d '{"name":"name"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /admin/pre-receive-hooks/{pre_receive_hook_id}', {
  pre_receive_hook_id: 42,
  name: 'name',
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 200 OK
{
  "id": 1,
  "name": "Check Commits",
  "enforcement": "disabled",
  "script": "scripts/commmit_check.sh",
  "script_repository": {
    "id": 595,
    "full_name": "DevIT/hooks",
    "url": "https://github.example.com/api/v3/repos/DevIT/hooks",
    "html_url": "https://github.example.com/DevIT/hooks"
  },
  "environment": {
    "id": 1,
    "name": "Default",
    "image_url": "githubenterprise://internal",
    "url": "https://github.example.com/api/v3/admin/pre-receive-environments/1",
    "html_url": "https://github.example.com/admin/pre-receive-environments/1",
    "default_environment": true,
    "created_at": "2016-05-20T11:35:45-05:00",
    "hooks_count": 1,
    "download": {
      "url": "https://github.example.com/api/v3/admin/pre-receive-environments/1/downloads/latest",
      "state": "success",
      "downloaded_at": "2016-05-26T07:42:53-05:00",
      "message": null
    }
  },
  "allow_downstream_configuration": true
}

预览通知

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️此标头必填.

Delete a pre-receive hook

delete /admin/pre-receive-hooks/{pre_receive_hook_id}

参数

Name Type In Description
accept string header

This API is under preview and subject to change.查看预览通知

pre_receive_hook_id integer path

pre_receive_hook_id parameter

代码示例

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/admin/pre-receive-hooks/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /admin/pre-receive-hooks/{pre_receive_hook_id}', {
  pre_receive_hook_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 204 No Content

预览通知

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️此标头必填.

仓库预接收挂钩

仓库预接收挂钩 API 允许您查看和修改仓库可用的预接收挂钩的实施。

对象属性

名称类型描述
name字符串挂钩的名称。
enforcement字符串此仓库中挂钩的实施状态。
configuration_url字符串设置实施的端点 URL。

enforcement 的可能值包括 enableddisabledtestingdisabled 表示预接收挂钩不会运行。 enabled 表示它将运行并拒绝会导致非零状态的任何推送。 testing 表示脚本将运行,但不会导致任何推送被拒绝。

configuration_url 可能是此仓库、其组织所有者或全局配置的链接。 configuration_url 端点的访问授权在所有者或站点管理员级别确定。

List pre-receive hooks for a repository

List all pre-receive hooks that are enabled or testing for this repository as well as any disabled hooks that are allowed to be enabled at the repository level. Pre-receive hooks that are disabled at a higher level and are not configurable will not be listed.

get /repos/{owner}/{repo}/pre-receive-hooks

参数

Name Type In Description
accept string header

This API is under preview and subject to change.查看预览通知

owner string path
repo string path
per_page integer query

Results per page (max 100)

Default: 30
page integer query

Page number of the results to fetch.

Default: 1
direction string query

One of asc (ascending) or desc (descending).

Default: desc
sort string query Default: created

代码示例

Shell
curl \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/repos/octocat/hello-world/pre-receive-hooks
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/pre-receive-hooks', {
  owner: 'octocat',
  repo: 'hello-world',
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 200 OK
[
  {
    "id": 42,
    "name": "Check Commits",
    "enforcement": "disabled",
    "configuration_url": "https://github.example.com/api/v3/orgs/octocat/pre-receive-hooks/42"
  }
]

Notes

预览通知

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️此标头必填.

Get a pre-receive hook for a repository

get /repos/{owner}/{repo}/pre-receive-hooks/{pre_receive_hook_id}

参数

Name Type In Description
accept string header

This API is under preview and subject to change.查看预览通知

owner string path
repo string path
pre_receive_hook_id integer path

pre_receive_hook_id parameter

代码示例

Shell
curl \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/repos/octocat/hello-world/pre-receive-hooks/42
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/pre-receive-hooks/{pre_receive_hook_id}', {
  owner: 'octocat',
  repo: 'hello-world',
  pre_receive_hook_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 200 OK
{
  "id": 42,
  "name": "Check Commits",
  "enforcement": "disabled",
  "configuration_url": "https://github.example.com/api/v3/orgs/octocat/pre-receive-hooks/42"
}

Notes

预览通知

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️此标头必填.

Update pre-receive hook enforcement for a repository

For pre-receive hooks which are allowed to be configured at the repo level, you can set enforcement

patch /repos/{owner}/{repo}/pre-receive-hooks/{pre_receive_hook_id}

参数

Name Type In Description
accept string header

This API is under preview and subject to change.查看预览通知

owner string path
repo string path
pre_receive_hook_id integer path

pre_receive_hook_id parameter

enforcement string body

The state of enforcement for the hook on this repository.

代码示例

Shell
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/repos/octocat/hello-world/pre-receive-hooks/42 \
  -d '{"enforcement":"enforcement"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /repos/{owner}/{repo}/pre-receive-hooks/{pre_receive_hook_id}', {
  owner: 'octocat',
  repo: 'hello-world',
  pre_receive_hook_id: 42,
  enforcement: 'enforcement',
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 200 OK
{
  "id": 42,
  "name": "Check Commits",
  "enforcement": "enabled",
  "configuration_url": "https://github.example.com/api/v3/repos/octocat/hello-world/pre-receive-hooks/42"
}

Notes

预览通知

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️此标头必填.

Remove pre-receive hook enforcement for a repository

Deletes any overridden enforcement on this repository for the specified hook.

Responds with effective values inherited from owner and/or global level.

delete /repos/{owner}/{repo}/pre-receive-hooks/{pre_receive_hook_id}

参数

Name Type In Description
accept string header

This API is under preview and subject to change.查看预览通知

owner string path
repo string path
pre_receive_hook_id integer path

pre_receive_hook_id parameter

代码示例

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/repos/octocat/hello-world/pre-receive-hooks/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /repos/{owner}/{repo}/pre-receive-hooks/{pre_receive_hook_id}', {
  owner: 'octocat',
  repo: 'hello-world',
  pre_receive_hook_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Responds with effective values inherited from owner and/or global level.

Status: 200 OK
{
  "id": 42,
  "name": "Check Commits",
  "enforcement": "disabled",
  "configuration_url": "https://github.example.com/api/v3/orgs/octocat/pre-receive-hooks/42"
}

Notes

预览通知

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️此标头必填.

用户

用户管理 API 允许您暂停、取消暂停、升级和降级 企业上的用户。 它只适用于经过身份验证的站点管理员。普通用户尝试访问它时会收到 403 响应。

List public keys

get /admin/keys

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

per_page integer query

Results per page (max 100)

Default: 30
page integer query

Page number of the results to fetch.

Default: 1
direction string query

One of asc (ascending) or desc (descending).

Default: desc
sort string query Default: created
since string query

Only show public keys accessed after the given time.

代码示例

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/keys
JavaScript (@octokit/core.js)
await octokit.request('GET /admin/keys')

Response

Status: 200 OK
[
  {
    "key": "2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234",
    "id": 2,
    "url": "https://api.github.com/user/keys/2",
    "title": "ssh-rsa AAAAB3NzaC1yc2EAAA",
    "created_at": "2020-06-11T21:31:57Z",
    "verified": false,
    "read_only": false,
    "last_used": "2020-06-11T22:31:57Z",
    "user_id": 1,
    "repository_id": 2
  },
  {
    "key": "9Og8iYjAyymI9LvABpJerYrMxURPc8r+dB7TJyvv1234",
    "id": 3,
    "url": "https://api.github.com/user/keys/2",
    "title": "ssh-rsa AAAAB3NzaC1yc2EAAA",
    "created_at": "2020-06-11T21:31:57Z",
    "verified": false,
    "read_only": false,
    "last_used": "2020-06-11T22:31:57Z",
    "user_id": 1,
    "repository_id": 2
  }
]

Delete a public key

delete /admin/keys/{key_ids}

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

key_ids string path

代码示例

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/keys/KEY_IDS
JavaScript (@octokit/core.js)
await octokit.request('DELETE /admin/keys/{key_ids}', {
  key_ids: 'key_ids'
})

Response

Status: 204 No Content

List personal access tokens

Lists personal access tokens for all users, including admin users.

get /admin/tokens

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

per_page integer query

Results per page (max 100)

Default: 30
page integer query

Page number of the results to fetch.

Default: 1

代码示例

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/tokens
JavaScript (@octokit/core.js)
await octokit.request('GET /admin/tokens')

Response

Status: 200 OK
[
  {
    "id": 2,
    "url": "https://enterprise.octocat.com/api/v3/authorizations/2",
    "app": {
      "name": "My personal access token",
      "url": "https://docs.github.com/enterprise/rest/reference/enterprise-admin#list-personal-access-tokens",
      "client_id": "00000000000000000000"
    },
    "token": "ghp_16C7e42F292c6912E7710c838347Ae178B4a",
    "hashed_token": "23cffb2fab1b0a62747863eba88cb9327e561f2f7a0c8661c0d9b83146cb8d45",
    "token_last_eight": "Ae178B4a",
    "note": "My personal access token",
    "note_url": null,
    "created_at": "2019-04-24T21:49:02Z",
    "updated_at": "2019-04-24T21:49:02Z",
    "scopes": [
      "admin:business",
      "admin:gpg_key",
      "admin:org",
      "admin:org_hook",
      "admin:pre_receive_hook",
      "admin:public_key",
      "admin:repo_hook",
      "delete_repo",
      "gist",
      "notifications",
      "repo",
      "user",
      "write:discussion"
    ],
    "fingerprint": null
  }
]

Delete a personal access token

Deletes a personal access token. Returns a 403 - Forbidden status when a personal access token is in use. For example, if you access this endpoint with the same personal access token that you are trying to delete, you will receive this error.

delete /admin/tokens/{token_id}

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

token_id integer path

代码示例

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/tokens/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /admin/tokens/{token_id}', {
  token_id: 42
})

Response

Status: 204 No Content

Create a user

If an external authentication mechanism is used, the login name should match the login name in the external system. If you are using LDAP authentication, you should also update the LDAP mapping for the user.

The login name will be normalized to only contain alphanumeric characters or single hyphens. For example, if you send "octo_cat" as the login, a user named "octo-cat" will be created.

If the login name or email address is already associated with an account, the server will return a 422 response.

post /admin/users

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

login string body

Required. The user's username.

email string body

Required for built-in authentication. The user's email address. This parameter can be omitted when using CAS, LDAP, or SAML. For details on built-in and centrally-managed authentication, see the the GitHub authentication guide.

代码示例

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/users \
  -d '{"login":"login"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/users', {
  login: 'login'
})

Response

Status: 201 Created
{
  "login": "octocat",
  "id": 1,
  "node_id": "MDQ6VXNlcjE=",
  "avatar_url": "https://github.com/images/error/octocat_happy.gif",
  "gravatar_id": "",
  "url": "https://api.github.com/users/octocat",
  "html_url": "https://github.com/octocat",
  "followers_url": "https://api.github.com/users/octocat/followers",
  "following_url": "https://api.github.com/users/octocat/following{/other_user}",
  "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
  "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
  "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
  "organizations_url": "https://api.github.com/users/octocat/orgs",
  "repos_url": "https://api.github.com/users/octocat/repos",
  "events_url": "https://api.github.com/users/octocat/events{/privacy}",
  "received_events_url": "https://api.github.com/users/octocat/received_events",
  "type": "User",
  "site_admin": false
}

Update the username for a user

patch /admin/users/{username}

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

username string path
login string body

Required. The user's new username.

代码示例

Shell
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/users/USERNAME \
  -d '{"login":"login"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /admin/users/{username}', {
  username: 'username',
  login: 'login'
})

Response

Status: 202 Accepted
{
  "message": "Job queued to rename user. It may take a few minutes to complete.",
  "url": "https://api.github.com/user/1"
}

Delete a user

Deleting a user will delete all their repositories, gists, applications, and personal settings. Suspending a user is often a better option.

You can delete any user account except your own.

delete /admin/users/{username}

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

username string path

代码示例

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/users/USERNAME
JavaScript (@octokit/core.js)
await octokit.request('DELETE /admin/users/{username}', {
  username: 'username'
})

Response

Status: 204 No Content

Create an impersonation OAuth token

post /admin/users/{username}/authorizations

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

username string path
scopes array of strings body

A list of scopes.

代码示例

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/users/USERNAME/authorizations \
  -d '{"scopes":["scopes"]}'
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/users/{username}/authorizations', {
  username: 'username',
  scopes: [
    'scopes'
  ]
})

Response

Status: 201 Created
{
  "id": 1,
  "url": "https://api.github.com/authorizations/1",
  "scopes": [
    "public_repo"
  ],
  "token": "ghu_16C7e42F292c6912E7710c838347Ae178B4a",
  "token_last_eight": "Ae178B4a",
  "hashed_token": "25f94a2a5c7fbaf499c665bc73d67c1c87e496da8985131633ee0a95819db2e8",
  "app": {
    "url": "http://my-github-app.com",
    "name": "my github app",
    "client_id": "abcde12345fghij67890"
  },
  "note": "optional note",
  "note_url": "http://optional/note/url",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z",
  "fingerprint": "jklmnop12345678"
}

Delete an impersonation OAuth token

delete /admin/users/{username}/authorizations

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

username string path

代码示例

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/users/USERNAME/authorizations
JavaScript (@octokit/core.js)
await octokit.request('DELETE /admin/users/{username}/authorizations', {
  username: 'username'
})

Response

Status: 204 No Content

Promote a user to be a site administrator

Note that you'll need to set Content-Length to zero when calling out to this endpoint. For more information, see "HTTP verbs."

put /users/{username}/site_admin

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

username string path

代码示例

Shell
curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/users/USERNAME/site_admin
JavaScript (@octokit/core.js)
await octokit.request('PUT /users/{username}/site_admin', {
  username: 'username'
})

Response

Status: 204 No Content

Demote a site administrator

You can demote any user account except your own.

delete /users/{username}/site_admin

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

username string path

代码示例

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/users/USERNAME/site_admin
JavaScript (@octokit/core.js)
await octokit.request('DELETE /users/{username}/site_admin', {
  username: 'username'
})

Response

Status: 204 No Content

Suspend a user

If your GitHub instance uses LDAP Sync with Active Directory LDAP servers, Active Directory LDAP-authenticated users cannot be suspended through this API. If you attempt to suspend an Active Directory LDAP-authenticated user through this API, it will return a 403 response.

You can suspend any user account except your own.

Note that, if you choose not to pass any parameters, you'll need to set Content-Length to zero when calling out to this endpoint. For more information, see "HTTP verbs."

put /users/{username}/suspended

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

username string path
reason string body

The reason the user is being suspended. This message will be logged in the audit log. If you don't provide a reason, it will default to "Suspended via API by SITE_ADMINISTRATOR", where SITE_ADMINISTRATOR is the person who performed the action.

代码示例

Shell
curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/users/USERNAME/suspended \
  -d '{"reason":"reason"}'
JavaScript (@octokit/core.js)
await octokit.request('PUT /users/{username}/suspended', {
  username: 'username',
  reason: 'reason'
})

Response

Status: 204 No Content

Unsuspend a user

If your GitHub instance uses LDAP Sync with Active Directory LDAP servers, this API is disabled and will return a 403 response. Active Directory LDAP-authenticated users cannot be unsuspended using the API.

delete /users/{username}/suspended

参数

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

username string path
reason string body

The reason the user is being unsuspended. This message will be logged in the audit log. If you don't provide a reason, it will default to "Unsuspended via API by SITE_ADMINISTRATOR", where SITE_ADMINISTRATOR is the person who performed the action.

代码示例

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/users/USERNAME/suspended \
  -d '{"reason":"reason"}'
JavaScript (@octokit/core.js)
await octokit.request('DELETE /users/{username}/suspended', {
  username: 'username',
  reason: 'reason'
})

Response

Status: 204 No Content