GitHub

Connecting to Github

GitHub lets you control on an organization-by-organization which external applications have access to your data.

When you connect from Trelica to GitHub you will have to consent to give Trelica access for each organization.

You may receive this message when connecting Trelica to GitHub:

Although you appear to have the correct authorization credentials, the 'acme-inc' organization has enabled OAuth App access restrictions, meaning that data access to third-parties is limited. For more information on these restrictions, including how to enable this app, visit https://docs.github.com/articles/restricting-access-to-your-organization-s-data/

This means that an owner must grant access to the Trelica application, or if you are the owner, you may need to go and manage the consent settings for Trelica.

To approve consent requests made by another user:

1. Click on your avatar icon at the top-right and choose Your organizations.
2. Next to the organization, click Settings.
3. In the Third-party Access section of the sidebar, click OAuth application policy.
4. Next to the Trelica application, click Review.
5. Review the information about Trelica and click Grant access.

To see and alter the choices you made:

1. Click on your avatar icon at the top-right and choose Your organizations.
2. On the left-hand menu, under Integrations, choose Applications.
3. Click on the Authorized OAuth Apps tab.
4. Click on the Trelica icon.
5. Under Organization access click Grant next to relevant organizations.

Once you have changed settings you may need to reconnect or refresh your GitHub integration in Trelica.

If you are still having problems

If you're still experiencing problems we recommend revoking accesss in GitHub, reconnecting from Trelica, and ensuring you grant access to the correct organizations:

1. Click on your profile icon at the top-right, choose Settings > and then in the Integrations section click Applications.
2. Under Authorized OAuth Apps click on the ... icon next to the Trelica app and choose Revoke.
   
3. Now go back to Trelica, and reconnect to GitHub. Be sure to grant access to the relevant organizations by clicking Grant before continuing to Authorize. 

GitHub and user identities

The Trelica integration with GitHub Cloud can connect with Free, Team or Enterprise plans. If you are using GitHub Enterprise Server then there is a separate integration.

GitHub Cloud is designed to let people collaborate, and from an organizational perspective you may have outside collaborators as well as employees. A GitHub user account is therefore typically portable, in the sense that the account belongs to the individual. You add someone as a member of your organization when they start working for you, and remove them from your organization when they leave, but they take their account with them.

This behaviour means that email addresses belong to the account and may well be personal addresses and not work ones. GitHub ensures privacy by default by not exposing email addresses unless a user explicitly chooses to make it public.

This is important for Trelica because Trelica tries to tie user accounts back to individuals in your organization based on email address.

If you have SAML2 SSO configured

If you are using GitHub Enterprise you may well be using SAML2 SSO. SAML2 SSO can be enabled at either an Enterprise or at individual Organization level.

If you use SAML2 SSO, then a user will login with their corporate account through your Identity Provider. The first time they do this, they effectively link their personal GitHub account with their corporate identity.

Trelica uses this connection information to link GitHub account usage details to a Trelica identity.

Organizations without SAML2 SSO

If you aren't using SAML2 SSO, Trelica will try to read email addresses, either where the user has expicitly made it public (which is atypical), or if their GitHub email address is from a verified domain.

This works well if you encourage employees to set-up new GitHub accounts for work purposes, and they assign a work email address, even if you don't use SAML2 SSO.

A verified domain is a domain that a GitHub Enterprise or Organization owner has confirmed belongs to your organization. Ideally domains are verified at Enterprise level, but you can also verify domains for individual organizations.

Whilst you can verify domains on any GitHub account plan, GitHub restricts API access to emails from verified domains to Enterprise plans only.

What if I'm on the Free or Team plan?

If Trelica can't read an email address via SAML2 or a verified domain, then you will see the GitHub login for the individual. These can sometimes be rather cryptic, but you can manually map these logins back to employees or contractors in Trelica.

Optimization

Last login date

We read last login data from the GitHub audit log. API access to this is only available on a GitHub Enterprise plan.

Billing policy

GitHub charging varies between Enterprise and Team plans.

Invited users are billable, but the invitations expire after 7 days. Be aware that this does not apply to SCIM invited users who remain billable until you delete the invitation.

Copilot Usage

Copilot is an extra cost option. It can be assigned at team or individual level. Trelica reads in information about Copilot data which can be used as part of optimization workflows.

Accessing Copilot data requires acceptance of an additional scope, if you select this option when connecting to GitHub from Trelica.

Advanced Security Usage

Advanced Security is a billable Enterprise plan option. Trelica shows you the number of repositories to which a user is contributing which have Advanced Security enabled, and the date when the user last pushed to them.

GitHub Enterprise and SCIM

GitHub Cloud provides a SCIM interface for inviting new members or deactivating them. Currently this only works at Organizational level, and a pre-requisite is that SAML2 SSO is also at Organization level. GitHub have an early adopter version of SCIM at Enterprise level but this is not available for general use.

GitHub lets you synchronize SCIM groups to GitHub teams. This only works with Okta and Microsoft Entra ID.

Setting up the integration in GitHub Enterprise Server

If your organization uses GitHub Enterprise Cloud the following steps can be ignored.

If your organization users a self-hosted GitHub Enterprise Server platform, then you will need to configure an OAuth application as described below:

Click on your profile icon, and choose User settings:

Then navigate to Developer settings > OAuth Apps and click Register a new application.

Input an Application name and Homepage URL followed by an optional Application description. Most importantly input an Authorization callback URL of https://app.trelica.com/IntegrationsApi/Integrations/GitHubServer/AuthCallback.

Click Register application to create the OAuth application.

On the following page, click Generate a new client secret to generate the required credentials to connect.

Copy the Client secret as it will be required alongside the Client ID when connecting the integration in Trelica.