Managing custom organization roles

About custom organization roles

You can have more granular control over the access you grant to your organization and repository's settings by creating custom organization roles. Organization roles are a way to grant an organization member the ability to administer certain subsets of settings without granting full administrative control of the organization and its repositories. For example, you could create a role that contains the "View organization audit log" permission. For more information, see "About custom organization roles."

If you are an organization owner or have a custom role with the "View organization roles" or "Manage custom organization roles" permissions, you can view custom roles for the organization. To find the "Custom roles" page, you can follow the first steps in "Creating a custom role." The exact steps will vary depending on which other settings page you have access to.

To view organization role permissions and manage organization role assignments, see "Using organization roles"

Creating a custom role

Organization owners and users with the "Manage custom organization roles" permission can create up to 10 custom organization roles.

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 "Access" section of the sidebar, click Organization roles, then click Role management.

4. Click Create a role.

5. Type a name and description for the custom role.

6. Under "Add permissions", click the Organization or Repository tab to select the type of permissions you want to add to the custom role.

   • To add permissions for the organization, click the Organization tab, then select the dropdown menu and click the permissions you want your custom role to include.

   • To choose a base repository role to inherit, click the Repository tab, then select the dropdown menu and click the base role you want to include in the custom role. For more information about the available base repository roles, see "Base roles for repository access."

     Once you've selected a base repository role, you can add additional permissions to the custom role. For more information about the available permissions, see "Additional permissions for repository access."

     Note

     Adding a repository role and permissions to a custom organization role is currently in public preview and subject to change.

7. Click Create role.

Editing a custom role

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 "Access" section of the sidebar, click Organization roles, then click Role management.
4. Next to the role you want to edit, select , then click Edit role.
5. Change the role as required, then click Update role.

Deleting a custom role

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 "Access" section of the sidebar, click Organization roles, then click Role management.
4. Next to the role you want to edit, select , then click Delete role.
5. Read the details in the dialog to confirm you want to delete the role, then click Delete role.