Devesh
568c04f7c1
* docs: reorganize sidebar navigation and clean up install pages` * feat: enhance index hero styling and update features documentation * docs: update installation guides and enhance table styling * docs: enhance investigation documentation and improve interactive shell descriptions * Update documentation for API, community giveaway, CloudOpsBench, deployment, FAQ, PR review flow, and Python API * Update documentation for background investigations, closed-loop learning, cron scheduling, and integrations overview * Introducing structured flow for the documentation * docs: update integration documentation for various services --------- Co-authored-by: Vaibhav Upreti <vaibhav.upreti16@gmail.com> Co-authored-by: Cursor <cursoragent@cursor.com>
156 lines
6.7 KiB
Plaintext
156 lines
6.7 KiB
Plaintext
---
|
|
title: "GitHub workflow tools"
|
|
description: "Use GitHub-backed tools for read snapshots, status reports, follow-up summaries, and approved issue mutations"
|
|
---
|
|
|
|
## Overview
|
|
|
|
OpenSRE provides GitHub workflow tools for engineering coordination. The public workflow is:
|
|
|
|
1. Read a GitHub snapshot.
|
|
2. Generate a report or community follow-up summary.
|
|
3. Render a mutation proposal for explicit Slack-sourced task requests.
|
|
4. Execute the proposal only through the runtime approval path.
|
|
|
|
The workflow tools deliberately separate read-only snapshots from mutating execution. Headless or non-approved runs can produce proposals, but they cannot execute workflow mutations.
|
|
|
|
For ad-hoc chat mutations outside the Slack proposal flow (create issue, assign, merge, `gh api`, etc.), use **`github_cli`** instead — see [GitHub](/github).
|
|
|
|
## Prerequisites
|
|
|
|
- GitHub connected via [GitHub integration](/github)
|
|
- Token with at least `repo` scope; add security-alert scopes for `list_github_security_alerts`
|
|
|
|
## Setup
|
|
|
|
Workflow tools use the same GitHub MCP credentials as the [GitHub integration](/github).
|
|
|
|
```bash
|
|
opensre integrations setup github
|
|
opensre integrations verify github
|
|
```
|
|
|
|
| Requirement | Details |
|
|
| --- | --- |
|
|
| **Token** | `GITHUB_MCP_AUTH_TOKEN`, or browser sign-in via `opensre integrations setup github` |
|
|
| **Scopes** | `repo` minimum; add security alert scopes for `list_github_security_alerts` |
|
|
| **Alternate env** | `GITHUB_TOKEN` / `GH_TOKEN` accepted by some workflow tools |
|
|
|
|
### Example REPL turn
|
|
|
|
```text
|
|
> generate a Slack-ready morning check-in for Tracer-Cloud/opensre
|
|
· gathering via GitHub · list work items…
|
|
```
|
|
|
|
## Credentials
|
|
|
|
Set a GitHub token through the configured GitHub integration, `GITHUB_TOKEN`, or `GH_TOKEN`.
|
|
|
|
Security alert endpoints require token scopes that GitHub enforces separately. If the token cannot read one alert class, the tool returns an error for that alert type while still returning any alert classes it can read.
|
|
|
|
## Investigation tools
|
|
|
|
| Tool | Role | Side effects |
|
|
| --- | --- | --- |
|
|
| `list_github_work_items` | Reads issues and classifies work as `taken`, `up_for_grabs`, or `unassigned`. | None |
|
|
| `summarize_github_pr_status` | Reads PR detail endpoints, authoritative mergeability, check runs, and blocking reasons. | None |
|
|
| `list_github_security_alerts` | Reads Dependabot, secret-scanning, and code-scanning alerts when token scope allows. | None |
|
|
| `generate_work_status_report` | Produces a Slack-ready status report from work items and PR status. | None |
|
|
| `summarize_community_followups` | Reads repository issue comments, then summarizes unanswered questions, agenda items, and suggested replies. | None |
|
|
| `propose_github_issue_mutation_from_slack` | Builds a deterministic proposal for creating, updating, or closing a GitHub issue from an explicit Slack request. | None |
|
|
| `execute_github_issue_mutation` | Executes an approved proposal. | Mutating; requires runtime approval |
|
|
|
|
### Workflow
|
|
|
|
#### 1. Read snapshot
|
|
|
|
Use read tools first:
|
|
|
|
- `list_github_work_items`
|
|
- `summarize_github_pr_status`
|
|
- `list_github_security_alerts` when security status is relevant
|
|
|
|
`summarize_github_pr_status` does not trust list-endpoint mergeability. It fetches each PR detail endpoint so `mergeable` and `mergeable_state` are authoritative. Unknown mergeability is reported as `unknown`, not as ready to merge.
|
|
|
|
#### 2. Report or summarize
|
|
|
|
Use `generate_work_status_report` for morning check-ins, Slack updates, blockers, owners, and next actions.
|
|
|
|
If the report tool performs its own GitHub reads and a required read fails, it returns:
|
|
|
|
- `available: false`
|
|
- `incomplete: true`
|
|
- an `errors` list
|
|
|
|
It must not produce a false "no blockers" report from partial data.
|
|
|
|
Use `summarize_community_followups` for contributor questions, community meeting agenda items, and suggested replies. It reads repository issue comments directly with pagination instead of performing one request per issue.
|
|
|
|
#### 3. Propose mutation
|
|
|
|
Only when the user explicitly asks to turn a Slack request into a GitHub task, call `propose_github_issue_mutation_from_slack`.
|
|
|
|
Good proposal triggers:
|
|
|
|
- "Add this Slack request to the project task list."
|
|
- "Create a GitHub task from this thread."
|
|
- "Update issue 42 with this Slack context."
|
|
- "Close task 51; PR #2973 shipped."
|
|
|
|
The proposal includes:
|
|
|
|
- operation: `create`, `update`, or `close`
|
|
- target issue, when applicable
|
|
- rendered GitHub payload
|
|
- source Slack link
|
|
- deterministic `proposal_id`
|
|
- idempotency marker for retry detection
|
|
|
|
#### 4. Execute mutations
|
|
|
|
`execute_github_issue_mutation` is the only **workflow** mutating tool. It has no `confirm` argument. Ad-hoc GitHub writes in chat go through `github_cli`.
|
|
|
|
Mutation behavior:
|
|
|
|
- **create**: searches for the idempotency marker first; creates only if no existing issue is found.
|
|
- **update**: fetches the issue, adds the Slack follow-up as a comment unless the proposal marker is already present, and patches title/labels/assignees only when those fields are explicitly present. It never replaces the issue body.
|
|
- **close**: fetches the issue, adds a closing comment unless the proposal marker is already present, then patches `state=closed` and `state_reason=completed`. It never replaces the issue body.
|
|
|
|
<Warning>
|
|
Do not expose `execute_github_issue_mutation` on investigation surfaces. Investigation and headless runs may render proposals, but should not execute mutations directly.
|
|
</Warning>
|
|
|
|
### Example prompts
|
|
|
|
- "Which PRs are mergeable, blocked, or unknown in `Tracer-Cloud/opensre`?"
|
|
- "What issues are taken vs up for grabs?"
|
|
- "Generate a Slack-ready morning check-in from current GitHub work."
|
|
- "List unanswered community questions from recent issue comments."
|
|
- "Propose a GitHub issue from this Slack request and keep the source link."
|
|
- "Execute this approved GitHub issue proposal."
|
|
|
|
## Verify
|
|
|
|
```bash
|
|
opensre integrations verify github
|
|
```
|
|
|
|
There is no separate `github-workflow` verify target. Workflow tools become available when GitHub credentials validate.
|
|
|
|
## Troubleshooting
|
|
|
|
| Symptom | Fix |
|
|
| --- | --- |
|
|
| **Tools unavailable** | Run `opensre integrations setup github` and verify |
|
|
| **Security alerts error for one class** | Token lacks that alert scope — other alert classes may still return |
|
|
| **False "no blockers" concern** | If report reads fail, expect `available: false` / `incomplete: true` rather than an empty green report |
|
|
| **Mutation not executing** | Headless/non-approved runs can propose only — execute needs the runtime approval path |
|
|
| **Want ad-hoc issue create outside Slack flow** | Use `github_cli` — see [GitHub](/github) |
|
|
|
|
## Security
|
|
|
|
- Keep read tools and mutating execute on separate approval paths.
|
|
- Prefer least-privilege tokens; add security scopes only when you need alert listing.
|
|
- Store tokens in `.env`, not in source control.
|