[CXH-2123] - Add provisioning for the Enterprise Owner role - GitHub Enterprise Connector

README.md

@@ -44,6 +44,7 @@ baton resources
 - Users
 - Teams
 - Repositories
+- Enterprise roles, when `--enterprises` is set. With a GitHub App, the built-in Enterprise Owner role can also be granted and revoked.
 
 By default, `baton-github-enterprise` will sync information from any organizations that the provided credential has Administrator permissions on. You can specify exactly which organizations you would like to sync using the `--orgs` flag.
 
@@ -109,4 +110,8 @@ Org:
 
 Repo:
 - Administrator: Read and Write
-  - This permission implies Metadata: Read
+  - This permission implies Metadata: Read
+
+Enterprise (GitHub App with `--enterprises` only):
+- Enterprise people: Read and Write
+  - The app must be installed on the enterprise account as well as on the organization. This is what syncs and provisions the built-in Enterprise Owner role.

baton_capabilities.json

@@ -73,7 +73,8 @@
         ]
       },
       "capabilities": [
-        "CAPABILITY_SYNC"
+        "CAPABILITY_SYNC",
+        "CAPABILITY_PROVISION"
       ],
       "permissions": {}
     },

config_schema.json

@@ -163,7 +163,7 @@
     {
       "name": "enterprises",
       "displayName": "Enterprises",
-      "description": "Sync enterprise roles, must be an admin of the enterprise.",
+      "description": "Sync enterprise roles, must be an admin of the enterprise. A personal access token syncs every role. A GitHub App syncs and provisions the built-in Owner role instead, and needs to be installed on the enterprise account as well as on the organization, with the \"Enterprise people: read and write\" permission.",
       "stringSliceField": {}
     },
     {

docs/connector.mdx

@@ -21,7 +21,7 @@ If you access GitHub at `github.com`, go to the [GitHub](/baton/github) integrat
 | Teams | <Icon icon="square-check" iconType="solid"  color="#c937ae"/> | <Icon icon="square-check" iconType="solid"  color="#c937ae"/> |
 | Orgs\* | <Icon icon="square-check" iconType="solid"  color="#c937ae"/> | <Icon icon="square-check" iconType="solid"  color="#c937ae"/> |
 | Org roles\*\* | <Icon icon="square-check" iconType="solid"  color="#c937ae"/> | <Icon icon="square-check" iconType="solid"  color="#c937ae"/> |
-| Enterprise roles | <Icon icon="square-check" iconType="solid"  color="#c937ae"/> |  |
+| Enterprise roles\*\*\*\* | <Icon icon="square-check" iconType="solid"  color="#c937ae"/> | <Icon icon="square-check" iconType="solid"  color="#c937ae"/> |
 | Licenses | <Icon icon="square-check" iconType="solid"  color="#c937ae"/> |  |
 | Secrets - API keys | <Icon icon="square-check" iconType="solid"  color="#c937ae"/> |  |
 | GitHub App | <Icon icon="square-check" iconType="solid"  color="#c937ae"/> |  |
@@ -35,12 +35,26 @@ The GitHub Enterprise connector supports [automatic account provisioning and dep
 
 \*\*\* Only synced when **Sync user last activity** is enabled. See [Sync member last activity](#sync-member-last-activity) below.
 
+\*\*\*\* Only synced when **Enterprises** is set. Only the built-in **Enterprise Owner** role can be provisioned, and only with GitHub App authentication. See [Enterprise Owner provisioning](#enterprise-owner-provisioning) below.
+
 [This connector can sync secrets](/product/admin/inventory) and display them on the **Inventory** page. 
 
 <Warning>
-Syncing the **Licenses** resource type only works with a personal access token (classic). GitHub App installation tokens are not supported for license sync.
+Syncing the **Licenses** resource type only works with a personal access token (classic). GitHub App installation tokens are not supported for license sync. If you use a GitHub App and set **Enterprises**, leave the **Licenses** resource type disabled.
 </Warning>
 
+### Enterprise Owner provisioning
+
+C1 can grant and revoke the built-in **Enterprise Owner** role when the connector uses a GitHub App that is installed on both the enterprise account and the organization, with the **Enterprise people** permission set to read and write. A personal access token syncs enterprise roles but cannot provision them.
+
+Granting Owner sends the user an enterprise administrator invitation. The grant appears in C1 right away, but the user holds the role only after accepting the invitation in GitHub, and C1 shows a pending invitation and an accepted Owner as the same grant. For time-bound access, the clock starts when the invitation is sent. If the window closes before the user accepts, the invitation is cancelled and they never hold the role. GitHub expires pending invitations after seven days.
+
+A user who already administers the enterprise, such as a billing manager, cannot be invited, and the request fails with GitHub's reason. Manage Owner for those users in GitHub.
+
+Revoking Owner keeps the user as a member of the enterprise and cancels an invitation that has not been accepted.
+
+Enterprise roles are a GitHub Enterprise Cloud feature. Setting **Enterprises** on GitHub Enterprise Server fails the sync, because that host has no Owner invitation API. On Enterprise Cloud, if the app is not installed on the enterprise account, or the organization does not belong to that enterprise, that enterprise is left out of the sync. C1 then drops its Owner grants until the installation is restored.
+
 ## Gather GitHub Enterprise credentials 
 
 Configuring the connector requires you to pass in credentials generated in GitHub Enterprise. Gather these credentials before you move on. To set up the GitHub Enterprise connector, you can choose to create either a personal access token (classic) or a fine-grained access token.
@@ -103,11 +117,11 @@ Follow these instructions to integrate your GitHub instance by using a [GitHub a
 This process creates a GitHub app that is only available to your GitHub organization, then generates an installation token for that app, which can be used to integrate the GitHub organization with C1. This creates the equivalent of a personal access token, but does not tie the token to a specific identity.
 
 <Tip>
-**Integrating multiple GitHub organizations requires separate GitHub Apps and connectors.** GitHub Enterprise APIs do not support GitHub App tokens and require classic PATs with the [`admin:enterprise`](https://docs.github.com/en/rest/enterprise-teams/enterprise-teams?apiVersion=2022-11-28) scope.
+**Integrating multiple GitHub organizations requires separate GitHub Apps and connectors.** To sync and provision the built-in Enterprise Owner role, the same app must also be installed on the enterprise account. License sync still requires a classic PAT with the [`admin:enterprise`](https://docs.github.com/en/rest/enterprise-teams/enterprise-teams?apiVersion=2022-11-28) scope.
 </Tip>
 
 <Warning>
-A user with the **Org Owner** permission in the GitHub organization to be integrated with C1 must perform this task.
+A user with the **Org Owner** permission in the GitHub organization to be integrated with C1 must perform this task. Installing the app on the enterprise account requires an **Enterprise Owner**.
 </Warning>
 
 <Steps>
@@ -154,6 +168,7 @@ In the **Permissions** section of the page, give the app the following permissio
 
    - Enterprise permissions:
 
+      - **Enterprise people**: Read and write access (required to sync and provision the built-in Enterprise Owner role)
       - **Custom enterprise roles**: Read-only access
       - **Enterprise custom properties for organizations**: Read-only access
 
@@ -189,6 +204,9 @@ Select the repositories the app can act on.
 <Step>
 Click **Install**.
 </Step>
+<Step>
+To sync and provision the built-in Enterprise Owner role, install the app on the enterprise account as well. Open the app's installation page again and select your enterprise. The enterprise is listed as an installation target when you are an Enterprise Owner and the app requests enterprise permissions. See [Installing a GitHub App on your enterprise](https://docs.github.com/enterprise-cloud@latest/apps/using-github-apps/installing-a-github-app-on-your-enterprise). The enterprise installation does not grant organization or repository access, so both installations are needed.
+</Step>
 </Steps> 
 
 **Done.** Next, move on to the connector configuration instructions. 
@@ -241,7 +259,7 @@ If you're using a personal access token to set up the connector:
 
    1. **Optional.** If you want to sync only specific organizations, enter the organizations' names in the **Organizations** field. If you do not specify specific organizations, C1 will sync all organizations.
 
-   1. **Optional.** If you want to sync roles for only some enterprises, add the names of the enterprises in the **Enterprises to sync enterprise roles for** field.
+   1. **Optional.** If you want to sync roles for only some enterprises, add the names of the enterprises in the **Enterprises** field. A personal access token syncs those roles and cannot provision them.
 
    1. **Optional.** If you do not want to include archived repos in syncs, click to enable **Omit archived repositories**.
 
@@ -262,7 +280,7 @@ If you're using a GitHub app to set up the connector:
 
    1. In the **Organization** field, enter the name of the GitHub organization associated with the GitHub app. **You must enter a single organization name in this field or the connector configuration will fail.**
 
-   1. **Optional.** If you want to sync roles for only some enterprises, add the names of the enterprises in the **Enterprises to sync enterprise roles for** field.
+   1. **Optional.** To sync and provision the built-in Enterprise Owner role, enter the enterprise that owns the organization in the **Enterprises** field. The app must be installed on that enterprise account. See [Enterprise Owner provisioning](#enterprise-owner-provisioning).
 
    1. **Optional.** If you do not want to include archived repos in syncs, click to enable **Omit archived repositories**.