REST API for organization custom properties in an enterprise

Get organization custom properties schema for an enterprise

Gets all organization custom property definitions that are defined on an enterprise.

Access requirements:

Enterprise admins
OAuth tokens and personal access tokens (classic) with the read:enterprise scope
Actors with the enterprise-level "read enterprise custom properties for organizations" fine-grained permission or above

“Get organization custom properties schema for an enterprise”的细粒度访问令牌

此端点支持以下精细令牌类型:

精细令牌必须具有以下权限集:

"Enterprise custom properties for organizations" enterprise permissions (read)

“Get organization custom properties schema for an enterprise”的参数

标头
名称, 类型, 说明
`accept` string Setting to `application/vnd.github+json` is recommended.

路径参数
名称, 类型, 说明
`enterprise` string 必须 The slug version of the enterprise name.

“Get organization custom properties schema for an enterprise”的 HTTP 响应状态代码

状态代码	说明
`200`	OK
`403`	Forbidden
`404`	Resource not found

“Get organization custom properties schema for an enterprise”的示例代码

如果你通过 GHE.com 访问 GitHub，请将 api.github.com 替换为你的企业在 api.SUBDOMAIN.ghe.com 上的专用子域。

请求示例

get/enterprises/{enterprise}/org-properties/schema

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/enterprises/ENTERPRISE/org-properties/schema

Response

Status: 200

{
  "properties": [
    {
      "property_name": "environment",
      "url": "https://api.github.com/enterprises/github/org-properties/schema/environment",
      "source_type": "enterprise",
      "value_type": "single_select",
      "required": true,
      "default_value": "production",
      "description": "Prod or dev environment",
      "allowed_values": [
        "production",
        "development"
      ],
      "values_editable_by": "enterprise_actors"
    },
    {
      "property_name": "service",
      "url": "https://api.github.com/enterprises/github/org-properties/schema/service",
      "source_type": "enterprise",
      "value_type": "string"
    },
    {
      "property_name": "team",
      "url": "https://api.github.com/enterprises/github/org-properties/schema/team",
      "source_type": "enterprise",
      "value_type": "string",
      "description": "Team owning the organization"
    }
  ]
}

Create or update organization custom property definitions on an enterprise

Creates new or updates existing organization custom properties defined on an enterprise in a batch.

If the property already exists, the existing property will be replaced with the new values. Missing optional values will fall back to default values, previous values will be overwritten.

Access requirements:

Enterprise admins
OAuth tokens and personal access tokens (classic) with the admin:enterprise scope
Actors with the enterprise-level "manage enterprise custom properties for organizations" fine-grained permission

“Create or update organization custom property definitions on an enterprise”的细粒度访问令牌

此端点支持以下精细令牌类型:

精细令牌必须具有以下权限集:

"Enterprise custom properties for organizations" enterprise permissions (admin)

“Create or update organization custom property definitions on an enterprise”的参数

标头
名称, 类型, 说明
`accept` string Setting to `application/vnd.github+json` is recommended.

路径参数
名称, 类型, 说明
`enterprise` string 必须 The slug version of the enterprise name.

名称, 类型, 说明

properties array of objects 必须

The array of organization custom properties to create or update.

Properties of properties

名称, 类型, 说明
`property_name` string 必须 The name of the property
`url` string The URL that can be used to fetch, update, or delete info about this property via the API.
`source_type` string The source type of the property 可以是以下选项之一: `organization`, `enterprise`
`value_type` string 必须 The type of the value for the property 可以是以下选项之一: `string`, `single_select`, `multi_select`, `true_false`
`required` boolean Whether the property is required.
`default_value` null or string or array Default value of the property
`description` string or null Short description of the property
`allowed_values` array of strings or null An ordered list of the allowed values of the property. The property can have up to 200 allowed values.
`values_editable_by` string or null Who can edit the values of the property 可以是以下选项之一: `enterprise_actors`, `enterprise_and_org_actors`, `null`

“Create or update organization custom property definitions on an enterprise”的 HTTP 响应状态代码

状态代码	说明
`200`	OK
`403`	Forbidden
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.

“Create or update organization custom property definitions on an enterprise”的示例代码

如果你通过 GHE.com 访问 GitHub，请将 api.github.com 替换为你的企业在 api.SUBDOMAIN.ghe.com 上的专用子域。

请求示例

patch/enterprises/{enterprise}/org-properties/schema

curl -L \
  -X PATCH \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/enterprises/ENTERPRISE/org-properties/schema \
  -d '{"properties":[{"property_name":"environment","url":"https://api.github.com/enterprises/github/org-properties/schema/environment","source_type":"enterprise","value_type":"single_select","required":true,"default_value":"production","description":"Prod or dev environment","allowed_values":["production","development"],"values_editable_by":"enterprise_actors"},{"property_name":"service","url":"https://api.github.com/enterprises/github/org-properties/schema/service","source_type":"enterprise","value_type":"string"},{"property_name":"team","url":"https://api.github.com/enterprises/github/org-properties/schema/team","source_type":"enterprise","value_type":"string","description":"Team owning the organization"}]}'

Response

Status: 200

{
  "properties": [
    {
      "property_name": "environment",
      "url": "https://api.github.com/enterprises/github/org-properties/schema/environment",
      "source_type": "enterprise",
      "value_type": "single_select",
      "required": true,
      "default_value": "production",
      "description": "Prod or dev environment",
      "allowed_values": [
        "production",
        "development"
      ],
      "values_editable_by": "enterprise_actors"
    },
    {
      "property_name": "service",
      "url": "https://api.github.com/enterprises/github/org-properties/schema/service",
      "source_type": "enterprise",
      "value_type": "string"
    },
    {
      "property_name": "team",
      "url": "https://api.github.com/enterprises/github/org-properties/schema/team",
      "source_type": "enterprise",
      "value_type": "string",
      "description": "Team owning the organization"
    }
  ]
}

Get an organization custom property definition from an enterprise

Gets an organization custom property definition that is defined on an enterprise.

Access requirements:

Enterprise admins
OAuth tokens and personal access tokens (classic) with the read:enterprise scope
Actors with the enterprise-level "read enterprise custom properties for organizations" fine-grained permission or above

“Get an organization custom property definition from an enterprise”的细粒度访问令牌

此端点支持以下精细令牌类型:

精细令牌必须具有以下权限集:

"Enterprise custom properties for organizations" enterprise permissions (read)

“Get an organization custom property definition from an enterprise”的参数

标头
名称, 类型, 说明
`accept` string Setting to `application/vnd.github+json` is recommended.

路径参数
名称, 类型, 说明
`enterprise` string 必须 The slug version of the enterprise name.
`custom_property_name` string 必须 The custom property name

“Get an organization custom property definition from an enterprise”的 HTTP 响应状态代码

状态代码	说明
`200`	OK
`403`	Forbidden
`404`	Resource not found

“Get an organization custom property definition from an enterprise”的示例代码

如果你通过 GHE.com 访问 GitHub，请将 api.github.com 替换为你的企业在 api.SUBDOMAIN.ghe.com 上的专用子域。

请求示例

get/enterprises/{enterprise}/org-properties/schema/{custom_property_name}

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/enterprises/ENTERPRISE/org-properties/schema/CUSTOM_PROPERTY_NAME

Response

Status: 200

{
  "property_name": "environment",
  "url": "https://api.github.com/enterprises/github/org-properties/schema/environment",
  "source_type": "enterprise",
  "value_type": "single_select",
  "required": true,
  "default_value": "production",
  "description": "Prod or dev environment",
  "allowed_values": [
    "production",
    "development"
  ],
  "values_editable_by": "enterprise_actors"
}

Create or update an organization custom property definition on an enterprise

Creates a new or updates an existing organization custom property definition that is defined on an enterprise.

Access requirements:

Enterprise admins
OAuth tokens and personal access tokens (classic) with the admin:enterprise scope
Actors with the enterprise-level "manage enterprise custom properties for organizations" fine-grained permission

“Create or update an organization custom property definition on an enterprise”的细粒度访问令牌

此端点支持以下精细令牌类型:

精细令牌必须具有以下权限集:

"Enterprise custom properties for organizations" enterprise permissions (admin)

“Create or update an organization custom property definition on an enterprise”的参数

标头
名称, 类型, 说明
`accept` string Setting to `application/vnd.github+json` is recommended.

路径参数
名称, 类型, 说明
`enterprise` string 必须 The slug version of the enterprise name.
`custom_property_name` string 必须 The custom property name

正文参数
名称, 类型, 说明
`value_type` string 必须 The type of the value for the property. 可以是以下选项之一: `string`, `single_select`, `multi_select`, `true_false`
`required` boolean Whether the property is required.
`default_value` null or string or array Default value of the property.
`description` string or null Short description of the property.
`allowed_values` array of strings or null An ordered list of the allowed values of the property. The property can have up to 200 allowed values.
`values_editable_by` string or null Who can edit the values of the property. 可以是以下选项之一: `enterprise_actors`, `enterprise_and_org_actors`, `null`

“Create or update an organization custom property definition on an enterprise”的 HTTP 响应状态代码

状态代码	说明
`200`	OK
`403`	Forbidden
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.

“Create or update an organization custom property definition on an enterprise”的示例代码

如果你通过 GHE.com 访问 GitHub，请将 api.github.com 替换为你的企业在 api.SUBDOMAIN.ghe.com 上的专用子域。

请求示例

put/enterprises/{enterprise}/org-properties/schema/{custom_property_name}

curl -L \
  -X PUT \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/enterprises/ENTERPRISE/org-properties/schema/CUSTOM_PROPERTY_NAME \
  -d '{"value_type":"single_select","required":true,"default_value":"production","description":"Prod or dev environment","allowed_values":["production","development"]}'

Response

Status: 200

{
  "property_name": "environment",
  "url": "https://api.github.com/enterprises/github/org-properties/schema/environment",
  "source_type": "enterprise",
  "value_type": "single_select",
  "required": true,
  "default_value": "production",
  "description": "Prod or dev environment",
  "allowed_values": [
    "production",
    "development"
  ],
  "values_editable_by": "enterprise_actors"
}

Remove an organization custom property definition from an enterprise

Removes an organization custom property definition that is defined on an enterprise.

Access requirements:

Enterprise admins
OAuth tokens and personal access tokens (classic) with the admin:enterprise scope
Actors with the enterprise-level "manage enterprise custom properties for organizations" fine-grained permission

“Remove an organization custom property definition from an enterprise”的细粒度访问令牌

此端点支持以下精细令牌类型:

精细令牌必须具有以下权限集:

"Enterprise custom properties for organizations" enterprise permissions (admin)

“Remove an organization custom property definition from an enterprise”的参数

标头
名称, 类型, 说明
`accept` string Setting to `application/vnd.github+json` is recommended.

路径参数
名称, 类型, 说明
`enterprise` string 必须 The slug version of the enterprise name.
`custom_property_name` string 必须 The custom property name

“Remove an organization custom property definition from an enterprise”的 HTTP 响应状态代码

状态代码	说明
`204`	A header with no content is returned.
`403`	Forbidden
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.

“Remove an organization custom property definition from an enterprise”的示例代码

如果你通过 GHE.com 访问 GitHub，请将 api.github.com 替换为你的企业在 api.SUBDOMAIN.ghe.com 上的专用子域。

请求示例

delete/enterprises/{enterprise}/org-properties/schema/{custom_property_name}

curl -L \
  -X DELETE \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/enterprises/ENTERPRISE/org-properties/schema/CUSTOM_PROPERTY_NAME

A header with no content is returned.

Status: 204

List custom property values for organizations in an enterprise

Lists enterprise organizations with all of their custom property values.

Access requirements:

Enterprise admins
OAuth tokens and personal access tokens (classic) with the read:enterprise scope
Actors with the enterprise-level "read enterprise custom properties for organizations" fine-grained permission or above

“List custom property values for organizations in an enterprise”的细粒度访问令牌

此端点支持以下精细令牌类型:

精细令牌必须具有以下权限集:

"Enterprise custom properties for organizations" enterprise permissions (read)

“List custom property values for organizations in an enterprise”的参数

标头
名称, 类型, 说明
`accept` string Setting to `application/vnd.github+json` is recommended.

路径参数
名称, 类型, 说明
`enterprise` string 必须 The slug version of the enterprise name.

查询参数
名称, 类型, 说明
`per_page` integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." 默认: `30`
`page` integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." 默认: `1`

“List custom property values for organizations in an enterprise”的 HTTP 响应状态代码

状态代码	说明
`200`	OK
`403`	Forbidden
`404`	Resource not found

“List custom property values for organizations in an enterprise”的示例代码

如果你通过 GHE.com 访问 GitHub，请将 api.github.com 替换为你的企业在 api.SUBDOMAIN.ghe.com 上的专用子域。

请求示例

get/enterprises/{enterprise}/org-properties/values

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/enterprises/ENTERPRISE/org-properties/values

Response

Status: 200

[
  {
    "organization_id": 1296269,
    "organization_login": "Hello-World",
    "properties": [
      {
        "property_name": "environment",
        "value": "production"
      },
      {
        "property_name": "service",
        "value": "web"
      },
      {
        "property_name": "team",
        "value": "octocat"
      }
    ]
  }
]

Create or update custom property values for organizations in an enterprise

Create or update custom property values for organizations in an enterprise.

To remove a custom property value from an organization, set the property value to null.

Access requirements:

Enterprise admins
OAuth tokens and personal access tokens (classic) with the admin:enterprise scope
Actors with the enterprise-level "edit enterprise custom properties for organizations" fine-grained permission or above

“Create or update custom property values for organizations in an enterprise”的细粒度访问令牌

此端点支持以下精细令牌类型:

精细令牌必须具有以下权限集:

"Enterprise custom properties for organizations" enterprise permissions (write)

“Create or update custom property values for organizations in an enterprise”的参数

标头
名称, 类型, 说明
`accept` string Setting to `application/vnd.github+json` is recommended.

路径参数
名称, 类型, 说明
`enterprise` string 必须 The slug version of the enterprise name.

名称, 类型, 说明

organization_logins array of strings 必须

The names of organizations that the custom property values will be applied to.

properties array of objects 必须

List of custom property names and associated values to apply to the organizations.

Properties of properties

名称, 类型, 说明
`property_name` string 必须 The name of the property
`value` null or string or array 必须 The value assigned to the property

“Create or update custom property values for organizations in an enterprise”的 HTTP 响应状态代码

状态代码	说明
`204`	No Content when custom property values are successfully created or updated
`403`	Forbidden
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.

“Create or update custom property values for organizations in an enterprise”的示例代码

如果你通过 GHE.com 访问 GitHub，请将 api.github.com 替换为你的企业在 api.SUBDOMAIN.ghe.com 上的专用子域。

请求示例

patch/enterprises/{enterprise}/org-properties/values

curl -L \
  -X PATCH \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/enterprises/ENTERPRISE/org-properties/values \
  -d '{"organization_logins":["acme","github"],"properties":[{"property_name":"environment","value":"production"},{"property_name":"service","value":"web"},{"property_name":"team","value":"octocat"}]}'

No Content when custom property values are successfully created or updated

Status: 204