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

# GitHub

> Connect a GitHub organization to Layer to inventory repositories, members, branch protection rules, and Copilot seat utilization for security reporting.

The GitHub integration discovers your organization's repositories, members, and Copilot seat utilization — essential for access review, license optimization, and SOC 2 evidence.

## What you'll need

* GitHub **Organization Owner** role on the org you want to connect.
* Two minutes.

## Set it up

<Steps>
  <Step title="Open the GitHub integration in Layer">
    In Layer, go to **Integrations**, find GitHub, and click **Connect**.
  </Step>

  <Step title="Install the Axiom GitHub App">
    You'll be redirected to GitHub. Choose the organization to install on, then pick **All repositories** (recommended for full inventory) or specific repos.
  </Step>

  <Step title="Approve the requested permissions">
    The Axiom GitHub App requests **read-only** access to:

    * **Repository**: Metadata, Contents, Issues, Pull requests
    * **Organization**: Members, Administration, Copilot

    Click **Install**.
  </Step>

  <Step title="Wait for the first sync">
    The initial sync runs immediately. Larger orgs (1,000+ members) may take 15–20 minutes.
  </Step>
</Steps>

## What gets synced

| Object                | Fields                                                                       | Refresh cadence |
| --------------------- | ---------------------------------------------------------------------------- | --------------- |
| Organizations         | login, type                                                                  | Every 6 hours   |
| Repositories          | name, full name, visibility (public/private/internal), default branch, owner | Every 6 hours   |
| Teams                 | name, slug, privacy, member count, repo count                                | Every 6 hours   |
| Team membership       | user → team links                                                            | Every 6 hours   |
| Repository governance | repo → team links with team permission                                       | Every 6 hours   |
| Copilot seats         | total seats provisioned per organization                                     | Daily           |

## Teams, members, and repository governance

Layer enumerates every team in each connected GitHub organization and emits a **Team** asset for each one, along with two relationship types that map who has access to what:

* **MemberOf** — links every team member (a Layer user keyed by GitHub login) to the team they belong to.
* **GovernedBy** — links every repository the team is granted access to back to the team, with the team's permission level (`pull`, `push`, `admin`, etc.) stored on the relationship.

Together these surface the real GitHub access path — *which engineers are on which teams, and which repos those teams govern* — so [access reviews](/layer/access-reviews) and [offboarding](/layer/offboarding) can deprovision team-derived repo access without manually tracing org-wide permissions. Pagination is followed automatically, so orgs with hundreds of teams sync completely.

Private (secret) teams are still discovered as long as the Axiom GitHub App is installed at the organization level with **Members: Read** granted.

## Copilot seat utilization

Layer automatically checks each connected organization for GitHub Copilot seat data. If your organization has a Copilot Business or Enterprise plan, the total number of provisioned seats appears in your asset inventory and feeds compliance evidence. Organizations without Copilot are skipped silently.

## Compliance evidence

GitHub data generates evidence records for the following SOC 2 controls:

| Evidence                                      | Controls     |
| --------------------------------------------- | ------------ |
| Repository inventory and visibility breakdown | CC8.1        |
| Organization governance                       | CC8.1        |
| Team membership and repository governance     | CC6.1, CC6.3 |
| Copilot seat utilization                      | CC7.2        |

See the [SOC 2 evidence catalog](/codex/soc2-evidence-catalog) for full control descriptions.

## Why GitHub App, not OAuth or PAT

GitHub Apps issue **fine-grained, expiring tokens** scoped to the specific resources you authorized. Personal Access Tokens (the old way) grant a single user's full account access until manually revoked — much worse for least-privilege.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Members show but teams don't">
    Re-check that you installed on the **organization**, not your personal account. Reinstall via [github.com/settings/installations](https://github.com/settings/installations) and pick the org.
  </Accordion>

  <Accordion title="Teams sync but membership or repo links are missing">
    The Axiom GitHub App needs **Organization → Members: Read** to enumerate team members and **Repository → Metadata: Read** to enumerate team-governed repositories. Both are requested by default during install — if the install was customized to a narrower scope, reinstall via [github.com/settings/installations](https://github.com/settings/installations) and accept the full permission set.
  </Accordion>

  <Accordion title="Copilot seats show as zero">
    Copilot seat data requires a Copilot Business or Enterprise subscription on the organization. If your org uses individual Copilot plans, seat counts aren't available through the organization API.
  </Accordion>

  <Accordion title="I want to disconnect">
    Go to **Integrations → GitHub → Disconnect** in Layer, then uninstall the Axiom app from [github.com/organizations/YOUR\_ORG/settings/installations](https://github.com).
  </Accordion>
</AccordionGroup>