Skip to content

Add read-only deployment history tools (list_deployments, list_deployment_statuses) - #3886

Open
Mystery01092000 wants to merge 1 commit into
github:mainfrom
Mystery01092000:feat/deployment-history
Open

Mystery01092000 wants to merge 1 commit into
github:mainfrom
Mystery01092000:feat/deployment-history

Conversation

@Mystery01092000

Copy link
Copy Markdown

Summary

Adds two read-only tools to the repos toolset, list_deployments and list_deployment_statuses. With them an agent can check which commit reached an environment and whether that deployment succeeded.

Why

The issue describes a release audit where the agent could see merged PRs, commits, checks and Actions runs, but not GitHub Deployment objects. Without them it could report what merged, but not whether it was actually deployed. The deployment and deployment_status filters on actions_list only select workflow triggers. They don't read the Deployment records that external deployment services create.

Fixes #3876

What changed

  • list_deployments wraps GET /repos/{owner}/{repo}/deployments. It takes the API's sha, ref, task and environment filters plus page/perPage, and returns id, sha, ref, task, environment, description, creator, created_at and updated_at, newest first.
  • list_deployment_statuses wraps GET /repos/{owner}/{repo}/deployments/{deployment_id}/statuses. It returns id, state, description, environment, environment_url, log_url, creator and the timestamps, newest first, so the first entry is the deployment's current state.
  • I didn't add a separate get-by-ID tool. list_deployments already returns every field the single-deployment endpoint has, so a third tool would mostly add to the tool count. Happy to add it if you'd like the 1:1 mapping from the issue.
  • payload is left out. It's arbitrary JSON that integrations fill with large blobs, and it isn't needed to answer "what's deployed where".
  • Descriptions go through sanitize.PlainText, like release names.
  • A new ifc.LabelDeployment label: untrusted integrity, with confidentiality following repository visibility. Deployments are written by CI and deployment integrations, and on public repositories those often run for fork PRs (preview deployments), so the ref, environment and description can carry outside text. It has the same shape as LabelActionsResult, but has its own name and doc comment so the reasoning stays next to it.
  • The release-preparation skill maps both tools as optional and now notes that merged or released does not mean deployed.
  • Registered in tools.go, with toolsnaps and README regenerated.

MCP impact

  • No tool or API changes
  • Tool schema or behavior changed
  • New tool added: list_deployments and list_deployment_statuses, both read-only.

Prompts tested (tool changes only)

I ran these through the locally built server over stdio with --read-only --toolsets repos, against live GitHub:

  • "Which commit was last deployed to production in vercel/next.js?" list_deployments with environment: Production, perPage: 2 returned deployment 6228410729 for 5b8c866c…, created by vercel[bot], and the one before it.
  • "Did that deployment succeed?" list_deployment_statuses for 6228410729 returned one status with state: failure and Vercel's description and log URL. This is the case the issue is about: the commit was handed to a deployment, but it didn't go live.
  • A non-existent deployment ID returns a tool error carrying GitHub's 404, not a crash.
  • Both tools show up in tools/list in read-only mode.

Security / limits

  • No security or limits impact
  • Auth / permissions considered: both tools use scopes.PublicRead(scopes.Repo), like the release and tag tools, and are read-only, so they are available with --read-only.
  • Data exposure, filtering, or token/size limits considered: paginated (default 30, max 100), payload omitted, free text sanitized, results labelled untrusted.

Tool renaming

  • I am renaming tools as part of this PR (e.g. a part of a consolidation effort)
    • I have added the new tool aliases in deprecated_tool_aliases.go
  • I am not renaming tools as part of this PR

Lint & tests

  • Linted locally with ./script/lint: golangci-lint v2.14.0 reports 0 issues, and gofmt is clean.
  • Tested locally with ./script/test: go test ./... passes. The new tests cover the filters and pagination query string, the no-filter defaults, field mapping, a missing deployment_id, API errors, and the IFC label on public and private repositories.

Docs

  • Not needed
  • Updated (README / docs / examples): README regenerated with generate-docs.

Skills

  • Updated relevant skills or confirmed no bundled skill applies: release-preparation maps both tools and mentions checking the deployed commit.

Add list_deployments and list_deployment_statuses so an agent can check
which commit reached an environment and whether that deployment
succeeded, using GitHub's Deployments API.

list_deployments supports the API's sha, ref, task and environment
filters plus pagination. list_deployment_statuses returns a deployment's
statuses newest first. Both are read-only, live in the repos toolset,
sanitize free-text descriptions and carry an untrusted IFC label, since
deployments are usually written by CI and preview integrations.

Fixes github#3876
@Mystery01092000
Mystery01092000 requested a review from a team as a code owner November 18, 2026 18:50
Copilot AI adaptive review requested due to automatic review settings November 18, 2026 18:50

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The skill and tool guidance can misidentify live deployments by omitting latest-status success verification and failing to limit current-state claims to page 1.

2 open issues
What changed in this PR

Adds read-only deployment history tools to the GitHub MCP Server’s repos toolset, helping release audits distinguish merged or released commits from successful deployments.

Changes:

  • Adds paginated deployment and status readers, with deployment filters and trimmed responses.
  • Labels results as untrusted, with confidentiality based on repository visibility.
  • Adds tests, tool snapshots, generated documentation, and release-preparation skill guidance.
File Description
README.md Documents both tools and their parameters.
pkg/​skills/​catalog/​tools.go Maps both tools to the release-preparation skill.
pkg/​skills/​catalog/​skills/​release-preparation/​SKILL.md Adds deployment verification guidance.
pkg/​ifc/​ifc.go Defines deployment security labels.
pkg/​ifc/​ifc_test.go Tests public and private deployment labels.
pkg/​github/​tools.go Registers both deployment tools.
pkg/​github/​helper_test.go Adds deployment endpoint constants for mocks.
pkg/​github/​deployments.go Implements deployment and status readers.
pkg/​github/​deployments_test.go Tests schemas, responses, filters, errors, and labeling.
pkg/​github/​__toolsnaps__/​list_deployments.snap Captures the deployment-list tool schema.
pkg/​github/​__toolsnaps__/​list_deployment_statuses.snap Captures the deployment-status tool schema.

Review effort: Balanced (adaptive)

Comment thread pkg/github/deployments.go
mcp.Tool{
Name: "list_deployment_statuses",
Description: t("TOOL_LIST_DEPLOYMENT_STATUSES_DESCRIPTION",
"List the statuses of a deployment in a GitHub repository, newest first. The first status is the deployment's current state (e.g. success, failure, error, in_progress, queued, pending or inactive)."),
Comment on lines +70 to +73
- `sha` and `environment` on a deployment, with the newest `state` from
`list_deployment_statuses` — `list_deployments` filtered to the production
environment shows which commit is live now; merged or released does not mean
deployed.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Expose read-only deployment history and deployment statuses

2 participants