Skip to main content

​
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.

​
Prerequisites

  • GitHub connected via GitHub integration
  • 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.

​
Example REPL turn

​
Credentials

Connect or reconnect GitHub in the OpenSRE app. 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.

​
Tools

​
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.
Do not expose execute_github_issue_mutation outside the runtime approval path. Headless runs may render proposals, but should not execute mutations directly.

​
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

There is no separate github-workflow verify target. Workflow tools become available when GitHub credentials validate.

​
Troubleshooting

​
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.