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

FlagShark follows the principle of least privilege - we only request permissions necessary for core functionality.

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:

1. **Check your role**: You need Owner or Admin role on the organization 2. **Request installation**: Non-admins can request the app be installed 3. **Contact org admin**: Ask them to approve or install FlagShark

For Organization Owners:

1. Go to Organization Settings > Third-party access 2. Ensure GitHub Apps can be installed 3. Check for pending installation requests 4. Approve FlagShark if it's pending

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:

1. Go to GitHub > Settings > Applications (or Organization Settings > GitHub Apps) 2. Find FlagShark and click "Configure" 3. Under "Repository access", choose: - "All repositories" for full access, or - "Only select repositories" and add your repo 4. Save changes

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:

1. Go to the repository > Settings > Integrations 2. Find FlagShark in the list 3. Verify it shows "Pull requests: Read and write"

If permission is missing:

1. Go to GitHub > Settings > Applications 2. Find FlagShark > Configure 3. Review permissions - they should include Pull requests (read & write) 4. If permissions have changed, you may need to re-approve

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:

1. Go to Repository > Settings > Webhooks 2. Find the FlagShark webhook 3. Check "Recent Deliveries" for success/failure 4. Look at response codes and messages

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:

1. Go to your personal GitHub settings > Applications 2. Find FlagShark 3. Click "Enable SSO" for your organization 4. Complete the SSO authentication You may need to re-enable SSO after each GitHub session, depending on your organization's SSO settings.

Third-Party Access Restrictions

Some organizations restrict third-party app access:

1. Go to Organization > Settings > Third-party access 2. Check if third-party apps are restricted 3. If restricted, an admin must approve FlagShark 4. Look for FlagShark in pending requests

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:

1. **Uninstall the app**: - Go to GitHub > Settings > Applications - Find FlagShark > Configure - Scroll down and click "Uninstall" - Confirm uninstallation

2. Wait a moment: Give GitHub time to clean up

3. Reinstall:

   • Go to FlagShark dashboard
   • Click "Add Repository" or "Install GitHub App"
   • Follow the installation flow
   • Select repositories to grant access

4. Verify: Create a test PR with a flag to confirm detection works

Reinstalling won't lose your FlagShark data. Your flag history and settings are preserved.

Personal vs Organization Repositories

Personal Repositories

For repositories under your personal account:

• You have full control over app installations
• Go to Settings > Applications to manage
• Grant access to specific repos as needed

Organization Repositories

For organization repositories:

• You need appropriate org permissions
• Installations may require admin approval
• Repository access can be controlled by org policies

Forked Repositories

For forks:

• FlagShark needs access to the fork, not just the upstream
• PRs from forks may have limited access
• Consider granting access to fork repositories

Checking Current Permissions

From GitHub

1. Go to github.com/settings/applications (personal) or Organization > Settings > GitHub Apps 2. Find FlagShark 3. Click "Configure" 4. Review "Permissions" section 5. Review "Repository access" section

From FlagShark Dashboard

1. Go to Settings > Repositories 2. Look for permission status indicators 3. Red/yellow indicators suggest permission issues 4. Click a repository for details

Requesting Additional Permissions

If FlagShark adds new features requiring additional permissions:

1. You'll see a notification about new permissions needed 2. Go to GitHub App settings 3. Review the new permission requests 4. Approve if acceptable 5. Permissions update automatically FlagShark will never request permissions beyond what's needed for feature flag management. We'll always explain why new permissions are needed.

Permission Audit Log

Track permission changes in your organization:

1. Go to Organization > Settings > Audit log 2. Filter by "integration" or "app" 3. Look for FlagShark-related events 4. Review any permission changes or access modifications

Getting Help

If you're still having permission issues:

1. **Document the issue**: - Screenshot of error messages - Your GitHub role (owner, admin, member) - Whether it's personal or organization repo - Current permission settings

2. Check status: Visit status.flagshark.com

3. Contact support: Email [email protected] with:

   • Organization/repository name
   • Your GitHub username
   • Description of what you've tried
   • Screenshots of permission settings

Related Documentation

• Installation - Initial setup guide
• Connecting Repositories - Adding repos
• Common Issues - General troubleshooting
• GitHub Comments - PR comment feature