Connecting GitHub¶
Mayo ASPM connects to your GitHub repositories through a GitHub App. This is the most secure integration model GitHub offers — it uses short-lived installation tokens, requires explicit repository selection, and can be revoked at any time from your GitHub settings.
This page covers installation, repository selection, permissions, and what happens after you connect.
Before you begin¶
| Requirement | Details |
|---|---|
| GitHub account | Personal account or organization. You need owner or admin permission on the GitHub org to install apps. |
| Mayo ASPM organization | You must have already created a Mayo ASPM organization. See Account Setup. |
| Role in Mayo ASPM | You need the Owner or Admin role in your Mayo ASPM organization to install integrations. |
Step 1: Start the GitHub connection¶
- In the Mayo ASPM dashboard, navigate to Settings > Integrations.
- Find the GitHub card and click Connect.
- You are redirected to GitHub to authorize the Mayo ASPM GitHub App.
You can also start from the Assets page
If you navigate to Assets and click Add Repository, you will be prompted to connect GitHub if no integration exists yet.
Step 2: Choose an installation target¶
GitHub asks you where to install the app:
- Your personal account — installs on your personal repositories.
- An organization you administer — installs on the organization's repositories.
Select the appropriate target and click Install.
Step 3: Select repositories¶
You have two options:
| Option | When to use |
|---|---|
| All repositories | You want Mayo ASPM to monitor every current and future repository in the account/org. Good for small orgs or orgs that want comprehensive coverage. |
| Only select repositories | You want to control exactly which repositories Mayo ASPM can access. Good for large orgs or when you want to start with a subset. |
You can change this later
Repository selection is not permanent. You can add or remove repositories at any time from your GitHub settings: GitHub > Settings > Applications > Mayo ASPM > Configure.
Recommended approach¶
For most teams, we recommend starting with select repositories and choosing 3 to 5 repositories. This lets you evaluate the platform without granting broad access. You can expand access once you are comfortable.
Step 4: Review and approve permissions¶
Before completing installation, GitHub shows you the permissions the Mayo ASPM app requests. Here is what each permission is for and why it is necessary:
Repository permissions¶
| Permission | Access level | Why Mayo ASPM needs it |
|---|---|---|
| Contents | Read-only | To clone and scan your source code. Without this, scanning cannot work. |
| Metadata | Read-only | To list repositories, branches, and basic repo information. Required by all GitHub Apps. |
| Pull requests | Read & write | To post scan-result comments on pull requests and update PR check statuses. Required for PR scanning. |
| Checks | Read & write | To create check runs on pull requests showing pass/fail status. Allows Mayo ASPM to block merges when policy dictates. |
| Webhooks | Read-only | To receive real-time notifications when pull requests are opened or updated, triggering automatic PR scans. |
Organization permissions¶
| Permission | Access level | Why Mayo ASPM needs it |
|---|---|---|
| Members | Read-only | To display organization member information for ownership assignment in policies. |
Mayo ASPM never writes to your code
Despite having read access to repository contents, Mayo ASPM never pushes commits, modifies files, or changes branches. The write permissions are limited to pull-request comments and check statuses. Your code is read-only from our perspective.
What about private key security?¶
The GitHub App uses a private key to authenticate. This key is stored encrypted on Mayo ASPM's infrastructure and is never exposed to users, logged, or transmitted outside of the GitHub API authentication flow. Tokens generated from the key are short-lived (1 hour) and scoped to the repositories you selected.
What happens after installation¶
Once you approve the installation, several things happen automatically:
1. Repositories sync as assets¶
Mayo ASPM pulls the list of repositories you granted access to and creates an asset for each one. This typically takes 5 to 15 seconds.
You can see your repositories on the Assets page immediately after installation completes.
2. A project is auto-created¶
For each newly synced repository, Mayo ASPM creates a project with the same name. Projects are organizational containers that group assets and their findings. You can customize or merge projects later.
3. Branch information is loaded¶
Mayo ASPM reads your repository's branches so you can choose which branch to scan (default branch is pre-selected).
4. Webhook is registered¶
A webhook is registered on each selected repository so that Mayo ASPM can receive pull-request events in real time. This is what powers PR scanning.
Repositories you selected
│
▼
Assets created in Mayo ASPM
│
├──> Project auto-created (one per repo)
├──> Branches loaded
└──> Webhook registered (for PR scanning)
Verifying the connection¶
After installation, verify everything is working:
- Navigate to Assets in the Mayo ASPM dashboard.
- Confirm your repositories appear in the list.
- Click any repository — you should see its branches, language breakdown, and an empty findings list (no scans yet).
Missing a repository?
If a repository does not appear, it was likely not selected during installation. Go to GitHub > Settings > Applications > Mayo ASPM > Configure and add the missing repository. It will sync within seconds.
Managing the connection¶
Adding more repositories¶
- Go to GitHub > Settings > Applications > Mayo ASPM > Configure.
- Under Repository access, add the repositories you want.
- Click Save.
- New assets appear in Mayo ASPM within seconds.
Removing repositories¶
- Go to GitHub > Settings > Applications > Mayo ASPM > Configure.
- Remove repositories from the access list.
- Click Save.
Removing a repository does not delete findings
When you remove repository access, the asset and its existing findings are retained in Mayo ASPM. If you want to remove them, delete the asset manually from the Assets page in Mayo ASPM.
Uninstalling the GitHub App entirely¶
- Go to GitHub > Settings > Applications > Mayo ASPM.
- Click Uninstall.
This revokes all access immediately. Existing data in Mayo ASPM (assets, findings, scan history) is preserved but no new scans can run until you reinstall.
Troubleshooting¶
| Problem | Solution |
|---|---|
| "Insufficient permissions" error during install | You need Owner or Admin role on the GitHub org. Ask an org owner to install the app or grant you admin rights. |
| Repositories not showing after install | Wait 30 seconds and refresh. If they still don't appear, check that the repos were selected during installation. |
| PR scanning not triggering | Verify the webhook is registered: GitHub > Repo > Settings > Webhooks. You should see a mayoaspm.com webhook. |
| "App suspended" warning | A GitHub org admin may have suspended the app. Ask them to unsuspend it from GitHub > Settings > Applications. |
Your repositories are now connected and ready to scan.
:material-arrow-right: Next: Running Your First Scan