Integration Permissions

BIMP connects only to the repositories available through the provider connection you configure. Use this page to review the credentials and permissions required for repository discovery, scanning, remediation, and provider events.

GitHub

GitHub App architecture

BIMP integrates with GitHub as a GitHub App. When you connect GitHub, GitHub installs the BIMP App on the account or organization you select. During installation, you can grant access to all repositories or only selected repositories. GitHub remains the source of truth for that repository scope.

BIMP stores the installation ID and account details needed to identify the connection. It does not ask you for a GitHub personal access token. For API operations, BIMP authenticates the App with its private key and requests an installation access token for the connected installation. GitHub limits that token to the permissions and repositories granted to the installation.

GitHub sends subscribed repository events to the App webhook. BIMP validates the HMAC-SHA256 signature before accepting a delivery, rejects replay conflicts, and uses the installation ID to resolve the correct BIMP organization.

GitHub token security

• The GitHub App private key is an environment-level BIMP secret. It is not a credential taken from your GitHub user account.
• The App uses a short-lived JSON Web Token (JWT) only to authenticate as the App and request an installation access token.
• GitHub installation access tokens expire after one hour. BIMP obtains them as needed rather than storing a long-lived GitHub personal access token.
• Installation tokens cannot exceed the repository selection or permissions approved for the App installation.
• The webhook signing secret does not grant GitHub API access. It authenticates inbound webhook deliveries only.

See GitHub’s documentation for authentication as a GitHub App installation and choosing GitHub App permissions.

Required GitHub permissions

All permissions are repository permissions. BIMP does not require organization administration or account permissions.

Permission	Access	Primary use
Metadata	Read-only	Repository discovery and identity.
Contents	Read and write	Scanning and remediation branches.
Pull requests	Read and write	Remediation pull request lifecycle.
Issues	Read-only	Snooze Requests comment events.

Metadata provides repository identity, visibility, and default-branch details; GitHub includes it with repository access. Contents allows BIMP to list branches and trees, read files, create remediation branches, update affected files, and remove BIMP remediation branches when required. Pull requests allows BIMP to create, inspect, update, label, comment on, mark draft or ready, and close its remediation pull requests. Issues read access is used only to receive issue_comment events on pull requests; BIMP does not require permission to create issues.

The GitHub App subscribes to these repository events:

Event	Purpose
push	Queue scans and refresh configured policy sources.
pull_request	Synchronize remediation pull request status.
issue_comment	Process supported Snooze Requests commands.

GitHub ties webhook availability to App permissions: push requires Contents read access, pull_request requires Pull requests read access, and issue_comment requires Issues read access. See GitHub’s webhook events and payloads for the provider requirements.

Change or revoke GitHub access

An account or organization owner can change the repository selection, suspend the installation, or uninstall the App in GitHub. Uninstalling it prevents BIMP from obtaining new installation tokens for that account. Follow GitHub’s instructions for reviewing and modifying installed GitHub Apps.

To disconnect cleanly, first remove tracked repositories that depend on the connection, then choose Disconnect in BIMP. BIMP attempts to uninstall the GitHub App installation. If the provider-side uninstall does not complete, use the GitHub instructions above to remove the installation directly.

GitLab

GitLab group token architecture

BIMP integrates with a GitLab group through the GitLab REST API. You create a group access token for the group and enter the group path and token when you connect GitLab. GitLab represents the token as a bot user whose reach is limited by both the token’s group role and its scopes. The bot inherits access to the group’s projects and subgroups.

BIMP validates the token against the configured group before saving the connection. It then uses the same token for repository discovery, file reads, remediation branches, file updates, merge requests, labels, and merge-request comments.

GitLab webhooks are configured separately. The webhook signing token authenticates inbound deliveries and does not grant access to the GitLab API.

GitLab token security

• Use a dedicated group access token rather than a personal access token. The resulting GitLab activity is attributed to the group’s bot user instead of a person.
• BIMP encrypts the group access token at rest with AES-256-GCM and decrypts it only when making a provider request.
• BIMP sends the token to the configured GitLab API in the Private-Token header. It redacts token-shaped values from provider errors returned to users.
• The token remains valid until its configured expiry date or until you rotate or revoke it in GitLab. BIMP cannot extend its lifetime.
• BIMP encrypts the separate webhook signing token at rest. That token can validate inbound webhook signatures but cannot call the GitLab API.

See GitLab’s documentation for group access token security and lifecycle and the available access token scopes.

Required GitLab permissions

Control	Required value	Primary use
Token type	Group access token	Group-scoped bot identity.
Scope	api	Read and write through the GitLab API.
Role	Developer or higher	Branch and merge request operations.
Group reach	Required projects	Repository access.
Webhook token	Secret; no API scope	Authenticate webhook deliveries.

The group access token limits the credential to the connected group, its projects, and its subgroups, and attributes operations to a bot user. The api scope permits BIMP to read group and project metadata and perform the writes needed for remediation files, branches, merge requests, labels, and comments. read_api and read_repository alone cannot perform those writes.

The bot user must be able to reach every repository that BIMP will track. The webhook signing token is required only when webhooks are enabled and is separate from the group access token.

Developer is the minimum role for the standard BIMP workflow. Protected branch rules, custom push rules, or other project policies can still prevent an operation even when the token has the required role and scope. BIMP writes to a remediation branch and opens a merge request; it does not require direct push access to the protected default branch. GitLab documents the relevant capabilities in Roles and permissions.

Revoke GitLab access

Disconnecting GitLab in BIMP removes BIMP’s stored copy of the group access token after dependent repositories are removed. It does not revoke the original token at GitLab. To invalidate the credential at the provider, open the GitLab group, go to Settings → Access tokens, and revoke the token. Follow GitLab’s group access token revocation instructions.

If you rotate rather than revoke the token, the previous value becomes inactive immediately. Enter the replacement token in BIMP before expecting discovery, scans, or remediation operations to resume.

Review access regularly

Review repository selection, token expiry, provider audit activity, and unused connections as part of your normal access review. Remove repositories from BIMP before disconnecting their provider connection, then revoke or uninstall access at the provider when BIMP should no longer be able to reconnect.

For connection and repository-management steps, see Code Providers & Repositories.