Custom properties

Get custom properties for an enterprise

Note

This endpoint is in public preview and is subject to change.

Gets all custom properties defined for an enterprise. Enterprise members can read these properties.

Fine-grained access tokens for "Get custom properties for an enterprise"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Custom properties" business permissions (read)

Parameters for "Get custom properties for an enterprise"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name. You can also substitute this value with the enterprise id.

HTTP response status codes for "Get custom properties for an enterprise"

Status code	Description
`200`	OK
`403`	Forbidden
`404`	Resource not found

Code samples for "Get custom properties for an enterprise"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/enterprises/{enterprise}/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/properties/schema

Response

Status: 200

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

Create or update custom properties for an enterprise

Note

This endpoint is in public preview and is subject to change.

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

To use this endpoint, the authenticated user must be an administrator for the enterprise.

Fine-grained access tokens for "Create or update custom properties for an enterprise"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Custom properties" business permissions (write)

Parameters for "Create or update custom properties for an enterprise"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name. You can also substitute this value with the enterprise id.

Name, Type, Description

properties array of objects Required

The array of custom properties to create or update.

Properties of properties

Name, Type, Description
`property_name` string Required 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 Can be one of: `organization`, `enterprise`
`value_type` string Required The type of the value for the property Can be one of: `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 Can be one of: `org_actors`, `org_and_repo_actors`, `null`

HTTP response status codes for "Create or update custom properties for an enterprise"

Status code	Description
`200`	OK
`403`	Forbidden
`404`	Resource not found

Code samples for "Create or update custom properties for an enterprise"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

patch/enterprises/{enterprise}/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/properties/schema \
  -d '{"properties":[{"property_name":"environment","value_type":"single_select","required":true,"default_value":"production","description":"Prod or dev environment","allowed_values":["production","development"],"values_editable_by":"org_actors"},{"property_name":"service","value_type":"string"},{"property_name":"team","value_type":"string","description":"Team owning the repository"}]}'

Response

Status: 200

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

Get a custom property for an enterprise

Note

This endpoint is in public preview and is subject to change.

Gets a custom property that is defined for an enterprise. Enterprise members can read these properties.

Fine-grained access tokens for "Get a custom property for an enterprise"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Custom properties" business permissions (read)

Parameters for "Get a custom property for an enterprise"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name. You can also substitute this value with the enterprise id.
`custom_property_name` string Required The custom property name

HTTP response status codes for "Get a custom property for an enterprise"

Status code	Description
`200`	OK
`403`	Forbidden
`404`	Resource not found

Code samples for "Get a custom property for an enterprise"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/enterprises/{enterprise}/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/properties/schema/CUSTOM_PROPERTY_NAME

Response

Status: 200

{
  "property_name": "environment",
  "url": "https://api.github.com/orgs/github/properties/schema/environment",
  "source_type": "organization",
  "value_type": "single_select",
  "required": true,
  "default_value": "production",
  "description": "Prod or dev environment",
  "allowed_values": [
    "production",
    "development"
  ]
}

Create or update a custom property for an enterprise

Note

This endpoint is in public preview and is subject to change.

Creates a new or updates an existing custom property that is defined for an enterprise.

To use this endpoint, the authenticated user must be an administrator for the enterprise.

Fine-grained access tokens for "Create or update a custom property for an enterprise"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Custom properties" business permissions (write)

Parameters for "Create or update a custom property for an enterprise"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name. You can also substitute this value with the enterprise id.
`custom_property_name` string Required The custom property name

Body parameters
Name, Type, Description
`value_type` string Required The type of the value for the property Can be one of: `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.

HTTP response status codes for "Create or update a custom property for an enterprise"

Status code	Description
`200`	OK
`403`	Forbidden
`404`	Resource not found

Code samples for "Create or update a custom property for an enterprise"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

put/enterprises/{enterprise}/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/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/orgs/github/properties/schema/environment",
  "source_type": "organization",
  "value_type": "single_select",
  "required": true,
  "default_value": "production",
  "description": "Prod or dev environment",
  "allowed_values": [
    "production",
    "development"
  ]
}

Remove a custom property for an enterprise

Note

This endpoint is in public preview and is subject to change.

Remove a custom property that is defined for an enterprise.

To use this endpoint, the authenticated user must be an administrator for the enterprise.

Fine-grained access tokens for "Remove a custom property for an enterprise"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Custom properties" business permissions (write)

Parameters for "Remove a custom property for an enterprise"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name. You can also substitute this value with the enterprise id.
`custom_property_name` string Required The custom property name

HTTP response status codes for "Remove a custom property for an enterprise"

Status code	Description
`204`	A header with no content is returned.
`403`	Forbidden
`404`	Resource not found

Code samples for "Remove a custom property for an enterprise"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

delete/enterprises/{enterprise}/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/properties/schema/CUSTOM_PROPERTY_NAME

A header with no content is returned.

Status: 204