Search documentation

Find a documentation page by title, topic or keyword.

GitHub

On this page

The GitHub connector records organisation membership, team and repository access, branch protection changes and code-security alerts. Every permission it asks for is read-only.

Before you start#

You need to be able to install an app on your GitHub organisation, which normally means being an organisation owner. You register nothing: Governax operates its own GitHub App and you are installing it.

Decide beforehand whether to grant all repositories or a subset. All repositories is the usual choice, because a repository created later is covered automatically; with a subset, new repositories are invisible until you add them.

Installing the app#

  1. Open the entity's Integrations page and choose GitHub

    Confirm you are on the entity that should own this organisation.

  2. Pick the organisation

    GitHub asks which account to install on. Choose the organisation, not your personal account.

  3. Choose repository scope

    All repositories, or a selected list.

  4. Install and return

    You are returned to Governax and the connection is saved. If the app was already installed, GitHub may send you through an extra confirmation step; this is expected.

Permissions requested#

Repository permissions, all read-only
PermissionWhy it is needed
MetadataRequired by GitHub for any app
AdministrationRepository lifecycle, visibility changes, branch protection
ContentsPush metadata only: which branch, force-push, branch deletion
Pull requestsMerges and review approvals
Secret scanning alertsSecret exposure alerts
Code scanning alertsCode security alerts
Dependabot alertsDependency vulnerability alerts
Organisation permissions, all read-only
PermissionWhy it is needed
MembersOrganisation and team membership changes
AdministrationOrganisation-level settings changes
Personal access token requestsPAT approval requests and their outcomes

The connect-time baseline#

At connect, Governax walks the organisation's current members and records access.baseline_observed for anyone not previously seen. Where a member's role has changed since Governax last looked, it records access.role_changed with reconciled: true.

Events captured#

GitHub event types by area
AreaEvent types
Organisation membershipaccess.member_added, access.member_removed, access.member_invited, access.org_user_blocked, access.org_user_unblocked
Teamsaccess.team_member_added, access.team_member_removed, resource.team_created, resource.team_deleted, resource.team_edited, access.team_repo_access_added, access.team_repo_access_removed
Repository accessaccess.repo_collaborator_added, access.repo_collaborator_removed, access.repo_permission_changed, access.repo_made_public, access.repo_made_private, access.deploy_key_added, access.deploy_key_removed
Repository lifecycleresource.repo_created, resource.repo_deleted, resource.repo_archived, resource.repo_unarchived, resource.repo_renamed, resource.repo_transferred
Guardrailsresource.branch_protection_created, resource.branch_protection_edited, resource.branch_protection_deleted, the two branch_protection_config_* events, and the three resource.ruleset_* events
Code movementresource.branch_deleted, resource.branch_force_pushed, resource.pull_request_merged
Review decisionsdecision.pull_request_approved, decision.pull_request_review_dismissed
Code securitysecurity.secret_scanning_alert, security.code_scanning_alert, security.dependabot_alert, security.features_changed
Access tokensaccess.pat_request_created, access.pat_request_approved, access.pat_request_denied, access.pat_request_cancelled
Connector healthintegration.disconnected_remotely, integration.suspended, integration.unsuspended, integration.permissions_changed, integration.repos_added, integration.repos_removed

Not captured: ordinary pushes (only force-pushes and branch deletions are recorded), pull request opens, updates and comments (only merges and review decisions), and cosmetic repository edits such as description or topic changes.

Why GitHub events have no email addresses#

Disconnecting#

Disconnecting uninstalls the app from your organisation, which is a real uninstall rather than just a local flag. Uninstalling from GitHub directly has the same effect from the other direction: Governax records integration.disconnected_remotely and marks the connection dead. Suspending the app rather than uninstalling it records integration.suspended.

Events already recorded remain in the ledger either way.

Troubleshooting#

Common GitHub connection problems
SymptomCause and fix
Install unauthorisedThe ownership check failed. Run the install from the Governax Integrations page rather than from GitHub's own app directory.
Already connectedThis organisation is bound to another entity or organisation. Disconnect it there first.
New repositories not appearingThe installation is scoped to selected repositories. Add them in the app's settings on GitHub, or switch to all repositories.
Owner promotion never appearedGitHub emits no webhook for it. Reconnect to pick it up through the baseline comparison.

General connector behaviour is covered in Connecting a tool.