GitHub app permissions
This page is the permission reference for the GitHub integration. It lists every permission the Coralogix GitHub app requests, what each one is used for, and which event types each permission makes available.
Review it before you install the app, especially if your organization requires an owner to approve GitHub Apps: the approver sees the permission list without the context of what Coralogix does with it, and this page is the explanation to hand them.
Principles
- Read-only. Every permission is requested at read level. The app cannot push commits, open or merge pull requests, change settings, or write anything to your repositories or organization.
- One app, three capabilities. The app is shared by the three capabilities of the integration: reading sources, collecting audit logs, and receiving events. GitHub grants permissions to the app as a whole, so the installation asks for the union of what the three need, whether or not you enable all three.
- Scoped by your installation. Repository permissions apply only to the repositories you select when installing the app. Organization permissions apply to the organization you install it on.
- Changing permissions requires re-approval. GitHub asks every organization that has the app installed to approve a new permission before it takes effect. Coralogix therefore requests the full set up front rather than adding permissions later, so that a new capability does not force a re-approval round across every customer.
Always requested
| GitHub permission | Level | Used for |
|---|---|---|
| Metadata | Read | Mandatory for every GitHub App. Lets Coralogix resolve which organizations and repositories the installation covers. |
Coralogix also lists the installations of the app, which needs no permission of its own.
Coralogix calls GitHub as the person who authorized the connection, using a token GitHub issues for that person and refreshes on its own. The effective access is therefore the intersection of two things: what the app is permitted to do, and what the authorizing user can already do in GitHub. A permission granted to the app never widens what that person can reach.
Read sources
| GitHub permission | Level | Used for |
|---|---|---|
| Contents | Read | Read file contents and browse the repository tree in the repositories the installation covers. |
| Metadata | Read | List the repositories the installation can access. |
Read audit logs
| GitHub permission | Level | Used for |
|---|---|---|
| Organization: Administration | Read | Call the GitHub organization audit-log API (GET /orgs/{org}/audit-log). This is the only way to read the audit log of an organization, and GitHub gates it behind organization administration. |
Two GitHub-side conditions apply on top of the permission:
- The person who authorizes the connection must be an owner of the organization. GitHub rejects the audit-log endpoint for non-owners even when the app has the permission.
- The organization must be on GitHub Enterprise Cloud. The audit-log API is not available to Free, Pro, or Team plans.
Enterprise-wide audit logs (GET /enterprises/{enterprise}/audit-log) need the separate "Enterprise administration" permission and are not supported by this integration. Collect the audit log per organization instead.
GitHub events
Event delivery is where most of the permission list comes from. GitHub only delivers an event to an app that holds the permission covering that event, so the set of permissions the app requests defines the set of event types you can choose from.
The table below is the full map. Every event type selectable in the integration appears exactly once, under the permission that unlocks it.
| GitHub permission | Level | Event types unlocked |
|---|---|---|
| Actions | Read | workflow_job, workflow_run |
| Administration (repository) | Read | branch_protection_configuration, branch_protection_rule, repository_ruleset, security_and_analysis |
| Administration (organization) | Read | org_block, repository_ruleset |
| Checks | Read | check_run, check_suite |
| Code scanning alerts | Read | code_scanning_alert |
| Commit statuses | Read | status |
| Contents | Read | commit_comment, create, delete, fork, gollum, push, release, repository_dispatch, workflow_dispatch |
| Custom properties (organization) | Read | custom_property, custom_property_values |
| Dependabot alerts | Read | dependabot_alert |
| Deployments | Read | deploy_key, deployment, deployment_protection_rule, deployment_review, deployment_status |
| Discussions | Read | discussion, discussion_comment |
| Issues | Read | issue_comment, issue_dependencies, issues, milestone, sub_issues |
| Members (organization) | Read | member, membership, organization, team, team_add |
| Merge queues | Read | merge_group |
| Metadata | Read | label, public, repository, star, watch |
| Packages | Read | registry_package |
| Pages | Read | page_build |
| Personal access token requests (organization) | Read | personal_access_token_request |
| Projects (repository and organization) | Read | project, project_card, project_column |
| Pull requests | Read | milestone, pull_request, pull_request_review, pull_request_review_comment, pull_request_review_thread |
| Repository security advisories | Read | repository_advisory |
| Secret scanning alerts | Read | secret_scanning_alert, secret_scanning_alert_location, secret_scanning_scan |
milestone appears twice on purpose: GitHub delivers it to an app holding either Issues or Pull requests.
Events that need no permission
GitHub sends these to every app regardless of the permissions granted, and they cannot be unsubscribed from. They describe the app installation itself rather than activity in your repositories, and Coralogix uses them to keep track of where the app is installed.
installation, installation_repositories, installation_target, github_app_authorization, ping
Events GitHub Apps cannot receive
These GitHub event types exist but are not deliverable to a GitHub App, so no permission makes them available: marketplace_purchase, package (superseded by registry_package), repository_import, repository_vulnerability_alert (superseded by dependabot_alert), security_advisory, sponsorship, and the projects_v2 family (projects_v2, projects_v2_item, projects_v2_status_update), which GitHub delivers only to organization-level webhooks.
Permissions your approver may question
Every permission is read-only, but a few read more than repository content, and an approver is likely to ask about them. Each is needed by a specific capability, and none of them is used for anything else.
| GitHub permission | Why the app asks for it | What you lose without it |
|---|---|---|
| Organization: Administration | The organization audit-log API is gated behind it. | The Read audit logs capability, plus the org_block, branch_protection_*, repository_ruleset, and security_and_analysis events. |
| Members (organization) | Membership and team events describe who gained or lost access. | Membership, team, and organization events. |
| Personal access token requests | Reports when a member requests a fine-grained token against the organization. | The personal_access_token_request event. |
| Secret scanning alerts, Code scanning alerts, Dependabot alerts | Security alerts are among the highest-value events to have in Coralogix next to the rest of your telemetry. Read access exposes alert metadata, not the secret itself. | The corresponding alert events. |
If your organization declines one of these, the rest of the integration still works. Only the capability and events listed in the last column stop being available.
Related resources
- GitHub integration
- GitHub webhook events and payloads in the GitHub documentation
- Choosing permissions for a GitHub App in the GitHub documentation