{
  "title": "GitHub permissions explained",
  "path": "/integrations/github/permissions",
  "url": "https://escapev.ai/integrations/github/permissions",
  "summary": "Every permission Escape Velocity requests from GitHub, what each one is for, and how each commitment is enforced.",
  "kind": "disclosure",
  "markdown": "https://escapev.ai/integrations/github/permissions.md",
  "integration": "github",
  "sections": [
    {
      "section": "understand",
      "heading": "Read permissions: Read your code, pull requests, and CI results",
      "blurb": "Escape Velocity understands your product by reading files, discussions, metadata, task tracking, and alerts. This information is used to ground understanding in your product, how the product is run and secured - and to help produce regular proposals for improvement.",
      "permissions": [
        {
          "scope": "metadata",
          "access": "read",
          "granted": "read",
          "purpose": "Reads the names, descriptions and settings of the repositories you pick, so you can choose which ones to connect. GitHub attaches this to every app."
        },
        {
          "scope": "issues",
          "access": "read",
          "granted": "read",
          "purpose": "Reads issues and their comments. Teams record decisions there as often as in documents, so issues often hold the reasoning."
        },
        {
          "scope": "checks",
          "access": "read",
          "granted": "read",
          "purpose": "Reads whether your checks passed on a commit, so work is only put in front of you once checks pass."
        },
        {
          "scope": "statuses",
          "access": "read",
          "granted": "read",
          "purpose": "Reads commit status from older CI integrations, which is how some repositories still report a build result."
        },
        {
          "scope": "members",
          "access": "read",
          "granted": "read",
          "purpose": "Maps commit authors to the people on your team, so a teammate is told apart from a bot."
        },
        {
          "scope": "discussions",
          "access": "read",
          "granted": "read",
          "purpose": "Reads GitHub Discussions, where many teams work through a design before an issue exists."
        },
        {
          "scope": "deployments",
          "access": "read",
          "granted": "read",
          "purpose": "Reads your deployment history, so what is actually running is known rather than assumed from the default branch."
        },
        {
          "scope": "environments",
          "access": "read",
          "granted": "read",
          "purpose": "Reads your configured environments, so staging and production are told apart."
        },
        {
          "scope": "packages",
          "access": "read",
          "granted": "read",
          "purpose": "Reads the packages published from your repositories, which is how a library release is distinguished from an application deploy."
        },
        {
          "scope": "repository_projects",
          "access": "read",
          "granted": "read",
          "purpose": "Reads the project boards attached to a repository, which carry the order of work that commits alone do not show."
        },
        {
          "scope": "organization_projects",
          "access": "read",
          "granted": "read",
          "purpose": "Reads the project boards your organization owns, where planning that spans several repositories usually lives."
        },
        {
          "scope": "organization_custom_properties",
          "access": "read",
          "granted": "read",
          "purpose": "Reads the custom properties your organization sets on repositories, which many teams use to mark tier, owner or lifecycle."
        },
        {
          "scope": "issue_types",
          "access": "read",
          "granted": "read",
          "purpose": "Reads the issue types your organization defines, so a bug is told apart from a feature in your own vocabulary rather than a guessed one."
        },
        {
          "scope": "issue_fields",
          "access": "read",
          "granted": "read",
          "purpose": "Reads the custom issue fields your organization defines, which carry the priority and sizing your team already agreed on."
        },
        {
          "scope": "administration",
          "access": "read",
          "granted": "read",
          "purpose": "Reads repository settings such as branch protection, so work is proposed the way your rules require instead of failing against them."
        },
        {
          "scope": "security_events",
          "access": "read",
          "granted": "read",
          "purpose": "Reads code scanning alerts, so a security finding is surfaced alongside the work that touches the affected code."
        },
        {
          "scope": "secret_scanning_alerts",
          "access": "read",
          "granted": "read",
          "purpose": "Reads alerts about secrets found in your code, so an exposed credential is raised as urgent rather than sitting in a list nobody opens."
        },
        {
          "scope": "vulnerability_alerts",
          "access": "read",
          "granted": "read",
          "purpose": "Reads Dependabot alerts about vulnerable dependencies, so an upgrade is proposed against a real advisory rather than as a routine version bump."
        }
      ]
    },
    {
      "section": "change",
      "heading": "Write permissions: Open pull requests, update branches, and re-run checks",
      "blurb": "Escape Velocity opens a pull request for your review and never merges without your approval.",
      "permissions": [
        {
          "scope": "contents",
          "access": "read and write",
          "granted": "write",
          "purpose": "Commits to a branch Escape Velocity opened for you, never to yours. Also reads your files at a specific commit, to understand your notes and documents."
        },
        {
          "scope": "pull_requests",
          "access": "read and write",
          "granted": "write",
          "purpose": "Opens a pull request for your review, and merges one you approved. Also reads each pull request's changes, reviewers and discussion, to learn how your team works."
        },
        {
          "scope": "workflows",
          "access": "read and write",
          "granted": "write",
          "purpose": "Changes files under `.github/workflows` when you ask for a change to your CI, which cannot be done through an ordinary commit. No automated job is ever given this."
        },
        {
          "scope": "actions",
          "access": "read and write",
          "granted": "write",
          "purpose": "Re-runs a check on a pull request Escape Velocity opened, so a flaky failure does not need you. Also reads your workflow run history, to tell a flaky check from a real failure."
        }
      ]
    }
  ],
  "promisesBlurb": "We value your trust and hold ourselves accountable to these commitments.",
  "promises": [
    {
      "claim": "We will never merge anything you have not approved",
      "enforcement": "Merging runs only against a pull request you approved, with a token carrying `pull_requests` write and `checks` read, and no `contents` grant at any level."
    },
    {
      "claim": "We will never change your CI without you asking",
      "enforcement": "No least-privilege scope grants `workflows`, so no automated job can mint a token that carries `workflows`. A CI change happens only when you ask for one."
    },
    {
      "claim": "We will never access a repository you did not choose",
      "enforcement": "Only the repositories you select are visible to Escape Velocity, through GitHub's own installation scope. You can change which ones at any time."
    }
  ]
}