> For the complete documentation index, see [llms.txt](https://docs.harmony.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.harmony.io/integrations/saas-applications/github.md).
# GitHub
Automate repository access management and developer onboarding with GitHub integration
GitHub is the world's leading software development platform providing Git repository hosting, code review, project management, and collaboration tools. Connecting GitHub to Harmony enables automated repository access provisioning, intelligent developer onboarding, streamlined license management for your engineering organization, and direct visibility into who is active in your organization.
#### What the GitHub integration enables
| Capability | Description |
| ---------------------------- | ------------------------------------------------------------------------------------------------------ |
| Access Management | Automate repository and organization access provisioning |
| Team Synchronization | Sync GitHub teams with HR systems and org structure |
| Onboarding Automation | Automatically provision access for new developers |
| Offboarding Security | Remove access and archive repositories during employee exits |
| License and Usage Visibility | See each member's license tier, derived from your organization's GitHub plan, alongside their activity |
| Custom Agent Workflows | Build automated GitHub workflows using a rich set of operation blocks |
#### Prerequisites
* **GitHub Organization**: You authorize with a GitHub account that is an **owner** of the organization. Organization ownership is what makes the audit log readable, and the audit log is the source of all activity data
* **GitHub Plan**: Member and license data works on any GitHub plan. Activity data comes from the organization audit log, which GitHub makes available to **GitHub Enterprise Cloud** organizations only. Self-hosted GitHub Enterprise Server is not supported - Harmony connects to `github.com` only
* **Harmony Account**: Active Harmony workspace with admin privileges
#### Connect GitHub to Harmony
**Step 1: Navigate to Integrations**
1. Log in to your Harmony dashboard
2. Go to **Settings** > **Integrations**
3. Find **GitHub** under **SaaS Applications**
**Step 2: Authorize GitHub**
1. **Initiate the connection**
1. Click the **GitHub** integration card
2. Click **Connect**
A GitHub authorization window will open.
2. **Authorize in GitHub**
Sign in with a GitHub account that owns your organization if prompted.
1. Review the permissions Harmony is requesting (see [Permissions Explained](#permissions-explained) below)
2. Click **Authorize** to approve the connection
3. The window closes automatically and you are returned to Harmony
There is nothing else to enter - no organization name, app ID, or key. Harmony discovers your organization automatically from the authorizing account. The initial sync pulls up to 90 days of historical activity; after that your member inventory refreshes every 6 hours and activity is collected hourly.
{% hint style="info" %}
**If the authorizing account belongs to more than one organization**, Harmony syncs the first organization GitHub returns for that account. Authorize with an account that belongs to the organization you want synced.
{% endhint %}
#### Disconnect GitHub from Harmony
1. Log in to your Harmony dashboard
2. Go to **Settings** > **Integrations**
3. Find **GitHub** under **SaaS Applications** and click the integration card
4. Click **Disconnect**
5. Confirm the disconnection when prompted
Once disconnected, Harmony stops syncing data from GitHub. Previously synced data remains available in Harmony.
#### What Harmony Syncs
**From GitHub:**
* Organization members - GitHub login and, where available, corporate email
* Organization role for each member (owner/admin or member)
* License tier, derived from your organization's GitHub plan
* Git activity per member, derived from your organization's audit log
{% hint style="info" %}
**How activity is measured:**
Harmony derives activity from **Git** events in your organization's audit log - clone, fetch, and push - and records at most one activity entry per member per day. Automation accounts (logins ending in `[bot]`) are excluded.
A member who only works in the GitHub web UI - reviewing pull requests, commenting on issues, changing settings - performs no Git operations and therefore produces no activity signal.
{% endhint %}
#### License and Usage Data
Once connected, Harmony automatically fetches and surfaces the following information from your GitHub account:
* **License type** - each member's license tier, derived from your organization's GitHub plan
* **Activity trends** - per-user Git activity sourced from your organization's audit log
This gives you a clearer picture of your GitHub adoption alongside your other tools, without any manual data entry.
#### Permissions Explained
**Required access**
| Access | Description | Purpose |
| ---------------- | ------------------------------- | ------------------------------------------------------------------------- |
| `read:org` | Read organization membership | List your organization's members and read each member's organization role |
| `read:audit_log` | Read the organization audit log | Collect per-user Git activity, the source of all activity data in Harmony |
{% hint style="info" %}
The audit log is only readable by an **organization owner**, and only for organizations on GitHub Enterprise Cloud. If either condition is not met, members and license tiers still sync - activity data will simply be empty.
{% endhint %}
#### Custom Agent Builder - GitHub Operations
You can use a comprehensive set of GitHub operation blocks when building custom agents, enabling you to automate GitHub organization management, repository access, and CI/CD workflows directly from the workflow builder.
**Organization and Team Operations**
The following team and organization blocks are available in the custom agent builder:
* **Create / Get Team** - create a new team or retrieve details about an existing one
* **Add Identity Provider Groups to Team** - sync your IdP groups with GitHub teams
* **Add / Update Team Repository Permissions** - manage what access a team has to a given repository
* **List Organization Teams** - retrieve all teams within your GitHub organization, including parent team relationships and permission levels. You can filter results by team type - choosing from all teams, parent teams, or child teams only. Pagination is handled internally so you always get complete results in a single step.
**Repository Operations**
* **Get / Create Repository** - fetch repository details or create new repositories in your organization
* **Get Repository Collaborators** - retrieves all collaborators for a given repository along with their permission levels. Supports an affiliation filter so you can scope results to outside collaborators, direct collaborators, or all collaborators.
* **Get Repository Admins** - lists only the users who have admin-level access to a repository, making it straightforward to audit and act on elevated permissions.
**SAML Identity Operations**
* **List Organization SAML Identities** - retrieve SAML identity data for all members of your GitHub organization. This makes it possible to reliably correlate GitHub users with your corporate directory (such as Entra ID) even when employees have not set a public email address on their GitHub profiles - using the SAML `nameId` set by your identity provider during SSO instead.
* **Filters**: narrow results by GitHub login, SAML/SCIM username, or members only
* **Full identity data returned**: GUID, linked GitHub user, SAML identity fields
#### Use Cases
Automated Developer Onboarding
Automatically add new engineers to the GitHub organization, assign them to teams, and provision repository access based on their role
Self-Service Repository Access
Developers request repository access via Slack and Harmony verifies, routes for approval, and grants access automatically
License Optimization
Identify inactive users, alert the IT team, and automate seat reclamation to reduce GitHub license costs. Because activity is derived from Git operations only, review members who work primarily in the GitHub web UI before reclaiming their seats - they can appear inactive while still using GitHub
Secure Offboarding
Remove departing employees from all teams and repositories, transfer ownership, and document complete access removal
Repository Access Auditing
Use the Get Repository Collaborators and Get Repository Admins actions to build workflows that audit who has access to your repositories, identify over-provisioned users, and trigger remediation steps automatically
Corporate Directory Correlation
Use the List Organization SAML Identities block to match GitHub users to your corporate identity provider records, ensuring accurate access reviews even when GitHub profiles lack public email addresses
Customer Support and Engineering Collaboration
Link customer conversations to GitHub issues, pull requests, or repositories to keep context in one place. Track technical issues reported by customers, escalate bugs to engineering, and close the loop when fixes are shipped
#### Troubleshooting
No data is appearing after connection
**Possible causes:**
* The initial sync has not completed yet
* The authorizing GitHub account is not a member of any organization
**Solutions:**
1. Wait for the initial sync to complete - member inventory runs every 6 hours
2. Reconnect using a GitHub account that belongs to the organization you want to sync
Members sync but there is no activity data
**Possible causes:**
* The organization is not on GitHub Enterprise Cloud - GitHub restricts audit log access to Enterprise Cloud organizations
* The authorizing account is not an owner of the organization, so the audit log cannot be read
* Members use GitHub only through the web UI, which produces no Git events
**Solutions:**
1. Confirm your organization's plan in GitHub under **Organization settings** > **Billing and plans**
2. Disconnect and reconnect the integration with an organization owner account
Members are missing an email address
**Possible causes:**
* Harmony reads corporate emails from your organization's verified domain, falling back to the member's public profile email. Members with neither are synced by their GitHub login only
**Solutions:**
1. Verify your organization's domain in GitHub so member emails become available to the integration
License tier shows as Unknown
**Possible causes:**
* Harmony maps your organization's GitHub plan to a license tier. A plan name it does not recognize is reported as Unknown
**Solutions:**
1. Members and their activity still sync normally - only the tier label is affected
The wrong organization was synced
**Possible causes:**
* The authorizing account belongs to more than one GitHub organization, and Harmony syncs the first one GitHub returns
**Solutions:**
1. Disconnect and reconnect using an account that belongs to the organization you want synced
#### Data & Privacy
Key privacy principles
For information about how Harmony handles your data, see our [Privacy Policy](https://harmony.io/privacy).
* Harmony's GitHub data sync is read-only and does not modify anything in your GitHub organization. Changes are only made by Custom Agent Builder blocks that you explicitly configure and run
* Integration can be revoked at any time from GitHub or Harmony settings
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.harmony.io/integrations/saas-applications/github.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.