Skip to content

Integration Issues

This guide covers common problems with GitHub App, Jira, and API key integrations.

GitHub App

App not installed or missing repos

Symptom: Repositories don't appear in the assets list.

Steps:

  1. Go to Settings > Integrations > GitHub.
  2. Check the integration status. If Disconnected:
    • Click Install GitHub App and re-authorize.
  3. If Connected but repos are missing:
    • Click Manage repositories on GitHub.
    • Verify the repositories are selected in the GitHub App installation.
    • Return to Mayo ASPM and click Sync Now.

"Installation not found" error

Symptom: Operations fail with "GitHub App installation not found".

Cause: The GitHub App was uninstalled from the organization.

Fix: Re-install the GitHub App from Settings > Integrations > GitHub > Install GitHub App.

Webhook not delivering

Symptom: Pushes and PR events don't trigger scans.

Diagnostic steps:

  1. In GitHub, go to your Organization Settings > GitHub Apps > Mayo ASPM > Advanced.
  2. Check Recent Deliveries for failed webhooks.
  3. Common failure reasons:
Error Cause Fix
timeout Mayo ASPM didn't respond in time Transient; retries should succeed
404 Webhook URL is incorrect Contact support to verify webhook configuration
401 Webhook secret mismatch Re-install the GitHub App

Rate limited by GitHub

Symptom: Scans fail with "GitHub API rate limit exceeded".

Cause: Too many API calls to GitHub in a short period (typically during large org scans).

Solutions:

  1. Space out scans — don't scan the entire org at once during business hours.
  2. Reduce scan frequency — daily instead of hourly.
  3. Enterprise GitHub plans have higher rate limits.

Jira

Connection expired

Symptom: Integration status shows Disconnected or ticket operations fail.

Fix (Jira Cloud):

  1. Go to Settings > Integrations > Jira.
  2. Click Reconnect.
  3. Re-authorize via the Atlassian OAuth flow.

Fix (Jira Data Center):

  1. Verify the application link is still configured in Jira.
  2. If the link was removed, follow the Jira connection guide again.

Tickets not syncing from Jira

Symptom: Closing a Jira ticket doesn't update the finding in Mayo ASPM.

Diagnostic steps:

Step Check Fix
1 Webhook exists in Jira Go to Jira Admin > Webhooks — look for the Mayo ASPM webhook
2 Webhook URL is correct Should point to https://mayoaspm.com/api/webhooks/jira
3 Webhook events are correct Must include jira:issue_updated
4 Ticket has mayo-aspm label Only labeled tickets trigger sync

If the webhook was deleted, go to Settings > Integrations > Jira > Repair Webhook.

"No Jira projects found"

Symptom: Project mapping dropdown is empty.

Cause: The OAuth user doesn't have access to any Jira projects.

Fix: Reconnect using a Jira account with project access, or grant project permissions to the current user in Jira.

Ticket creation fails

Symptom: Pushing a ticket returns an error.

Common errors:

Error Cause Fix
"Issue type not found" Mapped issue type doesn't exist in Jira project Update field mapping
"Required field missing" Jira project has required custom fields Configure custom field mapping
"User not found" Assigned user doesn't exist in Jira Update ownership policy or assignee mapping
"Permission denied" OAuth user can't create issues in that project Check Jira project permissions

API Keys

"Unauthorized" (401) error

Symptom: API calls return 401.

Checklist:

Check Fix
Key format correct? Must be mayo_ak_...
Header format correct? Authorization: Bearer mayo_ak_... or X-API-Key: mayo_ak_...
Key not revoked? Check Settings > Integrations > API Keys
Key not expired? Check expiry date in key list
No trailing whitespace? Common in environment variables — trim the value

"Forbidden" (403) error

Symptom: API calls return 403 with "insufficient permissions".

Cause: The API key doesn't have the required permission for the endpoint.

Fix:

  1. Check the endpoint's required permissions in the API docs.
  2. Check the key's permissions in Settings > Integrations > API Keys.
  3. If the key lacks the needed permission, create a new key with the correct permissions.

Info

API key permissions cannot be modified after creation. Create a new key with the correct permissions and revoke the old one.

API key exposed in code

Symptom: Gitleaks or another scanner found your API key committed to a repository.

Steps:

  1. Revoke the key immediately in Settings > Integrations > API Keys.
  2. Create a new key.
  3. Store the new key in a secrets manager.
  4. Remove the key from the repository's git history (use git filter-branch or BFG Repo-Cleaner).

General integration issues

Integration health degraded

Symptom: Settings > Integrations shows a yellow "Degraded" status.

Meaning: The integration is partially working but experiencing issues (e.g., intermittent webhook failures).

Steps:

  1. Click the integration for details on the degradation.
  2. Check for specific error messages.
  3. Most degraded states resolve automatically within an hour.
  4. If persistent, try disconnecting and reconnecting the integration.

Next steps