GitHub plugin
The GitHub plugin lets a Vaubaan Gateway mission use GitHub without handing the agent a credential. Repositories, branches, files, pull requests, issues, releases and workflows of the GitHub App installation.
- Version:
3.2.0(package@vaubaan/plugin-github) - Status: stable
- Health: not enough reports yet — what this means
- Source: plugins/github, catalog risk-catalog.yaml version 7 of 2026-10-16
- How to connect an account: Connect GitHub
- How it is modelled: handbook
One account is one installation of your company's GitHub App on an organisation, or a fine-grained personal access token; one resource is one repository. A mission picks repositories and the permissions it holds on them. GitHub has no environment label: protected branches (main, master, release-*) and working branches (feature/*, fix/*, …) are told apart by two different permissions.
Permissions
Each permission is a named risk of the plugin's catalog: a mission holds an explicit list of them, never "all". The severity is computed from the permission's six axes (undo, blast radius, data, cost, visible to, lasts); nothing is decided from it.
| Permission | What it allows | Severity | Why it is a risk |
|---|---|---|---|
github.read-code | Read code, branches, commits, files | low | Reads may leak secrets through `.env`-style commits (rare but non-zero). The contents of fetched files are attacker-injectable into the agent's context (OWASP LLM01) — a malicious README can steer a downstream prompt. |
github.read-meta | Read PRs, issues, releases, workflows, branch-protection | low | Repository metadata. Issue/PR bodies are attacker-controlled (OWASP LLM01) — handle with care on the agent side. Reading branch protection rules is diagnostic only, never dangerous in itself. |
github.search-global | Global GitHub search (code / issues, beyond the mission resources) | low | Search traverses every public GitHub repo plus every repo the App installation has access to. Cross-org leakage is possible if the App is installed widely. Sensitivity is low by default but the surface is account-shaped, not resource-shaped. |
github.feature-branch-write | Create/modify branches under feature/*, fix/*, chore/*, … | low | Reversible (`git revert` or branch delete). No production side effect until merged. This is the heart of the coding-agent flow. |
github.merge-protected | Write on main / master / release-* (direct commit OR PR merge) | medium | The canonical branch — triggers downstream CI/CD on prod. Costly to revert (release notes, communications, downstream dependencies). Covers direct commits (create_or_update_file without a PR) AND merges of PRs whose base is one of these branches. |
github.workflow-write-via-file | Modify a GitHub Actions workflow (.github/workflows/*.yml) | high | The CI YAML defines what runs with the repo's secrets. Modifying a workflow is a potential privilege-escalation vector (steal secrets via curl to attacker-controlled domain, `pull_request_target`). `dispatch_workflow` was retired for this reason — but the attack persists through file writes on the YAML itself. |
github.bulk-file-write | Bulk multi-file push (push_files) | low | A single commit touching many files. Harder to review manually than a single-file write. Kept distinct from file-by-file so the creator can opt-in/out specifically — useful signal for spotting malicious or buggy agents. Emitted as a `files-bulk` virtual leaf alongside the per-file `file[<path>].W` slices. |
github.create-pr | Open a pull request | low | No prod mutation. Notifies reviewers (visibility=team). PR title and body are reviewer-injectable. |
github.comment-write | Comment on an issue or PR | low | A comment on a PR notifies reviewers ; on an issue, subscribers. Low risk but pollution / spam potential if abused. |
github.create-release | Create a release (potentially public publication) | medium | With `draft=false && prerelease=false`, the release is publicly visible, notifies watchers, and triggers `on: release` workflows. Hard to "retract" — downstream consumers may already have pulled tarballs / asset URLs by the time you delete. |
github.delete-release | Delete a release | medium | Irreversible w.r.t. audit / external notifications. The tag itself persists, but the release body and assets vanish — downstream consumers may see 404s. |
github.branch-protection-write | Modify branch protection | medium | Posture-shift : opens the branch to out-of-process writes (e.g. disabling required reviews). Persists after the token's lifetime. Even when *tightening* (adding a required check), the change outlives the session. |
github.git-push | Push with git through the gateway | low | The git remote of the gateway relays the pack and moves the ref only after the decision. Touched by every pushed ref, next to the risk of the branch or tag it lands on ; it is what a creator limits to bound how often an agent pushes. The pack itself is not read : the decision is on refs and changed paths, never on content. |
github.force-push | Force-push (rewrite the history of a branch or move a tag) | low | A push that is not a fast-forward replaces commits others may have built on ; once replaced, they may survive only in someone's clone. Agents rebase often, which is precisely where a mistake destroys work. |
github.branch-delete | Delete a branch with git | low | The branch disappears for everyone ; its commits remain reachable only from other refs and clones. A deleted protected branch also touches `merge-protected`. |
github.tag-write | Push or delete a tag with git | medium | A tag names a release point : pushing one can trigger `on: push: tags` workflows (publication, deployment) and downstream consumers pin tags. Overlaps `create-release` on purpose : a tag pushed by git also writes `tag[<name>]`, which `create-release` covers, so a mission that may push tags says so twice. Matched on the git leaves only : `create_release` keeps touching `create-release` alone. |
github.mint-install-token-clone | Mint an install token (purpose=clone, read-only) | medium | Credential creation, but scoped to `contents:read` only. The token has its own TTL (1h) and its own scope. Moderate risk : code extraction is possible, no mutation. |
github.mint-install-token-push | Mint an install token (purpose=push, write) | medium | Credential creation with `contents:write + pull_requests:write + workflows:write`. The token leaves the gateway's gating perimeter ; no Vaubaan policy applies to usages of this credential. De-facto posture-shift. |
github.uncategorized-write | Uncategorized GitHub write (fallback) | medium (the catch-all: touched only by a call no other permission covers) | Catch-all for writes no fine-grained entry categorises — a branch outside the feature/* and protected conventions, or a future tool added without a catalog entry. Never offered by a preset ; the creator opts in explicitly (no implicit accept). |
Presets
A preset pre-fills the permissions of a mission for one account, with a limit per period, a rate and whether each permission runs freely or asks the mission creator first. The person creating the mission adjusts it; the mission stores the explicit list.
Read-only
read-only — Read code and metadata of the selected repositories; no write, no global search.
| Permission | What it allows | Limit per period | Rate | Runs |
|---|---|---|---|---|
github.read-code | Read code, branches, commits, files | 5000 | 120 per minute | runs freely |
github.read-meta | Read PRs, issues, releases, workflows, branch-protection | 5000 | 120 per minute | runs freely |
Developer
developer — One mission per code repository — clone and push with git on feature branches (a force-push asks first), read everything, open PRs and comment; no merge on protected branches, no branch-protection changes.
| Permission | What it allows | Limit per period | Rate | Runs |
|---|---|---|---|---|
github.read-code | Read code, branches, commits, files | 10000 | 240 per minute | runs freely |
github.read-meta | Read PRs, issues, releases, workflows, branch-protection | 10000 | 240 per minute | runs freely |
github.search-global | Global GitHub search (code / issues, beyond the mission resources) | 500 | 30 per minute | runs freely |
github.feature-branch-write | Create/modify branches under feature/*, fix/*, chore/*, … | 3000 | 60 per minute | runs freely |
github.bulk-file-write | Bulk multi-file push (push_files) | 1000 | 30 per minute | runs freely |
github.create-pr | Open a pull request | 200 | 10 per minute | runs freely |
github.comment-write | Comment on an issue or PR | 500 | 20 per minute | runs freely |
github.workflow-write-via-file | Modify a GitHub Actions workflow (.github/workflows/*.yml) | 50 | 5 per minute | ask me first |
github.git-push | Push with git through the gateway | 200 | 10 per minute | runs freely |
github.force-push | Force-push (rewrite the history of a branch or move a tag) | 20 | 2 per minute | ask me first |
Release manager
release-manager — Ship a release — merge into protected branches, create and delete releases, push tags with git, each asking the creator first; read everything.
| Permission | What it allows | Limit per period | Rate | Runs |
|---|---|---|---|---|
github.read-code | Read code, branches, commits, files | 5000 | 120 per minute | runs freely |
github.read-meta | Read PRs, issues, releases, workflows, branch-protection | 5000 | 120 per minute | runs freely |
github.feature-branch-write | Create/modify branches under feature/*, fix/*, chore/*, … | 500 | 30 per minute | runs freely |
github.create-pr | Open a pull request | 100 | 10 per minute | runs freely |
github.comment-write | Comment on an issue or PR | 200 | 10 per minute | runs freely |
github.merge-protected | Write on main / master / release-* (direct commit OR PR merge) | 50 | 5 per minute | ask me first |
github.create-release | Create a release (potentially public publication) | 20 | 2 per minute | ask me first |
github.delete-release | Delete a release | 5 | 1 per minute | ask me first |
github.git-push | Push with git through the gateway | 100 | 10 per minute | runs freely |
github.tag-write | Push or delete a tag with git | 20 | 2 per minute | ask me first |
Tools
| Tool | What it does |
|---|---|
github__list_branches | List branches |
github__list_commits | List commits |
github__list_pull_requests | List pull requests |
github__list_issues | List issues |
github__get_file_contents | Read a file |
github__get_pull_request | Read a pull request |
github__get_issue | Read an issue |
github__get_commit | Read a commit |
github__search_code | Search code |
github__search_issues | Search issues and pull requests |
github__create_branch | Create a branch |
github__create_or_update_file | Write a file on a branch |
github__push_files | Push files to a branch |
github__create_pull_request | Open a pull request |
github__add_issue_comment | Comment on an issue or pull request |
github__mint_install_token | Get a short-lived token for git |
github__list_workflows | List workflows |
github__list_workflow_runs | List workflow runs |
github__get_branch_protection | Read the protection of a branch |
github__merge_pull_request | Merge a pull request |
github__delete_file | Delete a file on a branch |
github__update_branch_protection | Change the protection of a branch |
github__list_releases | List releases |
github__list_tags | List tags |
github__create_release | Create a release |
github__delete_release | Delete a release |
Tools that hand the agent a short-lived provider token (the one exception to "the agent never holds a credential"), each a permission of its own:
github__mint_install_token:github.mint-install-token-clone,github.mint-install-token-push
The instance is also the agents' git remote for this service: git clone and git push go through the gateway with the mission key, every pushed ref decided like a tool call (git remote).
Health
Health: not enough reports yet. A plugin version is deemed validated by the community with at least 200 reports and 90 % of them successful, over the last 90 days, as reported by the instances whose operators turned community telemetry on. It is a community signal, not a security guarantee.