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
Copy file name to clipboardExpand all lines: content/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app.md
+7-5Lines changed: 7 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -25,19 +25,21 @@ category:
25
25
26
26
Although {% data variables.product.prodname_github_apps %} don't have any permissions by default, they do have implicit permissions to read public resources when acting on behalf of a user. When a user authorizes the app to act on their behalf, the {% data variables.product.prodname_github_app %} can use the resulting user access token to make requests to the REST API and the GraphQL API to read public resources. To learn more about acting on behalf of a user, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user).
27
27
28
-
App permissions are classified as repository, organization,{% ifversion enterprise-installed-apps %} enterprise,{% endif %} or account permissions.
28
+
App permissions are classified as repository, organization,{% ifversion fpt or enterprise-installed-apps %} enterprise,{% endif %} or account permissions.
29
29
30
30
* Repository permissions allow your app to access resources related to repositories that are owned by the account where the app is installed.
31
31
* Organization permissions allow your app to access resources related to the organization where the app is installed, if it is installed on an organization account.
32
-
{%- ifversion enterprise-installed-apps %}
32
+
{%- ifversion fpt or enterprise-installed-apps %}
33
33
* Enterprise permissions allow the app to manage an enterprise, if it is installed on an enterprise account.{%- endif %}
34
34
* Account permissions allow your app to access resources related to a user if the user has also authorized your app. For more information about user authorization of apps, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user).
35
35
36
-
{% ifversion enterprise-installed-apps %}
36
+
{% ifversion fpt or enterprise-installed-apps %}
37
37
38
-
Enterprise permissions are only available if you are creating the app in an enterprise account or an organization that is enterprise-owned. An app with enterprise permissions must be `public` or `internal` to be installed on an enterprise account. The only enterprise it can be installed on is the enterprise that owns the app or the organization that owns the app, but there are no additional restrictions on which organizations or personal accounts it can be installed on.{% endif %}
38
+
Any user, organization, or enterprise can create an app using any of the permission types. An app with enterprise permissions must be `public` or `internal` to be installed on an enterprise account. A `public` app can be installed by any enterprise, while an `internal` app can only be installed by the enterprise that owns the app or the enterprise of the organization that owns the app. There are no additional restrictions on which organizations or personal accounts an app can be installed on.
39
39
40
-
When a user installs an app on their user account or organization, they see and grant the repository and organization permissions that the app requested.{% ifversion enterprise-installed-apps %} When they install it on their enterprise, they see and grant only the enterprise permissions that the app requested. {% endif %} They will also see a list of account permissions that the app can request for individual users. When a user authorizes an app to act on their behalf, they will see and grant the account permissions that the app requested.
40
+
There is one exception to installing an app across enterprises. If an app requests the "Enterprise organization installations" or "Enterprise organization installation repositories" permissions, the only enterprise that can install it is the one that owns the app. You cannot install the app on another enterprise, and you cannot add either permission to an app that is already installed on an enterprise other than the one that owns it.{% endif %}
41
+
42
+
When a user installs an app on their user account or organization, they see and grant the repository and organization permissions that the app requested.{% ifversion fpt or enterprise-installed-apps %} When they install it on their enterprise, they see and grant only the enterprise permissions that the app requested. {% endif %} They will also see a list of account permissions that the app can request for individual users. When a user authorizes an app to act on their behalf, they will see and grant the account permissions that the app requested.
41
43
42
44
The success of an API request with a user access token depends on the user's permissions as well as the app's permissions. For example, if the app was granted permission to write the contents of a repository, but the user can only read the contents, then the user access token can only read the contents. The success of an API request with an installation access token only depends on the app's permissions.
Copy file name to clipboardExpand all lines: content/apps/using-github-apps/about-using-github-apps.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -17,7 +17,7 @@ category:
17
17
## Finding {% data variables.product.prodname_github_apps %}
18
18
19
19
{% ifversion fpt or ghec %}
20
-
You can discover {% data variables.product.prodname_github_apps %} on [{% data variables.product.prodname_marketplace %}](https://github.com/marketplace). {% else %}You cannot install third-party applications on your enterprise. If you want to use the functionality of a third-party app, you can contact the app developer about creating an app from a manifest or from URL parameters. For more information, see [AUTOTITLE](/apps/sharing-github-apps/registering-a-github-app-from-a-manifest) and [AUTOTITLE](/apps/sharing-github-apps/registering-a-github-app-using-url-parameters).{% endif %}{% ifversion enterprise-installed-apps %} You cannot install third-party applications on your enterprise account—they must be owned by your enterpriseor an organization in your enterprise.{% endif %}
20
+
You can discover {% data variables.product.prodname_github_apps %} on [{% data variables.product.prodname_marketplace %}](https://github.com/marketplace). Developers can also share a link to their public app directly, even if it's not in the {% data variables.product.prodname_marketplace %}. {% else %}You cannot install third-party applications on your enterprise. If you want to use the functionality of a third-party app, you can contact the app developer about creating an app from a manifest or from URL parameters. For more information, see [AUTOTITLE](/apps/sharing-github-apps/registering-a-github-app-from-a-manifest) and [AUTOTITLE](/apps/sharing-github-apps/registering-a-github-app-using-url-parameters).{% endif %}{% ifversion enterprise-installed-apps %} On {% data variables.product.prodname_dotcom_the_website %} you can install public apps from any developer on your enterprise, organization, or user account, as long as you trust the developer.{% endif %}
21
21
22
22
{% data reusables.data-residency.github-marketplace-apps-unsupported %}
Copy file name to clipboardExpand all lines: content/apps/using-github-apps/installing-a-github-app-from-a-third-party.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -36,7 +36,7 @@ Anyone can install {% data variables.product.prodname_github_apps %} on their pe
36
36
37
37
Organization owners can install {% data variables.product.prodname_github_apps %} on their organization.{% ifversion enterprise-installed-apps %}
38
38
39
-
Enterprise owners can install {% data variables.product.prodname_github_apps %} on their enterprise accounts, if the application requests enterprise permissions and is owned by the enterpriseor one of its organizations.
39
+
Enterprise owners can install {% data variables.product.prodname_github_apps %} on their enterprise accounts, if the application requests enterprise permissions. The app can be owned by the enterprise, an organization within the enterprise, or a third-party developer. Third-party apps must be public and cannot request the "Enterprise organization installations" or "Enterprise organization installation repositories" permissions.
40
40
{% endif %}
41
41
42
42
{% data reusables.apps.repo-admin-install-restriction %}
Copy file name to clipboardExpand all lines: content/apps/using-github-apps/installing-a-github-app-on-your-enterprise.md
+4-1Lines changed: 4 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -24,7 +24,10 @@ When an enterprise owner installs a {% data variables.product.prodname_github_ap
24
24
25
25
The {% data variables.product.prodname_github_app %} must request enterprise-level permissions. It can request other permissions as well, but only the enterprise permissions will be granted during installation.
26
26
27
-
The app must be owned by your enterprise or an organization within your enterprise. You cannot install apps owned by an account outside your enterprise.
27
+
The app can be owned by your enterprise, by an organization within your enterprise, or by a third-party developer. To install a public app from a third party, use the installation link that the app's developer provides. You cannot install a private app that is owned by an account outside your enterprise.
28
+
29
+
> [!NOTE]
30
+
> There is one exception to installing a third-party app across enterprises. If an app requests the "Enterprise organization installations" permission, it can only be installed on the enterprise that owns the app. You cannot install this app on your enterprise if it is owned outside your enterprise. In EMU enterprises and GHES, enterprise's users count as being within the enterprise, so their apps can be installed on the enterprise.
28
31
29
32
## Installing a {% data variables.product.prodname_github_app %} on your enterprise
Copy file name to clipboardExpand all lines: content/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/configure-enterprise-managed-settings.md
+48-3Lines changed: 48 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -15,7 +15,7 @@ category:
15
15
- Manage Copilot for a team
16
16
---
17
17
18
-
With enterprise managed settings, enterprise owners can centrally define and distribute configuration settings to supported clients for users on your enterprise's {% data variables.product.prodname_copilot_short %} plan, ensuring every member works within the same guardrails.
18
+
With enterprise managed settings, enterprise owners can centrally define and distribute configuration settings to supported clients for users on your enterprise's {% data variables.product.prodname_copilot_short %} plan, ensuring every member works within the guardrails you define, while letting teams tailor the settings you allow.
19
19
20
20
The following clients are supported, although not every client supports every property:
21
21
@@ -24,14 +24,16 @@ The following clients are supported, although not every client supports every pr
24
24
* The {% data variables.copilot.github_copilot_app %}
25
25
* {% data variables.copilot.copilot_cloud_agent %}
26
26
27
-
These settings apply enterprise-wide, with no organization-level override. For each supported key, the `{% data variables.copilot.managed_setting_file %}` value takes precedence over any file-based configuration a user sets in their client.
27
+
These settings apply enterprise-wide and enterprises can customize specific keys to enterprise teams. For each supported key, the `{% data variables.copilot.managed_setting_file %}` value takes precedence over any file-based configuration a user sets in their client.
28
28
29
29
Managed settings are loaded locally when the client starts, even if the device has no network connection. This means controls such as suppressing the `allow-all` permission options and restricting plugin configuration still apply before sign in or any server round trip, and remain active when users switch accounts.
30
30
31
31
## Defining settings
32
32
33
33
For detailed information on the available properties and syntax, see [AUTOTITLE](/copilot/reference/enterprise-managed-settings-reference).
34
34
35
+
Use `copilot/{% data variables.copilot.team_mappings_file %}` and the `copilot/{% data variables.copilot.team_settings_directory %}` directory when you need one or more enterprise teams to use settings that differ from the defaults in `copilot/{% data variables.copilot.managed_setting_file %}`. For more information, see [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/configure-enterprise-managed-settings#overriding-settings-for-specific-teams).
36
+
35
37
## Choosing a deployment method
36
38
37
39
There are multiple ways to deploy enterprise managed settings. Use the following guidelines to choose the right method for you. For any method, pilot on a small device group before broad deployment.
@@ -50,6 +52,47 @@ There are additional considerations if you use a dedicated enterprise for {% dat
50
52
1. Commit and push your changes to the default branch.
51
53
1. Confirm that enterprise users are running a supported client. Updated settings are applied automatically within about an hour, or immediately after the client restarts or the user signs in again.
52
54
55
+
## Overriding settings for specific teams
56
+
57
+
For server-managed deployments, use `copilot/{% data variables.copilot.team_mappings_file %}` and the `copilot/{% data variables.copilot.team_settings_directory %}` directory when one or more enterprise teams should use settings that differ from your default `copilot/{% data variables.copilot.managed_setting_file %}` values. `enabledPlugins` and `extraKnownMarketplaces` work additively. The enterprise `{% data variables.copilot.managed_setting_file %}` sets a baseline, and an enterprise team file can add more plugins and marketplaces on top of it.
58
+
59
+
1. In your enterprise's `copilot/{% data variables.copilot.managed_setting_file %}` file, mark each key you want to make eligible for override using the `{ "overridable": <VALUE> }` syntax. The `json` files you map to teams can only send different values for keys you mark overridable. An `overridable` value you provide in `managed-settings.json` is the default when teams files do not declare a different value for a given key.
60
+
For example, to defer both `model` and `disableBypassPermissionsMode`:
1. In your enterprise's `.github-private` repository, create `copilot/{% data variables.copilot.team_mappings_file %}`. Map each team settings file to one or more enterprise team slugs. The key is the settings file name and the value is an array of team slugs, so you can apply one file across multiple teams.
72
+
73
+
```json
74
+
{
75
+
"devs.json": ["developers-all", "finops-dev"],
76
+
"ai-users.json": ["ai-baseline-trained"],
77
+
"frontier.json": ["ai-pioneers"]
78
+
}
79
+
```
80
+
81
+
1. Create the team settings file under `copilot/{% data variables.copilot.team_settings_directory %}`. Include only the keys you marked as overridable. Every other key stays governed by your enterprise default.
82
+
83
+
```json
84
+
{
85
+
"model": "unmanaged",
86
+
"permissions": {
87
+
"disableBypassPermissionsMode": "unmanaged"
88
+
}
89
+
}
90
+
```
91
+
92
+
1. Commit and push your changes to the default branch.
93
+
94
+
{% data variables.product.prodname_dotcom %} evaluates enterprise team membership and applies matching settings for each person. If a user belongs to multiple teams, their team files are combined using the least restrictive value for each key, then applied beneath the enterprise settings, where platform decisions always win.
95
+
53
96
## Deploying MDM-managed settings
54
97
55
98
1. Create or update your `{% data variables.copilot.managed_setting_file %}` payload using the same JSON schema used for server-managed settings.
@@ -70,7 +113,9 @@ There are additional considerations if you use a dedicated enterprise for {% dat
70
113
71
114
## Verifying the configuration has applied
72
115
73
-
Once the configuration is committed, users on a supported client see the specified settings within about an hour, since clients periodically check the server for updated configuration. Restarting the client or signing in again applies the latest settings immediately.
116
+
Once the configuration is committed, users on a supported client see the specified settings within about an hour, since clients periodically check the server for updated configuration. For server-managed deployments, this includes `copilot/{% data variables.copilot.managed_setting_file %}`, `copilot/{% data variables.copilot.team_mappings_file %}`, and files in `copilot/{% data variables.copilot.team_settings_directory %}`.
117
+
118
+
Restarting the client or signing in again applies the latest settings immediately.
74
119
75
120
If a user does not see these settings, ensure they receive access to {% data variables.product.prodname_copilot_short %} through your enterprise or one of its organizations. If a user receives a license from multiple billing entities, ensure they have selected your enterprise in the "Usage billed to" dropdown in their [personal {% data variables.product.prodname_copilot_short %} settings](https://github.com/settings/copilot/features).
0 commit comments