# GitHub

> Connect GitHub to Tidal Control through the Tidal Control GitHub app, so compliance tests read your repositories, branch protection and access settings.

Source: https://tidalcontrol.com/docs/integrations/github

The GitHub integration enables Tidal Control to automatically execute compliance tests on your GitHub environment via the Tidal Control GitHub app.

## Requirements

- Super User role in Tidal Control
- GitHub organisation admin rights
- Access to GitHub organisation where monitoring is desired

## Configuration step-by-step plan

We'll install the **Tidal Control GitHub app** in your GitHub organisation(s). This app gets read-only access to repository configurations for security compliance monitoring.

**Configuration steps:**
1. **Start Tidal integration**
2. **GitHub authentication**
3. **Configure repository access**
4. **Complete app installation**
5. **Additional organisations**

## Required permissions

When you install the Tidal Control GitHub app, GitHub shows which permissions the app requests. All access is **read-only**. Tidal Control never writes, modifies, or deletes anything in your GitHub environment.

### Currently active

<table>
<thead>
<tr><th>Permission</th><th>Why we need it</th></tr>
</thead>
<tbody>
<tr><td><strong>Administration</strong></td><td>Reads branch protection rules and rulesets. Used to verify: is force push to the default branch disabled, is a PR review required before merging, and is code owner approval required.</td></tr>
<tr><td><strong>Pull requests</strong></td><td>Verifies that recently merged pull requests were approved before merging.</td></tr>
<tr><td><strong>Metadata</strong></td><td>Basic repository information: name, visibility (public/private), fork status, and default branch name.</td></tr>
</tbody>
</table>

### Present for future tests

The following permissions are included in the app but not yet actively used. They are reserved for additional compliance checks we plan to build:

<table>
<thead>
<tr><th>Permission</th><th>Planned use</th></tr>
</thead>
<tbody>
<tr><td><strong>Code</strong></td><td>Check whether a CODEOWNERS file is present and correctly configured, or whether a SECURITY.md (responsible disclosure policy) exists. We read only metadata files, not your business logic or intellectual property.</td></tr>
<tr><td><strong>Dependabot alerts</strong></td><td>Verify whether Dependabot is active and whether there are open critical vulnerabilities in dependencies.</td></tr>
<tr><td><strong>Secret scanning alerts</strong></td><td>Check whether secret scanning is enabled and whether there are open reports of leaked credentials.</td></tr>
<tr><td><strong>Checks</strong></td><td>Verify whether mandatory CI checks are configured as a condition for merging pull requests.</td></tr>
<tr><td><strong>Security events, repository advisories, deployments, issues</strong></td><td>Reserved for future compliance checks.</td></tr>
</tbody>
</table>

> **info:**

**Prefer limited access?** You can restrict the app to specific repositories instead of your entire organisation. Choose **"Selected repositories"** in step 3.

## Step 1: Start Tidal integration

- Go to **Settings → Integrations** in Tidal Control
- Click the **plus icon** next to GitHub
- Click **"Click here to get started"**
- You'll be automatically **redirected to GitHub**

## Step 2: GitHub authentication

- Enter your **GitHub login credentials**
- Click **"Sign in"** 
- Select the **organisation** where you want to install the app
- If app already installed: click **"Configure"** for settings

## Step 3: Configure repository access

- Choose access level:
  - **All repositories** - Complete organisation monitoring
  - **Selected repositories** - Selective compliance monitoring
- Select desired repositories if specific chosen

## Step 4: Complete app installation

- Review the **permissions** that Tidal Control requests
- Click **"Install"** for direct installation
- Or click **"Request"** if organisation approval required
- Wait for **approval** from organisation owner (if applicable)

## Step 5: Additional organisations

- Repeat **steps 1-4** for each additional organisation
- Each organisation needs **own app installation**
- Configure **per organisation** which repositories are monitored

## Verification

The integration is working when all of the following are true:

- **Settings → Integrations** shows GitHub under **Configured Integrations**
- **Test refresh** delivers repository data without (permission) errors

## Troubleshooting

If the integration does not connect, check the following:

- Verify GitHub app installation in organisation settings
- Check repository permissions for Tidal Control app
- Ask if organisation admin has approved the app
- Verify there are no conflicting security policies in GitHub

### Still can't figure it out?

Send an email to support@tidalcontrol.com, and we'll get back to you as soon as possible.

> **info:**

**Gathering support info:** Note which browser you're using, exact error messages, which steps you've already tried, and screenshots of the problem. This significantly speeds up the solution.