Managing custom properties for repositories in your organization

With custom properties, you can add metadata to repositories in your organization. You can use those properties to target repositories with rulesets.

Who can use this feature?

Organization owners and users with the "Manage the organization's custom properties definitions" permission can add and set a custom property schema at the organization level.

In this article

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.

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."

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."

  1. In the upper-right corner of GitHub, select your profile photo, then click Your organizations.

  2. Next to the organization, click Settings.

  3. In the left sidebar, in the "Code, planning, and automation" section, click Repository, then click Custom properties.

    Screenshot of an organization's settings page. In the sidebar, a link labeled "Custom properties" is outlined in orange.

  4. To add a new custom property, click New property in the upper right corner.

  5. In the "Name" field, type the name you'd like to use for your custom property. The name can't contain spaces.

  6. Optionally, in the "Description" field, fill in a description of your custom property.

  7. 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.

  8. 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.

  9. 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.

  10. 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.

  1. In the upper-right corner of GitHub, select your profile photo, then click Your organizations.

  2. Next to the organization, click Settings.

  3. In the left sidebar, in the "Code, planning, and automation" section, click Repository, then click Custom properties.

    Screenshot of an organization's settings page. In the sidebar, a link labeled "Custom properties" is outlined in orange.

  4. Click the "Set values" tab.

  5. Select one or more repositories from the list and click Edit properties.

    Screenshot the page to set values for repositories. A button, labeled with a pencil icon and "Edit properties", is highlighted with an orange outline.

  6. In the modal dialog that appears, select a value for each property you'd like to set for the selected repositories.

  7. 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."

  1. On GitHub, navigate to the main page of the repository.

  2. Under your repository name, click Settings. If you cannot see the "Settings" tab, select the dropdown menu, then click Settings.

    Screenshot of a repository header showing the tabs. The "Settings" tab is highlighted by a dark orange outline.

  3. 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.

  1. In the upper-right corner of GitHub, select your profile photo, then click Your organizations.
  2. Click the name of your organization.
  3. Under your organization name, click Repositories.
  4. 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.