Skip to content
forgit api docs

Create or update custom properties for an organization

PATCH
/orgs/{org}/properties/schema

Creates new or updates existing custom properties defined for an organization 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. E.g. if a property exists with values_editable_by: org_and_repo_actors and it’s updated without specifying values_editable_by, it will be updated to default value org_actors.

To use this endpoint, the authenticated user must be one of:

  • An administrator for the organization.
  • A user, or a user on a team, with the fine-grained permission of custom_properties_org_definitions_manager in the organization.

API method documentation

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
org
required
string

The organization name. The name is not case sensitive.

Request Body required

Section titled “ Request Body required ”
Media type application/json
object
properties
required

The array of custom properties to create or update.

Array<object>
>= 1 items <= 100 items
Organization Custom Property

Custom property defined on an organization

object
property_name
required

The name of the property

string
url

The URL that can be used to fetch, update, or delete info about this property via the API.

string format: uri
source_type

The source type of the property

string
Allowed values: organization enterprise
value_type
required

The type of the value for the property

string
Allowed values: string single_select multi_select true_false url
required

Whether the property is required.

boolean
default_value
One of:
string
description

Short description of the property

string
nullable
allowed_values

An ordered list of the allowed values of the property. The property can have up to 200 allowed values.

Array<string>
nullable
values_editable_by

Who can edit the values of the property

string
nullable
Allowed values: org_actors org_and_repo_actors
require_explicit_values

Whether setting properties values is mandatory

boolean
Examples
Example default 
{
  "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"
    }
  ]
}

Responses

Section titled “ Responses ”

200

Section titled “ 200 ”

Response

Media type application/json
Array<object>
Organization Custom Property

Custom property defined on an organization

object
property_name
required

The name of the property

string
url

The URL that can be used to fetch, update, or delete info about this property via the API.

string format: uri
source_type

The source type of the property

string
Allowed values: organization enterprise
value_type
required

The type of the value for the property

string
Allowed values: string single_select multi_select true_false url
required

Whether the property is required.

boolean
default_value
One of:
string
description

Short description of the property

string
nullable
allowed_values

An ordered list of the allowed values of the property. The property can have up to 200 allowed values.

Array<string>
nullable
values_editable_by

Who can edit the values of the property

string
nullable
Allowed values: org_actors org_and_repo_actors
require_explicit_values

Whether setting properties values is mandatory

boolean
Examples
Example default 
[
  {
    "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",
    "require_explicit_values": true
  },
  {
    "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"
  }
]

403

Section titled “ 403 ”

Forbidden

Media type application/json
Basic Error

Basic Error

object
message
string
documentation_url
string
url
string
status
string
Example generated 
{
  "message": "example",
  "documentation_url": "example",
  "url": "example",
  "status": "example"
}

404

Section titled “ 404 ”

Resource not found

Media type application/json
Basic Error

Basic Error

object
message
string
documentation_url
string
url
string
status
string
Example generated 
{
  "message": "example",
  "documentation_url": "example",
  "url": "example",
  "status": "example"
}