> For the complete documentation index, see [llms.txt](https://docs.ox.security/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ox.security/get-started/onboarding-to-ox/source-control/github/github-app/ox-security-github-app-permissions.md). # OX Security GitHub App Permissions OX Security connects to GitHub through a GitHub App that scans your code and, optionally, acts on your behalf to remediate findings. OX offers two variants of the GitHub App, and this page covers both. OX follows the principle of least privilege. Every write the app performs is initiated by an explicit action in the OX UI. OX never modifies your repositories or organization silently. ### Which variant should you install | If you want OX to... | Install the... | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | Scan your code AND take action on your behalf, including opening auto-fix pull requests, posting PR comments and reviews, and remediating posture issues when you accept the fix in the OX UI | Recommended option: **Read + write variant** (default) | | Scan your code, surface findings in the OX UI, and let your team handle remediation manually | Not recommended option: **Read-only variant** | ### Capability comparison | Capability | Read + write | Read-only | | ------------------------------------------------------------------------------------------------- | ------------------------- | -------------- | | Code scanning (SAST, SCA, IaC, secret scanning) | Yes | Yes | | OX Security PR status check | Yes | Yes | | PR-aware scanning and code-review policies | Yes | Yes | | Ingest Dependabot, secret-scanning, and CodeQL findings | Yes | Yes | | Posture findings (branch protection, Actions, RBAC, webhooks) | Detection and remediation | Detection only | | One-click auto-fix pull requests | Yes | No | | Inline PR review comments on findings | Yes | No | | OX summary comment on pull requests | Yes | No | | Remediation of branch protection, repo settings, Actions permissions, and collaborator membership | Yes | No | | Clean uninstall from the OX UI | Yes | No | ### Status definitions * **Required:** OX can't function without this permission. * **Optional:** A specific OX feature becomes unavailable, but the rest of the platform continues to work. * **Reserved:** OX requests this permission for an upcoming capability. Denying it has no impact on current functionality. ### Permission details The table below lists every permission OX requests, the access level for each variant, why you need it, and what stops working if you don't grant it. | Status | Permission | Read + write variant | Read-only variant | Why you need it | If you don't grant this | | ------------------------------------ | ------------------------------------ | -------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Required | **Metadata** | Read | Read | So OX can find the repositories you've authorized and read basic repository information. GitHub requires this baseline permission for nearly every API endpoint. | OX can't see any repository, and no part of the product works. | | Required (read), Optional (write) | **Code (contents)** | Read and write | Read | Read is the foundation of every code scan OX runs (SAST, SCA, IaC, secret scanning). In the read + write variant, write also lets OX open one-click auto-fix pull requests on your behalf by creating a branch, committing the proposed fix, and opening a PR for your team to review and merge. | Without read: all code-based scanning stops. Without write (read + write variant only): auto-fix PRs can't be opened. Scanning continues and findings still appear in OX, but the *Fix* button on a finding won't work. | | Optional | **Checks** | Read and write | Read and write | So developers see OX findings directly on every pull request and you can gate merges on the **OX Security** check. This is the only write permission the read-only variant requests. | Scans still run and findings remain visible in the OX UI. However, no OX status check appears on pull requests, and any merge-gating workflow that depends on the OX check stops working. | | Optional (high value) | **Pull requests** | Read and write | Read | Read gives you per-PR scanning, code-review policy posture (for example, *Pull request merged without review*), and accurate attribution of who introduced a finding. Write (read + write variant only) lets OX open auto-fix PRs, post inline review comments at the exact file and line of a finding, request reviewers, and update or dismiss past reviews as findings evolve. | Without read: per-PR scanning, code-review policies, and commit-to-pull-request mapping stop. Branch-level scanning continues. Without write (read + write variant only): auto-fix PRs can't be opened, and OX can't post inline review comments. | | Optional | **Issues** | Read and write | Read | Read lets OX deduplicate comments when posting findings on pull requests, keeping the PR conversation clean. Write (read + write variant only) lets OX post and update its summary comment on a pull request. GitHub treats top-level PR comments as "issue comments". | Without read: pull request comment deduplication may be less effective. Without write (read + write variant only): the OX summary comment won't appear on pull requests. Inline review comments still work if you grant **Pull requests** write. | | Optional | **Actions** | Read and write | Read | Read gives you GitHub Actions and CI/CD posture findings (insecure third-party actions, fork pull request workflow rules, overly permissive Actions tokens). Write (read + write variant only) lets OX remediate Actions misconfigurations in one click, for example restricting default workflow permissions to read-only and disabling workflow approval of pull requests. | Without read: all GitHub Actions and CI/CD posture findings are unavailable. Without write (read + write variant only): detection still works, but your team will need to apply the fix manually using the guidance in the OX UI. | | Optional | **Administration** | Read and write | Read | Read gives you branch protection and ruleset compliance findings (*Branch lacks required reviews*, *Rulesets bypassable by admins*). Write (read + write variant only) lets OX remediate branch protection rules and repository settings (require reviews, require signed commits, disallow deletion or force pushes, set repo private, archive, disallow forking) when you accept the fix in the OX UI. | Without read: branch-protection and ruleset compliance findings are unavailable. Without write (read + write variant only): detection still works, but your team will need to apply the fix manually. | | Optional | **Members** | Read and write | Read | Read gives you RBAC and access-control findings (outside collaborators, admin sprawl, missing two-factor authentication enforcement). Write (read + write variant only) lets OX remove a collaborator or change a collaborator's permission level (pull, triage, push, maintain, admin) when you accept the fix. | Without read: all RBAC and access-control posture findings are unavailable. Without write (read + write variant only): detection still works, but OX can't apply the membership change on your behalf. | | Optional | **Organization administration** | Read | Read | Read gives you org-level audit-log analysis and discovery of installed apps. Write (read + write variant only) lets OX remove an organization member or change their org role, flip the org-level *Allow forking of private repositories* setting, and cleanly uninstall the OX GitHub App when you disconnect from the OX UI. | Without read: org-level audit-log analysis is unavailable. Without write (read + write variant only): org-level remediations are unavailable, and uninstalling the app must be done from the GitHub UI rather than from OX. | | Optional (read + write variant only) | **Workflows** | Write | Not requested | So OX's auto-fix pull requests can include changes to workflow files (`.github/workflows/*.yml`), for example bumping an action version as part of an SCA fix. GitHub treats workflow files as a separate scope and doesn't define a read level for it. | Auto-fix PRs that touch workflow files are rejected by GitHub. Auto-fix PRs that don't touch workflow files continue to work. | | Optional | **Dependabot alerts** | Read | Read | So GitHub's native Dependabot findings appear alongside OX's own SCA results in a single dashboard, giving you one place to triage vulnerable dependencies. | Dependabot findings don't appear in OX. The OX SCA scanner still detects vulnerable dependencies on its own. | | Optional | **Secret scanning alerts** | Read | Read | So GitHub's native secret-scanning results appear alongside OX's secret scanner, giving you a unified view of leaked secrets. | GitHub-native secret-scanning findings don't appear in OX. The OX secret scanner continues to operate. | | Optional | **Security events** | Read | Read | So CodeQL and any third-party SARIF findings uploaded to GitHub appear in OX, consolidating all your SAST results in one place. | GitHub Code Scanning, CodeQL, and SARIF-uploaded findings don't appear in OX. The OX SAST scanner continues to scan your code independently. | | Optional | **Repository hooks** | Read | Read | So OX can detect insecure webhooks that could leak repository data (for example, webhook URLs without SSL verification). | Webhook posture findings become unavailable. | | Reserved | **Commit statuses** | Read | Read | Reserved for upcoming commit-status posture analysis. | No impact on current functionality. | | Reserved | **Deployments** | Read | Read | Reserved for upcoming deployment-tracking findings. | No impact on current functionality. | | Reserved | **Pages** | Read | Read | Reserved for upcoming GitHub Pages posture analysis. | No impact on current functionality. | | Reserved | **Packages** | Read | Read | Reserved for upcoming GitHub Packages security analysis. | No impact on current functionality. | | Reserved | **Repository projects** | Read | Read | Reserved for upcoming repository-projects posture analysis. | No impact on current functionality. | | Reserved | **Custom repository roles** | Read | Read | Reserved for upcoming custom-role posture analysis on organization custom roles. | No impact on current functionality. | | Reserved | **Organization events** | Read | Read | Reserved for upcoming organization-event analysis. The organization audit log itself is covered under **Organization administration**. | No impact on current functionality. | | Reserved | **Organization hooks** | Read | Read | Reserved for upcoming organization-level webhook posture analysis. | No impact on current functionality. | | Reserved | **Organization projects** | Read | Read | Reserved for upcoming organization-projects posture analysis. | No impact on current functionality. | | Reserved | **Organization self-hosted runners** | Read | Read | Reserved for upcoming self-hosted runner security analysis. | No impact on current functionality. | | Reserved | **Organization user blocking** | Read | Read | Reserved for upcoming user-blocking posture analysis. | No impact on current functionality. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.ox.security/get-started/onboarding-to-ox/source-control/github/github-app/ox-security-github-app-permissions.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.