You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
title: Creating custom organization roles in an enterprise
3
+
intro: Create roles with fine-grained permissions for a consistent experience across your organizations.
4
+
versions:
5
+
feature: ent-owner-custom-org-roles
6
+
type: how_to
7
+
topics:
8
+
- Enterprise
9
+
- Organizations
10
+
shortTitle: Custom organization roles
11
+
---
12
+
13
+
To define consistent sets of permissions for settings and repositories, you can create custom organization roles for use in all of the enterprise's organizations. This allows centralized management of common roles such as "Developer" or "SRE team."
14
+
15
+
Custom organization roles created at the enterprise level use the same organization and repository permissions and base roles as roles created at the organization level. There is no difference in how these roles function or what they can allow. For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles).
16
+
17
+
Enterprise owners can create and edit custom organization roles, but cannot assign them. Organization owners can assign custom roles in an organization.
18
+
19
+
>[!NOTE] An enterprise can create up to 20 custom organization roles. This limit applies to the enterprise: each organization can also create up to 20 custom organization roles.
20
+
21
+
{% data reusables.enterprise-accounts.access-enterprise %}
22
+
{% data reusables.enterprise-accounts.people-tab %}
23
+
1. In the left sidebar, select **Organization roles**.
@@ -35,33 +39,6 @@ All users that are part of your enterprise have one of the following roles.
35
39
36
40
People with collaborator access to repositories are listed in your enterprise's "People" tab, but are not enterprise members and do not have access to the enterprise. See {% ifversion ghec %}[AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#outside-collaborators-or-repository-collaborators).{% else %}[AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#outside-collaborators).{% endif %}
37
41
38
-
## How do I assign roles?
39
-
40
-
{% ifversion ghec %}
41
-
If you use an **enterprise with personal accounts**:
42
-
43
-
* People become enterprise members when they are added as a member or owner of an organization. See [AUTOTITLE](/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization).
44
-
* You can invite someone to become an enterprise owner or billing manager. See [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise).
45
-
46
-
If you use an **{% data variables.enterprise.prodname_emu_enterprise %}**:
47
-
48
-
* You must provision all users through your identity provider (IdP).
49
-
* You select each user's enterprise role using your IdP. The role cannot be changed on {% data variables.product.prodname_dotcom %}.
50
-
* To assign the guest collaborator role, you may need to update your IdP.
51
-
52
-
For more information about the different types of enterprise accounts, see [AUTOTITLE](/admin/identity-and-access-management/understanding-iam-for-enterprises/choosing-an-enterprise-type-for-github-enterprise-cloud#about-types-of-enterprises).
53
-
54
-
{% elsif ghes %}
55
-
56
-
When a user has joined your {% data variables.product.prodname_ghe_server %} instance, you can:
57
-
58
-
* Add the user to an organization. See [AUTOTITLE](/organizations/managing-membership-in-your-organization/adding-people-to-your-organization).
59
-
* Invite the user to become an enterprise owner. See [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise).
60
-
61
-
If you provision users with SCIM, you assign each user's enterprise role on your identity provider (IdP). The role cannot be changed on {% data variables.product.prodname_dotcom %}.
62
-
63
-
{% endif %}
64
-
65
42
## Enterprise owners
66
43
67
44
Enterprise owners have complete control over the enterprise and can take every action, including:
@@ -70,8 +47,8 @@ Enterprise owners have complete control over the enterprise and can take every a
* Enforcing policy across organizations{% ifversion ghec %}
51
+
* Managing billing settings{% endif %}
75
52
76
53
For security, we recommend making **only a few people** enterprise owners.
77
54
@@ -128,17 +105,6 @@ You can add unaffiliated users from your identity provider (for {% data variable
128
105
129
106
{% endif %}
130
107
131
-
## Custom organization roles
132
-
133
-
With {% data variables.product.prodname_ghe_cloud %} and starting from {% data variables.product.prodname_ghe_server %} 3.19, enterprise owners can create custom organization roles for use in all of the enterprise's organizations. This allows centralized management of common roles such as "Developer" or "SRE team". Only enterprise owners can create or edit these roles, and any organization owner or user with the "Manage organization roles" permission can assign them in an organization.
134
-
135
-
When creating an organization role, enterprise owners can use the same organization and repository permissions and base roles as organization owners—there is no difference in how these roles function or what they can allow.
136
-
137
-
{% data reusables.enterprise-accounts.access-enterprise %}
138
-
{% data reusables.enterprise-accounts.people-tab %}
139
-
1. Select the "Organization Roles" section in the left-hand menu.
140
-
1. Create a new role using the "Create custom role" button, or edit an existing role using the ellipsis menu (...).
141
-
142
-
See [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles) for more information about creating and assigning custom organization roles.
108
+
## Next steps
143
109
144
-
At this time, up to 20 custom organization roles can be created by the enterprise. This limit is only for the enterprise - each organization can also create up to 20 custom organization roles.
110
+
When you have decided which roles your users require, assign the roles to them. See [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/assign-roles).
intro: Assign roles to govern what people can do in your enterprise.
4
+
versions:
5
+
ghec: '*'
6
+
ghes: '*'
7
+
type: how_to
8
+
shortTitle: Assign roles
9
+
---
10
+
11
+
Users in an enterprise have roles for the enterprise and for organizations where they have access. For more information, see [AUTOTITLE](/admin/overview/about-roles).
12
+
13
+
## Assigning enterprise roles
14
+
15
+
{% ifversion ghec %}
16
+
If you use an **enterprise with personal accounts**:
17
+
18
+
* People become enterprise members when they are added as a member or owner of an organization. See [AUTOTITLE](/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization).
19
+
* You can invite someone to become an enterprise owner or billing manager. See [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise).
20
+
* You can add people as unaffiliated users without adding them to the enterprise. See [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/invite-users-directly).
21
+
22
+
If you use an **{% data variables.enterprise.prodname_emu_enterprise %}**:
23
+
24
+
* You must provision all users through your identity provider (IdP).
25
+
* You select each user's enterprise role using your IdP. The role cannot be changed on {% data variables.product.prodname_dotcom %}.
26
+
* To assign the guest collaborator role, you may need to update your IdP.
27
+
28
+
{% elsif ghes %}
29
+
30
+
When a user has joined your {% data variables.product.prodname_ghe_server %} instance, you can:
31
+
32
+
* Add the user to an organization. See [AUTOTITLE](/organizations/managing-membership-in-your-organization/adding-people-to-your-organization).
33
+
* Invite the user to become an enterprise owner. See [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise).
34
+
35
+
If you provision users with SCIM, you assign each user's enterprise role on your identity provider (IdP). The role cannot be changed on {% data variables.product.prodname_dotcom %}.
36
+
37
+
{% endif %}
38
+
39
+
## Assigning organization roles
40
+
41
+
Organization administrators can assign roles to users and teams in their organization. See [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/using-organization-roles#assigning-an-organization-role).
intro: 'Learn how roles allow you to control people''s access to your enterprise''s settings and resources.'
4
+
versions:
5
+
ghec: '*'
6
+
ghes: '*'
7
+
shortTitle: About roles
8
+
type: overview
9
+
topics:
10
+
- Enterprise
11
+
- Fundamentals
12
+
---
13
+
14
+
## What are roles?
15
+
16
+
A role is a set of permissions that you can assign to individuals or teams. A permission is the ability to perform a specific action, such as changing billing settings.
17
+
18
+
A user in an enterprise has a role for both the enterprise account itself and for each individual organization in the enterprise.
19
+
20
+
* The enterprise-level role defines the user's access to enterprise settings, and to internal repositories across the enterprise.
21
+
* Organization-level roles define the user's access to organization settings and repositories in that organization.
22
+
23
+
## Predefined and custom roles for organizations
24
+
25
+
Organization roles can be **predefined** or **custom**.
26
+
27
+
* Predefined roles, such as organization owner or billing manager, grant blanket permissions to users or teams. They may contain more permissions than someone needs to do their job.
28
+
* Custom roles include fine-grained permissions for organization settings and repository access. They allow you to follow the principle of least privilege by giving teams just the access they need to do their jobs. For example, you could allow a team to view your audit logs without allowing them to change policies.
29
+
30
+
We recommend using custom roles wherever possible. However, if a predefined role meets your needs, this is the quickest way to grant permissions.
31
+
32
+
## Who can assign roles?
33
+
34
+
Enterprise roles are assigned when a user is invited to the enterprise (personal accounts) or provisioned from an identity provider.{% ifversion ent-owner-custom-org-roles %} Enterprise owners can also create custom organization roles to be used across organizations, but these roles can only be assigned by organization administrators.{% endif %}
35
+
36
+
Organization administrators can grant organization roles and create custom organization roles, but can't affect roles at the enterprise level.
37
+
38
+
## Next steps
39
+
40
+
Review the predefined roles and fine-grained permissions available with custom organization roles, and plan out what roles will be required for your teams to do their jobs on {% data variables.product.github %}.
To ensure continued access, we recommend giving the enterprise owner role to at least two people, and the organization owner role to at least two people per organization. However, you should grant most teams only the minimum level of access they require.
For more information, or to purchase {% data variables.product.prodname_enterprise %}, see [{% data variables.product.prodname_enterprise %}](https://github.com/enterprise).
0 commit comments