GitHub Permissions

FlagShark requires specific GitHub permissions to function properly. This guide helps you diagnose and resolve permission-related issues.

Required Permissions

FlagShark requests these permissions during installation:

Permission	Level	Purpose
Repository contents	Read	Fetch PR diffs and file contents
Pull requests	Read & Write	Read PR data, post comments
Metadata	Read	Access repository information
Webhooks	Read & Write	Receive PR events

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:

Screenshot needed: GitHub Settings → GitHub App repository access

Repository access settings showing 'Only select repositories' option with repository list

Can't Post PR Comments

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

Causes:

• Missing "Pull requests: Write" permission
• Organization policy blocking comments
• Rate limiting

Check permissions:

If permission is missing:

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:

Error	Meaning	Solution
No webhook listed	App not installed properly	Reinstall FlagShark
401 Unauthorized	Authentication issue	Reinstall the app
403 Forbidden	Permission denied	Check app permissions
404 Not Found	Endpoint issue	Contact FlagShark support
No recent deliveries	Webhooks not triggering	Check app is still installed

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: