GitHub

Trustle reads members, teams, repositories, and repository access from your GitHub organization. Trustle can add and remove team members and repository collaborators, invite people to the organization, and remove members from it.

Prerequisites

• The Owner role in the GitHub organization. Only an owner can install an app on the organization.
• The admin role in Trustle. Only a Trustle admin can complete the connection.
• An identity provider connected in Trustle, for example Okta or Microsoft Entra ID. Trustle hides SaaS Applications until one is connected.
• For reliable automatic user linking: SAML single sign-on or verified domains in GitHub. Without them, Trustle links only people whose email GitHub search can find. You link the others by hand. See Troubleshooting.
• For GitHub activity: GitHub Enterprise Cloud. Only Enterprise Cloud has the organization audit log.

Configure GitHub

Step 1: Sign in as an organization owner

1. In the browser you use for Trustle, sign in to GitHub with an account that has the Owner role in the organization.

The GitHub account that approves the install must be able to manage the installation. If it cannot, Trustle does not create the connection.

Step 2: Grant permissions

The app asks for a fixed set of permissions. The Trustle connect page lists them in these groups. GitHub shows the exact permissions on its install screen.

Permission	Required	What Trustle does with it
Organization Visibility	Yes	Imports members, teams, and repositories.
Team Management	Yes	Adds and removes team members and repository collaborators.
Access Control	Yes	Shows who has access to each repository, and through which team.
Audit & Compliance	Optional	Reads the organization audit log, with organization_administration:read. Needs GitHub Enterprise Cloud. Without it, Trustle shows no GitHub activity.

On the install screen, GitHub also asks which repositories the app can see:

Repository access	What Trustle sees
All repositories	Every repository and its collaborators.
Only select repositories	Only the repositories you select. Trustle cannot show or grant access to the others.

Connect in Trustle

1. In Trustle, go to Connections.
2. Under SaaS Applications, find GitHub and click Connect.
3. Click Install GitHub App. GitHub opens in a new tab.
4. In GitHub, select the organization. Select the repository access. Review the permissions. Click Install & Authorize.
5. GitHub returns you to Trustle, on Complete GitHub Connection. Sign in to Trustle if it asks.
6. Check that Trustle shows Ready to Connect. Click Allow Connection.
7. Trustle opens the Connections page, shows a checkmark next to GitHub, and starts the first sync.

Note

Two accounts must pass a check. The GitHub account that clicks Install & Authorize must be an owner of the organization. The Trustle account that clicks Allow Connection must be a Trustle admin.

Verify

1. On the Connections page, open the GitHub connection.
2. Wait for the first sync to finish. A large organization can take several minutes.
3. Check that the user count and the team count match the People and Teams pages of the organization in GitHub.
4. On the Users tab, check that GitHub accounts show the Trustle user they belong to.

If something is missing, see Troubleshooting.

Security notes

Note

• The connection has no token or key to store. GitHub issues the app’s credentials, and you control them in GitHub.
• Select Only select repositories if Trustle must not see some repositories. Trustle then cannot grant access to them.
• To remove Trustle’s access, go to the organization in GitHub → Settings → Third-party Access → GitHub Apps. Configure the Trustle app, then uninstall it.

Troubleshooting

The install does not finish

• Insufficient permissions: your Trustle account is not an admin. Ask a Trustle admin to start the install from Connections.
• Missing required parameters: you opened Complete GitHub Connection without the link from GitHub. Start again from Connections.
• An error after Allow Connection: the GitHub account that approved the install is not an owner of the organization. Sign in to GitHub as an owner and start again.

The sync finishes, but GitHub accounts are not linked to Trustle users

Trustle links a GitHub account to a Trustle user by email. Where it finds the email depends on your organization:

Your GitHub organization	Where Trustle finds the email
SAML single sign-on on the organization	The SAML identity of each member.
No SAML on the organization, with verified domains	The member’s email on a verified domain.
No SAML on the organization	A GitHub search for each Trustle user’s email. The search finds only accounts that show that email publicly.

To link a person by hand, open the GitHub connection. On the Users tab, link the GitHub account to the Trustle user.

A repository is missing

The app can see only the repositories you selected at install. In GitHub, go to Settings → Third-party Access → GitHub Apps. Configure the Trustle app and add the repository. Trustle shows it after the next sync.

GitHub activity is empty

The audit log needs GitHub Enterprise Cloud. On the Free and Team plans, GitHub refuses the request, and Trustle shows no activity. The rest of the sync still runs.

None of these fixes work

Email support@trustle.com. Include the error message, the connection name, and the GitHub organization name. Never send a secret, key, or token.