GitHub Permissions

FlagShark has two separate components that interact with GitHub, and they have different permission models. Understanding which component you're configuring prevents over-granting permissions.

Permission Models

GitHub Action (CI, no account required)

The FlagShark GitHub Action runs in your CI pipeline and uses the built-in GITHUB_TOKEN. Add these two permissions to your workflow permissions: block — nothing more is needed:

Example workflow configuration:

permissions:
  contents: read
  pull-requests: write

The Action does not need Issues write or Contents write. It does not create branches or call the Issues API.

FlagShark GitHub App (SaaS)

The FlagShark GitHub App is installed via the dashboard and powers the SaaS features: automatic PR analysis, cleanup PR generation, and comment management. It requires a broader set of permissions:

Common Permission Issues

Can't Install on Organization

Symptoms: Installation fails or shows "You don't have permission to install this app."

Causes:

• You're not an organization owner or admin
• Organization has restricted app installations
• Third-party app access is disabled

Solutions:

For Organization Owners:

App Installed But No Repository Access

Symptoms: FlagShark is installed but can't see your repositories.

Causes:

• App only has access to selected repositories
• Your repository isn't in the selection
• Repository is private and access wasn't granted

Solutions:

Can't Post PR Comments

Symptoms: FlagShark detects flags but doesn't post comments on PRs.

Causes:

• Missing Issues write permission (the GitHub App posts PR comments through the Issues API)
• Organization policy blocking comments
• Rate limiting

Check permissions:

If permission is missing:

Action Not Posting Comments

Symptoms: The GitHub Action runs but no PR comment appears.

Cause: The workflow permissions: block is missing pull-requests: write.

Fix: Add the permissions block to your workflow:

permissions:
  contents: read
  pull-requests: write

The Action does not use the Issues API and does not need issues: write.

Webhooks Not Being Received

Symptoms: Nothing happens when you open or update PRs.

Causes:

• Webhook not properly configured
• Webhook delivery failing
• Repository removed from app access

Check webhook status:

Common webhook errors:

Can't Read Repository Contents

Symptoms: FlagShark can't analyze PRs, shows "access denied" errors.

Causes:

• Missing Contents read permission
• Repository is private and not accessible
• Branch protection blocking access

Solutions:

• Verify FlagShark has Contents read permission
• Ensure the repository is included in app access
• Check if branch protection rules affect API access

Organization Policies

SAML SSO

If your organization uses SAML SSO:

Third-Party Access Restrictions

Some organizations restrict third-party app access:

IP Allow Lists

If your organization uses IP allow lists:

• FlagShark needs to be able to reach GitHub's API
• Contact FlagShark support for our IP ranges if needed

Reinstalling FlagShark

If permissions are corrupted, a clean reinstall often helps: