> ## Documentation Index
> Fetch the complete documentation index at: https://klef.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Enterprise

<div className="page-title-row">
  <img src="https://mintcdn.com/klef/xJ0kXbcegZOD2G3h/images/connectors/github-enterprise.svg?fit=max&auto=format&n=xJ0kXbcegZOD2G3h&q=85&s=47373c523b5d67a3dda25579e8838ac0" alt="" noZoom width="24" height="24" data-path="images/connectors/github-enterprise.svg" />

  <h1>GitHub Enterprise</h1>
</div>

## Connection

### Setup

Klef provisions
[Enterprise Managed Users over SCIM](https://docs.github.com/en/enterprise-cloud@latest/admin/managing-iam/provisioning-user-accounts-with-scim).

### Settings

| Setting         | Required | Description                                                                                             |
| --------------- | -------- | ------------------------------------------------------------------------------------------------------- |
| Enterprise      | Yes      | Enterprise slug, as in github.com/enterprises/acme-inc.                                                 |
| GHE.com API URL |          | API address of an enterprise on GHE.com. Leave empty for GitHub.com.                                    |
| Access token    | Yes      | Classic token with the scim:enterprise scope, created by the enterprise's setup user. Stored encrypted. |

### Permissions

Minimum permissions the connection requires.

| Capability      | Required | Granted by (any one) |
| --------------- | -------- | -------------------- |
| Provision users | Yes      | `scim:enterprise`    |
| Read groups     | Yes      | `scim:enterprise`    |

## github\_enterprise.user

### Fields

| Field                               | Type            | Required | Description                                                                                                                                             |
| ----------------------------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `userName`                          | string          | Yes      | User name the identity provider signs the person in with, usually their email address.                                                                  |
| `externalId` (Identity provider ID) | reference, user | Yes      | The identity provider's ID for the person. Cannot change once the account exists. Names the account rather than describing it, so a diff leaves it out. |
| `displayName`                       | string          | Yes      | Full name shown on GitHub.                                                                                                                              |
| `givenName`                         | string          | Yes      | First name.                                                                                                                                             |
| `familyName`                        | string          | Yes      | Last name.                                                                                                                                              |
| `email`                             | string          | Yes      | Primary email address.                                                                                                                                  |
| `active`                            | bool            |          | Whether the account is active. An inactive account is suspended, never deleted.                                                                         |
| `groups`                            | grant           |          | Enterprise groups the user belongs to. A group can be linked to organization teams. One row grants one group.                                           |
| `groups[]`                          | string          |          | Group ID.                                                                                                                                               |

### Default Account Matching Rules

When Klef [adopts](/docs/adoption) an account that already exists in GitHub Enterprise, it works out whose it is by trying these in order. A connection can override them.

| Account field | Worker field            |
| ------------- | ----------------------- |
| `userName`    | `worker.business_email` |

## Examples

### GitHub Enterprise managed users

Provision managed GitHub accounts into IdP groups, pause them on leave, and suspend them when an engineer leaves.

```hcl theme={null}
stage active {
  target github_enterprise.user {
    userName    = worker.business_email
    externalId  = lookup(table.idp_user_ids, worker.business_email)
    displayName = worker.display_name
    givenName   = worker.legal_name.given
    familyName  = worker.legal_name.family
    email       = worker.business_email
    active      = true
    groups      = ["Engineering"]
  }
}
```