> 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
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 usage and cost data.
#### 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 | Pull GitHub plan, Copilot seat, and billing data directly into Harmony |
| Custom Agent Workflows | Build automated GitHub workflows using a rich set of operation blocks |
#### Prerequisites
* **GitHub Organization**: Organization owner or admin access
* **GitHub Plan**: Team, Enterprise Cloud, or Enterprise Server
* **Harmony Account**: Active Harmony workspace
#### Connect GitHub to Harmony
**Step 1: Create GitHub App**
1. Go to your GitHub organization settings: `https://github.com/organizations/[org-name]/settings/apps`
2. Click **New GitHub App** and configure:
* **GitHub App name**: `Harmony IT Operations`
* **Callback URL**: `https://app.harmony.io/auth/github/callback`
* **Repository permissions**: Administration (Read & Write), Metadata (Read), Members (Read & Write)
* **Organization permissions**: Members (Read & Write), Administration (Read & Write)
* **Events**: Member, Membership, Organization, Repository, Team
3. Click **Create GitHub App**, then **Generate a private key** and copy the **App ID** and **Client ID**
4. Click **Install App**, select your organization, and click **Install**
**Step 2: Navigate to Integrations**
1. Log in to your Harmony dashboard
2. Go to **Settings** > **Integrations**
3. Find **GitHub** under **Developer Tools** and click **Connect**
**Step 3: Enter Credentials**
1. Enter your **Organization name**
2. Enter your **App ID** and **Client ID**
3. Upload your **Private key** file
4. Click **Connect**
#### What Harmony Syncs
**From GitHub:**
* Organization members and their roles
* Teams, memberships, and permissions
* Repository list, visibility, and access
* Seat and license usage
* User activity and last active dates
* Pending organization invitations
* GitHub plan and Copilot seat allocations
* Login trends from GitHub's audit log
* Billing information from GitHub's enhanced billing API
#### License and Usage Data
Once connected, Harmony automatically fetches and surfaces the following information from your GitHub account:
* **License type** - your organization's GitHub plan and Copilot seat allocations
* **Login trends** - user login activity sourced from GitHub's audit log
* **Cost data** - billing information pulled from GitHub's enhanced billing API
This gives you a clearer picture of your GitHub spend and adoption alongside your other tools, without any manual data entry.
#### 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
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
---
# 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.