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.
You can create and assign custom organization roles in your organization's settings. You can also manage custom roles using the REST API. See "Managing custom organization roles."
You can also create a custom organization role that includes permissions for repositories. Repository permissions grant access to all current and future repositories in the organization.
There are several ways to combine permissions for repositories and organizations.
- You can create a role that includes permissions for organization settings, a base role for repository access, or both.
- If you add a base role for repository access, you can also include additional repository permissions. You can't add repository permissions without a base repository role.
Without repository permissions or a base repository role, the organization role doesn't grant access to any repositories.
Note
Adding repository permissions to a custom organization role is currently in beta and subject to change.
To grant access to specific repositories in your organization, you can create a custom repository role. See "About custom repository roles."
Permissions for organization access
When you include a permission in a custom organization role, any users with that role will have access to the corresponding settings via both the web browser and API. In the organization's settings in the browser, users will see only the pages for settings they can access.
Organization permissions do not grant read, write, or administrator access to any repositories. Some permissions may implicitly grant visibility of repository metadata, as marked in the table below.
| Permission | Description | More information |
|---|---|---|
| Manage custom organization roles | Access to create, view, update, and delete custom organization roles within the organization. This permission does not allow a user to assign custom roles. | "Managing custom organization roles" |
| View organization roles | Access to view the organization's custom organization roles. | "Managing custom organization roles" |
| Manage custom repository roles | Access to create, view, update, and delete the organization's custom repository roles. | "Managing custom repository roles for an organization" |
| View custom repository roles | Access to view the organization's custom repository roles. | "Managing custom repository roles for an organization" |
| Manage organization webhooks | Access to register and manage webhooks for the organization. Users with this permission will be able to view webhook payloads, which may contain metadata for repositories in the organization. | "REST API endpoints for organization webhooks" |
| Edit custom properties values at the organization level | Access to set custom property values on all repositories in the organization. | "Managing custom properties for repositories in your organization" |
| Manage the organization's custom properties definitions | Access to create and edit custom property definitions for the organization. | "Managing custom properties for repositories in your organization" |
| Manage organization ref update rules and rulesets | Access to manage rulesets and view ruleset insights at the organization level. | "Managing rulesets for repositories in your organization" |
| View organization audit log | Access to the audit log for the organization. The audit log may contain metadata for repositories in the organization. | "Reviewing the audit log for your organization" |
| Manage organization Actions policies | Access to manage all settings on the "Actions General" settings page, except for self-hosted runners settings. | "Disabling or limiting GitHub Actions for your organization" |
| Manage organization runners and runner groups | Access to create and manage GitHub-hosted runners, self-hosted runners, and runner groups, and control where self-hosted runners can be created. | "About GitHub-hosted runners" "About self-hosted runners" |
| Manage organization Actions secrets | Access to create and manage Actions organization secrets. | "Using secrets in GitHub Actions" |
| Manage organization Actions variables | Access to create and manage Actions organization variables. | "Store information in variables" |
Base roles for repository access
The base repository role determines the initial set of permissions included in the custom role. Repository access is granted across all current and future repositories in the organization.
The base repository roles are:
- Read: Grants read access to all repositories in the organization.
- Write: Grants write access to all repositories in the organization.
- Triage: Grants triage access to all repositories in the organization.
- Maintain: Grants maintenance access to all repositories in the organization.
- Admin: Grants admin access to all repositories in the organization.
Additional permissions for repository access
After choosing a base repository role, you can select additional permissions for your custom organization role.
You can only choose an additional permission if it's not already included in the base repository role. For example, if the base role offers Write access to a repository, then the "Close a pull request" permission will already be included in the base role.
Discussions
- Create a discussion category
- Edit a discussion category
- Delete a discussion category
- Mark or unmark discussion answers
- Hide or unhide discussion comments
- Convert issues to discussions
For more information, see "GitHub Discussions documentation."
Issue and Pull Requests
- Assign or remove a user
- Add or remove a label
Issue
- Close an issue
- Reopen a closed issue
- Delete an issue
- Mark an issue as a duplicate
Pull Request
- Close a pull request
- Reopen a closed pull request
- Request a pull request review
Repository
- Set milestones
- Manage wiki settings
- Manage project settings
- Manage pull request merging settings
- Manage GitHub Pages settings (see "Configuring a publishing source for your GitHub Pages site")
- Manage webhooks
- Manage deploy keys
- Edit repository metadata
- Set the social preview
- Push commits to protected branches
- Base role must be
write - Branch protection rules will still apply
- Base role must be
- Create protected tags
- Delete protected tags
- Bypass branch protections
- Edit repository rules
Security
- View code scanning results
- Dismiss or reopen code scanning results
- Delete code scanning results
- View Dependabot alerts
- Dismiss or reopen Dependabot alerts
- View secret scanning results
- Dismiss or reopen secret scanning results
Precedence for different levels of access
Roles and permissions are additive. If a person is given different levels of access through different avenues, such as team membership and the base permissions for an organization, the user has the sum of all access grants. For example, if an organization owner gives an organization member a custom role that uses the "Read" inherited role, and then an organization owner sets the organization's base permission to "Write", then members with the custom role will have write access, along with any additional permissions included in the custom role.
If a person has been given conflicting access, you'll see a warning on the repository access page. The warning appears with " Mixed roles" next to the person with the conflicting access. To see the source of the conflicting access, hover over the warning icon or click Mixed roles.
To resolve conflicting access, you can adjust your organization's base permissions or the team's access, or edit the custom role. For more information, see: