tracer-cloud--opensre/docs/github-workflow-tools.mdx

---
title: "GitHub workflow tools"
description: "Use GitHub-backed tools for read snapshots, status reports, follow-up summaries, and approved issue mutations"
---

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 implementation deliberately separates read-only tools from mutating execution. Headless or non-approved runs can produce proposals, but they cannot mutate GitHub.

## 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 mutating tool. It has no `confirm` argument.

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>

## Required GitHub access

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.

## 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."