About custom properties
Custom properties allow you to decorate your repositories with information such as compliance frameworks, data sensitivity, or project details. Custom properties are private and can only be viewed by people with read permissions to the repository.
An organization can have up to 100 property definitions. An allowed value list can have up to 200 items.
You can use repository properties to determine which repositories to target with a ruleset. For more information, see "Creating rulesets for repositories in your organization."
You can define custom properties at the enterprise level to create a consistent experience across organizations. See "Managing custom properties for repositories in your enterprise".
Allowed characters
Custom property names and values may only contain certain characters:
- Names:
a-z
,A-Z
,0-9
,_
,-
,$
,#
. - Values: All printable ASCII characters except
"
.
Adding custom properties
You can add custom properties to your organization and set values for those properties for repositories in your organization.
You can also use the REST API to create and manage custom properties for an organization. For more information, see "REST API endpoints for custom properties."
-
In the upper-right corner of GitHub, select your profile photo, then click Your organizations.
-
Next to the organization, click Settings.
-
In the left sidebar, in the "Code, planning, and automation" section, click Repository, then click Custom properties.
-
To add a new custom property, click New property in the upper right corner.
-
In the "Name" field, type the name you'd like to use for your custom property. The name can't contain spaces.
-
Optionally, in the "Description" field, fill in a description of your custom property.
-
Under "Type", select the type of property you'd like to add. This can either be a text string, a single select field, a multi select field, or a true/false boolean.
-
Optionally, you can select Allow repository actors to set this property. When enabled, repository users and apps with the repository-level "custom properties" fine-grained permission will be able to set and update the property value for their repository.
-
Optionally, you can select Require this property for all repositories and add a default value. This means that you require that all repositories in your organization have a value for this property. Repositories that don’t have an explicit value for this property will inherit the default value.
-
Click Save property.
Setting values for repositories in your organization
You, and any users with the "Edit custom properties values at the organization level" permission, can set values for custom properties for repositories in your organization.
-
In the upper-right corner of GitHub, select your profile photo, then click Your organizations.
-
Next to the organization, click Settings.
-
In the left sidebar, in the "Code, planning, and automation" section, click Repository, then click Custom properties.
-
Click the "Set values" tab.
-
Select one or more repositories from the list and click Edit properties.
-
In the modal dialog that appears, select a value for each property you'd like to set for the selected repositories.
-
Click Save changes.
Viewing values for repositories in your organization
People with read permissions to a repository can view the values of custom properties for that repository, but they can't edit those values.
You can also use the REST API to list the custom properties assigned to a repository by your organization. For more information, see "REST API endpoints for custom properties."
-
On GitHub, navigate to the main page of the repository.
-
Under your repository name, click Settings. If you cannot see the "Settings" tab, select the dropdown menu, then click Settings.
-
In the "Code and automation" section of the sidebar, click Custom properties.
Searching and filtering repositories by custom properties values
You can search for repositories in your organization by custom properties values.
- In the upper-right corner of GitHub, select your profile photo, then click Your organizations.
- Click the name of your organization.
- Under your organization name, click Repositories.
- In the search bar, type
prop
to see a list of all custom properties in your organization, and select the property you'd like to search by.