GitHub Operations Plugin
Connect your GitHub organisation to QuoxCORE. Cross-repo issue board, pull requests, VULCAN AI agent, release management, feedback pipeline, and AOCL policy gates.
Overview
The GitHub Operations plugin brings your entire GitHub organisation into QuoxCORE. Instead of switching between repositories, browser tabs, and notification emails, you get a single operational view: issues from every repo in one list, pull requests with review status at a glance, AI-driven queries and actions through VULCAN, governed releases with deploy checklists, and a feedback pipeline that turns website form submissions into tracked issues.
Every destructive action is gated by AOCL policy rules and logged server-side.
Setup
1. Add GitHub credentials
Go to Settings → Provider Keys → Advanced setup (Instance scope) in QuoxCORE and add a GitHub credential with a Personal Access Token (classic). Fine-grained tokens are not yet supported.
Required scopes:
| Scope | Purpose |
|---|---|
repo | Full repository access (issues, PRs, code, releases) |
read:org | Read organisation membership and team data |
workflow | Trigger and monitor GitHub Actions workflows |
2. Open the GitHub plugin
Click GitHub in the QuoxCORE sidebar. The plugin opens with a setup wizard on first use.
3. Link your organisation
The setup wizard discovers your GitHub organisations from the token. Select the organisation to link to your current Quox org. Each Quox org can link to one GitHub org.
4. Select repositories
Choose which repositories to track. You can select all or pick individual repos. This controls which repos appear in the issues board, PR list, and release manager. You can change this later in the plugin settings.
Features
Issues Board
A cross-repo view of all issues from your tracked repositories in one list.
- Filter by: repository, state (open/closed/all), labels, text search
- Inline actions: close, reopen, add labels, add comments directly from the board
- Issue detail: full markdown body, comments timeline, linked PRs
- Feedback tab: filter to show only issues created from website form submissions
Pull Requests
A cross-repo PR list showing state, review status, and author.
- Filter by: repository, state (open/closed/merged/all)
- Review status and CI results visible at a glance
FORGE AI Agent
FORGE gains full GitHub context when this plugin is active. Use the sidebar chat to ask questions, take actions, and draft content.
Ask questions:
- "What issues are open in quoxflow?"
- "Why did the last CI run fail?"
- "Show me all critical bugs across repos"
Take actions:
- "Create an issue in quoxmcp about timeout handling"
- "Close issue #42 with comment: fixed in v1.2.3"
- "Re-run the failed workflow in quoxbastion"
Draft content:
- "Draft release notes for quoxflow since v1.2.0"
- "Summarise what changed this week across all repos"
Quick actions are also available directly in the sidebar chat panel.
Release Management
Create and manage releases across all tracked repositories.
- Release list: browse releases across all tracked repos
- Create release: select tag, title, and auto-generate release notes via the GitHub API. Toggle draft and prerelease flags.
- Deploy checklist: five manual confirmations before release creation: tests passing, no blocking issues, changelog updated, version bumped, security review done
- Recent changes feed: the last 5 closed issues shown alongside the release form for context
Feedback Pipeline
Website form submissions (feedback, leads, contact forms) automatically create GitHub issues.
- Deduplication: if the same email address submits within 5 minutes, the second submission is added as a comment on the existing issue instead of creating a duplicate
- Labels:
feedback,lead,triage-needed, plus source labels (from:website,from:investor) - Privacy: email addresses are redacted from the issue body when the target repository is public
- Configuration: set the GitHub PAT and target repository in Admin > Site Settings > GitHub PAT + GitHub Issues Repo
Policy Gates (AOCL)
AOCL policy rules enforce operational discipline. Each policy can be toggled on or off in the GitHub plugin settings.
- requireChecklistBeforeRelease — blocks release creation until all five checklist items are confirmed
- requireLinkedPRForClosure — warns when closing an issue without a linked pull request; requires an override reason to proceed
- requireReviewApproval — warns about pull requests merged without at least one review approval
All policy evaluations are logged server-side in JSONL format for audit purposes.
FORGE MCP Tools Reference
The plugin exposes 11 tools through the MCP (Model Context Protocol) interface, available to FORGE and any connected MCP client.
| Tool | Description | Parameters |
|---|---|---|
github_list_issues | List issues across tracked repos | repo, state, labels, assignee, page |
github_get_issue | Get issue detail with comments | repo, number |
github_create_issue | Create an issue | repo, title, body, labels |
github_update_issue | Update issue state, labels, or assignees | repo, number, state, labels, comment |
github_list_prs | List pull requests | repo, state |
github_get_pr_diff | Get PR diff summary | repo, number |
github_list_actions_runs | List GitHub Actions runs | repo, status, per_page |
github_get_actions_log | Get Actions run details and logs | repo, run_id |
github_rerun_workflow | Re-trigger a workflow run | repo, run_id |
github_create_release | Create a GitHub release | repo, tag_name, name, body, draft |
github_compare_commits | Compare two refs | repo, base, head |
Security
- Token storage: the GitHub PAT is stored in QuoxCORE vault (encrypted, server-side only)
- Proxied API calls: all GitHub API requests are proxied through the collector service. The browser never holds the token.
- Org-scoped: each Quox organisation has its own GitHub credential and org mapping. Credentials are not shared across orgs.
- Audit trail: all policy evaluations and destructive actions are logged to a server-side audit trail
Configuration Reference
All settings are managed in the GitHub plugin settings panel.
| Setting | Description | Default |
|---|---|---|
| GitHub PAT | Personal Access Token (stored in vault) | Required |
| Organisation | GitHub org linked to current Quox org | Set during setup |
| Tracked repos | Which repositories to sync | All (configurable) |
| Sync interval | How often to refresh data (minutes) | 15 |
| requireChecklistBeforeRelease | Block releases without completed checklist | On |
| requireLinkedPRForClosure | Warn on closing issues without a linked PR | Off |
| requireReviewApproval | Warn on PR merges without review approval | Off |
Troubleshooting
Token expired
The plugin shows a red banner when the token is invalid or expired. Go to Settings → Provider Keys → Advanced setup, update your GitHub credential with a new PAT.
Rate limited
GitHub allows 5,000 API requests per hour for authenticated tokens. The plugin shows remaining quota in the status bar. If rate limited, wait for the limit to reset or reduce the number of tracked repositories. Increasing the sync interval also helps.
Repo with issues disabled
Repositories with the Issues feature disabled in GitHub are silently skipped. If a repo is missing from the issues board, check Settings > Features > Issues on that repository in GitHub.
GitHub Enterprise
Not yet supported. The plugin connects to api.github.com only. Enterprise Server support is planned.
No issues appearing
Check the following:
- Your token has the
reposcope - Repositories are selected in the plugin settings
- Click Sync to force an immediate refresh
- Review the plugin logs in QuoxCORE for API errors