Programmatic access and integrations with GitHub Enterprise Cloud

GitHub Enterprise Cloud (GHEC) offers several methods for API and command line access, and it’s best practice to know the advantages, disadvantages, and limitations of each. If you intend to integrate other tools with GitHub or build automation, you will also need to extend and secure these programmatic access options using GitHub’s app platforms and webhooks.

We’ll hear from Philips and Figma how they used webhooks tohelped with automate onboarding and prevent policy abuseion, and from SoftwareTesting.ai on the advantages of building GitHub Apps.

In this guide, you will learn:

How to access the GitHub API and command line via personal access tokens (PATs) and SSH keys
The advantages of using GitHub Apps for automation and integrations that require repeated API access
How to secure your integrations, even with a mix of SaaS and self-hosted tooling
The best practice of using webhooks instead of polling for integrations

API and command line access

GitHub offers three primary methods for authorizing access to the API and command line on behalf of your users: Personal access tokens (PATs), SSH keys, and IP allow lists. Each method has unique qualities that make it more or less appropriate for certain scenarios, so let's learn more about each.

Personal Access Tokens (PATs)

PATs access GitHub resources on behalf of an individual user via the GitHub API or command line interface (CLI). To access resources on behalf of an organization, or for long-lived integrations, a GitHub App is a better fit because it can provide enterprise-level scalability and controls. We’ll explore this approach below.

PATs are always created, managed, and owned by the individual user. They can be granted scoped access to specific resources and types of permissions that the user themself has.

In enterprises and organizations where SAML is enabled or enforced, the user must authorize the PAT by completing a SAML single sign-on (SSO) authentication in the browser before it can access resources. SAML-authorized PATs can then be audited by enterprise or organization administrators, and their authorization can be revoked by administrators in the user interface or via API at any time. Without administrator intervention, authorized tokens will stay authorized until the user is removed from the organization, the PAT scopes are edited, or the token is regenerated or expires.

GitHub currently supports two types of PATs: fine-grained PATs and classic PATs. Fine-grained PATs provide enhanced security with additional functionality, such as required expiration dates and granular scopes of access. Classic PATs still exist to support legacy features and endpoints that are not yet ready for fine-grained PATs. We recommend that you use fine-grained PATs whenever possible to take advantage of the enhancements. Enterprise and organization owners can set policies to restrict the access of classic PATs to the enterprise or organizations owned by the enterprise.

SSH keys and certificate authorities

SSH keys are intended for secure individual access to the GitHub CLI. Because they are only used for the command line, the additional controls for scoping types of access to other resources that PATs require are not a consideration for SSH keys.

However, like PATs, SSH keys need to be SAML-authorized in enterprises and organizations where SAML is enabled or enforced by completing a SAML SSO authentication in the browser. Enterprise or organization administrators can audit SAML-authorized keys and revoke their authorization in the user interface or via API at any time. Without administrator intervention, authorized keys will stay authorized until the user is removed from the organization, or the key is otherwise removed or invalidated.

Users can set up SSH keys by generating a new SSH keypair and adding the public key to their GitHub account. However, it is possible for an enterprise or organization to provision and manage SSH keys centrally by configuring an SSH certificate authority (CA). Once an SSH CA is set up, the enterprise or organization may also optionally require only SSH keys to be used for programmatic access, which may be of interest if your organization would like to avoid managing PATs for command line access entirely. CA-signed certificates do not need to be SAML-authorized like individually managed SSH keys.

A note about APIs and IP allow lists

Integrations with GitHub may need to call GitHub’s APIs in order to properly function. If you have configured an IP allow list for your enterprise or organization, the IP ranges of any integrations installed must be included. When setting up the IP allow list, you can optionally allow installed integrations to update it. If the author of the integration provides an allow list for their application, it will automatically be added to your allow list. If not, the allow list will need to be managed manually.

IP allow lists and Conditional Access Policies for Enterprise Managed Users (EMUs)

If you are using EMUs with OIDC SSO, GitHub can be configured to use your IdP's conditional access policy (CAP) IP conditions to validate user interactions. You will also need to ensure that you have added the IP ranges of all applications and integrations to your IdP’s CAP.

IP allow lists, CAP, and Actions runner access

GitHub provides hosted Actions runners that you can use to perform your builds, deployments, static analysis scans, and any other desired automations. If you are using GitHub-hosted runners with four or more vCPUs, you can receive a static IP address for your runners. This IP address is unique to your enterprise and can be added to your IP allow list or IdP CAP to grant the runners access to your code.

Apps

If you plan to use the GitHub API in a repeated manner, it is a best practice to use an app to interact with the API instead of accessing the API directly. In particular, we recommend the GitHub App framework over the OAuth framework for app integrations. GitHub Apps offer many advantages over OAuth apps and PAT-based API access, including:

Enhanced security features, like fine-grained permissions, choice over repository access, and short-lived tokens
The ability to act independently of or on behalf of a user
Scalable rate limits
Built-in webhooks

GitHub also supports a robust community of pre-existing integrations using both GitHub App and OAuth interfaces. If you’re looking to integrate with other tools in your development toolchain, it’s likely there’s already an app-based GitHub integration out there for you to install and start using!

Administrators control which apps are installed for your organizations, and which repositories and permissions they are granted. You can also set policies to completely restrict installations or require administrator approval for app installations. Administrators can also delegate app-specific administrative permissions to users to help manage GitHub Apps.

Apps can only be installed at the organization (or individual user) level.

There’s a lot that we can do, as developers, to improve our workflows and address the inefficiencies in how we build and ship code. GitHub provides a robust set of APIs and SDKs in Octokit that makes it super easy for us to build tooling that makes our lives better. From there, it’s simple to publish it on GitHub Marketplace to allow other developers to use it as well, that way it benefits the broader developer community.

Justin Trugman // Founder // SoftwareTesting.ai

Webhooks

Webhooks provide a way for notifications to be delivered to an external web server whenever certain events occur on GitHub, instead of polling the API on a schedule to check if certain events have occurred. They deliver a JSON payload securely over HTTPS POST. Integrations create webhooks, select the events they want for notification, provide a publicly-routable endpoint where GitHub can deliver the payload, and optionally provide a secret value that GitHub can use to cryptographically sign the payload. Delivering webhooks to on-premises resources As part of your GHEC deployment, you may need webhooks to send notifications to applications hosted behind your firewall that you wish to integrate with GitHub.

With proper network configuration, GHEC can notify these systems by implementing a form of reverse proxy, which includes:

A publicly routable fully-qualified domain name (FQDN) to which GitHub can send the HTTPS post URL rewrite and port forwarding to the appropriate application

This pattern can be implemented using off-the shelf components from vendors like ngrok, configuring existing web servers like NGINX, or a commercial product such as a WAF or API gateway.

We use webhooks to monitor GitHub events for when a new user joins an organization, that way we can automatically create and assign them an issue to help with their onboarding.

Niek Palm // Principal Software Engineer // Philips

Securing webhook deliveries to on-premises resources

When implementing a reverse proxy to handle webhook delivery, GitHub recommends the following practices:

Only allow inbound HTTPS traffic on port 443 to your FQDN
Only allow traffic from the IP ranges advertised in the hooks section of https://api.github.com/meta
Terminate SSL at your FQDN and inspect the JSON payload for the presence of well-formatted JSON
Ensure that the solution(s) you are integrating with support and use webhook signatures

Our change control policy is designed to improve efficiency. We require plus-one approvals on pull requests to merge, but we don’t dismiss stale approvals. Our approach is that the reviewer is approving the spirit, not the bytes, of the pull request. So when an approval has a few simple comments on style, for example, we generally allow the submitter to address the comments and merge the pull request without having to get a second approval.

At the same time, we wanted to make sure this policy wasn’t being abused, so we built an automation using an organization-level webhook that feeds into a custom automation we built on AWS Lambda which then feeds into our security information and event management (SIEM) platform. This allows us to flag cases where we think this policy is being abused—pull requests that were merged with significant post-approval changes—and alert us so we can address them.

Tommy MacWilliam // Engineering Manager for Infrastructure // Figma

Polling

If you are writing an integration or automation against the GitHub API, you should avoid API polling. To ensure the performance and reliability of our system for all, GitHub enforces a hard rate limit on API activity for individuals and a higher limit for applications. Regularly polling our API, especially in larger organizations, will hit the rate limit.

Rather than polling our API on a scheduled basis, you should use webhooks to be notified of events on GitHub instead. The integration will receive any webhook events to which it is subscribed and can then make an authenticated request to GitHub should any action need to be taken.

Up next: Access, capture, and consume your audit logs

As we wrap up this module, there’s one final topic to cover: Audit logs. Whether for regulatory compliance or troubleshooting, audit logs provide a paper trail for various actions within your enterprise, and your initial onboarding won’t be complete until you understand what they offer and how to access them.