# Github

Connecting GitHub gives SureCloud read access to your GitHub organisation's repositories, members, teams, and security settings. SureCloud monitors branch protection rules to verify that pull request reviews and status checks are enforced, audits organisation membership and outside collaborator access, checks whether two-factor authentication is required across the organisation, and collects Dependabot and secret scanning alerts. This provides continuous evidence that your source code management environment is governed and that code security controls are active.

{% hint style="info" %}
SureCloud connects to GitHub using OAuth 2.0. No credentials are stored — access is maintained via a refresh token that SureCloud rotates automatically. For self-hosted GitHub Enterprise Server, a Personal Access Token is used instead.
{% endhint %}

## Authentication and setup

{% tabs %}
{% tab title="GitHub Cloud (OAuth 2.0)" %}
{% stepper %}
{% step %}

#### Initiate the connection in SureCloud

In SureCloud, navigate to **Integrations → GitHub → Connect**. SureCloud redirects you to GitHub's OAuth authorisation page.
{% endstep %}

{% step %}

#### Authorise SureCloud in GitHub

Review the requested permissions and click **Authorise SureCloud**. The OAuth app is pre-registered by SureCloud — you do not need to create an app in GitHub.

SureCloud requests the following OAuth scopes:

| Scope              | Purpose                                                                    |
| ------------------ | -------------------------------------------------------------------------- |
| `read:org`         | Read organisation membership, teams, and outside collaborators             |
| `read:repo_hook`   | Read webhook configurations                                                |
| `repo` (read-only) | Read repository metadata, branch protection rules, and collaborator access |
| `read:user`        | Read the authorising user's profile                                        |
| `read:audit_log`   | Read the organisation audit log                                            |
| `security_events`  | Read Dependabot, code scanning, and secret scanning alerts                 |

{% hint style="warning" %}
The authorising account must be a **GitHub organisation owner** to grant `read:org` and `read:audit_log` scopes on behalf of the organisation. Member accounts cannot grant these scopes organisation-wide.
{% endhint %}
{% endstep %}

{% step %}

#### Select organisations to monitor

After authorisation, return to SureCloud and select the GitHub organisations you want to monitor. If your account is a member of multiple organisations, each can be added as a separate monitored scope.

Click **Save Connection**.
{% endstep %}
{% endstepper %}
{% endtab %}
{% endtabs %}

## Endpoints

| API Call                                                 | Use Case                                                                                     |
| -------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `GET /orgs/{org}`                                        | Read organisation-level settings including 2FA requirement and default repository visibility |
| `GET /orgs/{org}/members`                                | Enumerate all organisation members and their roles                                           |
| `GET /orgs/{org}/outside_collaborators`                  | List outside collaborators; detect external access to private repositories                   |
| `GET /orgs/{org}/teams`                                  | Enumerate teams and their repository permission assignments                                  |
| `GET /orgs/{org}/repos`                                  | List all repositories in the organisation                                                    |
| `GET /repos/{owner}/{repo}/branches/{branch}/protection` | Read branch protection rules for the default branch of each repository                       |
| `GET /repos/{owner}/{repo}/collaborators`                | Enumerate per-repository collaborators and their permission levels                           |
| `GET /orgs/{org}/audit-log`                              | Retrieve organisation audit log events                                                       |
| `GET /repos/{owner}/{repo}/vulnerability-alerts`         | Check whether Dependabot vulnerability alerts are enabled                                    |
| `GET /repos/{owner}/{repo}/secret-scanning/alerts`       | Collect active secret scanning alerts per repository                                         |
| `GET /orgs/{org}/dependabot/alerts`                      | Aggregate Dependabot alerts across all repositories in the organisation                      |

## Pagination

The GitHub REST API uses cursor-based pagination via `Link` headers. When a response is paginated, the `Link` response header includes a `rel="next"` URL. SureCloud follows this URL until no `rel="next"` link is present.

```
Link: <https://api.github.com/orgs/my-org/repos?page=2>; rel="next",
      <https://api.github.com/orgs/my-org/repos?page=8>; rel="last"
```

For the audit log endpoint, GitHub uses cursor-based pagination via the `after` query parameter rather than page numbers. SureCloud uses the cursor value from the `Link` header to advance through audit log pages.

{% hint style="info" %}
GitHub's REST API rate limit is 5,000 requests per hour for authenticated OAuth apps. SureCloud monitors rate limit consumption via the `X-RateLimit-Remaining` response header and spaces requests to avoid hitting the limit during collection runs.
{% endhint %}

## Required permissions

For GitHub Cloud (OAuth), the scopes listed in the authentication section are all that is required. The authorising user must be an **organisation owner**.

For GitHub Enterprise Server (Personal Access Token), the token must be generated by an **organisation owner** account for `read:org` and `read:audit_log` to return organisation-wide data.

## Troubleshooting

<details>

<summary>Branch protection rules are returning as empty for repositories that have protection configured</summary>

The `GET /repos/{owner}/{repo}/branches/{branch}/protection` endpoint requires the authenticated account to have at least read access to the repository. For private repositories, the OAuth app must have `repo` scope (not just `public_repo`).

Confirm the SureCloud OAuth app was authorised with the `repo` scope (not `public_repo`). If access was granted with `public_repo` only, re-connect the integration via **SureCloud → Integrations → GitHub → Reconnect** to re-authorise with the correct scopes.

</details>

<details>

<summary>The organisation audit log is returning empty or access is denied</summary>

The `read:audit_log` scope can only be granted by an **organisation owner**. If the account that authorised the OAuth connection is a member (not an owner), audit log access will be denied.

Re-connect the integration using an organisation owner account, or ask an owner to authorise the connection from their account in **SureCloud → Integrations → GitHub → Reconnect**.

</details>

<details>

<summary>Secret scanning alerts are not appearing for some repositories</summary>

Secret scanning must be enabled at the repository or organisation level. For GitHub Advanced Security (GHAS) features, the repositories must have GHAS licences assigned.

In **GitHub → Organisation → Settings → Code security and analysis**, confirm **Secret scanning** is enabled. For individual repositories, check **Repository → Settings → Security & analysis**.

</details>

<details>

<summary>Outside collaborators are missing from SureCloud</summary>

The `GET /orgs/{org}/outside_collaborators` endpoint returns only collaborators who have been added directly to a repository without being organisation members. Confirm the SureCloud OAuth connection was authorised by an **organisation owner**, as members cannot list outside collaborators org-wide.

</details>

<a href="https://docs.github.com/en/developers/apps/building-oauth-apps/scopes-for-oauth-apps" class="button secondary">GitHub OAuth scopes reference</a> <a href="https://docs.github.com/en/rest/branches/branch-protection" class="button secondary">GitHub branch protection API docs</a>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/github.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.