Add gh run watch guidance for GitHub Actions monitoring by xingyaoww · Pull Request #3 · OpenHands/extensions

xingyaoww · 2025-12-01T18:54:35Z

Summary

This PR updates the GitHub skills documentation to instruct agents to prioritize using gh run watch for monitoring GitHub Actions workflow runs.

Changes

Added guidance in skills/github.md to use gh run watch (https://cli.github.com/manual/gh_run_watch) as the primary method for checking GitHub Actions status
Agents will fallback to basic API calls only if gh run watch is not successful

Context

This change relates to issue #1285 which aims to improve OpenHands' capacity at monitoring async actions like GitHub CI runs. The gh CLI tool is well-known to LLMs and provides a better interface for monitoring workflow runs than polling with basic API calls.

Benefits

Better async monitoring: gh run watch is specifically designed for watching workflow runs until completion
Familiar tool: LLMs have good knowledge of the GitHub CLI
Graceful fallback: Still supports basic API calls as a backup method

Closes #1285 (partial - addresses the GitHub CI monitoring aspect)

Co-authored-by: openhands openhands@all-hands.dev

@xingyaoww can click here to continue refining the PR

Instructs agents to prioritize gh run watch for monitoring GitHub Actions workflow runs, with fallback to basic API calls if needed. Relates to issue #1285 - improving OH capacity at monitoring async actions. Co-authored-by: openhands <openhands@all-hands.dev>

Co-authored-by: Engel Nyst <engel.nyst@gmail.com>

xingyaoww · 2025-12-15T14:31:20Z

Thanks! @enyst

openhands-release-bot · 2026-06-05T17:55:32Z

🚀 Released in v0.1.0.

openhands-release-bot · 2026-06-05T18:48:42Z

🚀 Released in v0.2.0.

openhands-release-bot · 2026-06-10T13:48:46Z

🚀 Released in v0.4.0.

… with v4 base URL) Address AI review #3 (all-hands-bot, CHANGES_REQUESTED on b1ab4e1): the GitLab openApiUrl pointed at the apis.guru v3 Swagger spec while apiBaseUrl is https://gitlab.com/api/v4 — a version mismatch that would generate tools for the wrong API surface. GitLab publishes no official v4 OpenAPI spec (apis.guru only carries v3, and gitlab.com/api/v4/openapi returns 404) and no official MCP server (no gitlab-org MCP repo; only community servers). Per the agreed policy ('if no reliable public OpenAPI spec exists, drop the HTTP option'), and since GitLab has no MCP connection option, the whole GitLab entry is removed. Catalog: 76 -> 75 entries (30 HTTP w/ openApiUrl, 52 MCP, 0 defaultTool).

…connectors (#369) * feat(integrations): remove defaultTool, add openApiUrl, drop no-spec connectors Remove the defaultTool field from the integration catalog and type defs (it is no longer used by integrations-hub or agent-canvas; tools come from MCP tools/list or HTTP OpenAPI regeneration). For every remaining HTTP connection option, add a public openApiUrl so tools can be indexed. Connector changes: - Added openApiUrl to 31 HTTP connectors from official vendor specs or apis.guru (where a vendor publishes no spec of its own). - Removed the HTTP option from airtable and linear (kept their MCP option); linear is GraphQL-only with no REST OpenAPI spec. - Deleted 13 connectors that had only an HTTP option and no public OpenAPI spec: clickup, dropbox, freshdesk, mailchimp, miro, monday, pipedrive, posthog, quickbooks, salesforce, servicenow, shopify, zendesk. - Reordered connectionOptions so MCP comes before HTTP when both exist. - Removed a stray defaultTool from github's mcp oauth option. Type defs: dropped IntegrationHttpDefaultTool and the defaultTool field from IntegrationHttpConfig in integrations/index.d.ts. Validation: catalog sync tests (20) pass; full suite 353 passed (5 pre-existing env failures on main: missing httpx/openhands.sdk). * feat(integrations): recover 7 vendors as MCP connectors; bump to 0.7.0 Seven of the 13 vendors that were dropped (no public OpenAPI spec) publish official MCP servers, so restore them as MCP-only connectors rather than deleting them: - miro: hosted shttp at https://mcp.miro.com/ (OAuth2) - monday: hosted shttp at https://mcp.monday.com/mcp (OAuth2) - posthog: hosted shttp at https://mcp.posthog.com/mcp (Bearer API key) - salesforce: hosted shttp at https://api.salesforce.com/platform/mcp/v1/platform/sobject-reads (urlEditable; OAuth2 with PKCE; edit URL per server/org) - shopify: stdio via `npx -y @shopify/dev-mcp@latest` (no auth; dev docs) - dropbox: stdio via the official dropbox/mcp-server-dash (APP_KEY env) - quickbooks: stdio via the official intuit/quickbooks-online-mcp-server Six vendors remain deleted (no official MCP and no OpenAPI spec): clickup, mailchimp, zendesk, freshdesk, pipedrive, servicenow. Bump version 0.6.0 -> 0.7.0 (package.json, pyproject.toml, _version.py, .release-please-manifest.json) so a release is cut after merge. Catalog now has 76 entries (31 HTTP w/ openApiUrl, 52 MCP, 0 defaultTool). Validation: catalog sync + version alignment tests (23) pass; full suite 353 passed (5 pre-existing env failures unchanged). * fix(integrations): self-contained stdio transports for dropbox/quickbooks; restore original OAuth scopes - dropbox: use `uvx --from git+https://github.com/dropbox/mcp-server-dash` so the server runs without a manual clone (the package has a mcp-server-dash entry point). - quickbooks: use `npx -y github:intuit/quickbooks-online-mcp-server` (the package is not on npm, but npx resolves github: refs); installHint documents the one-time OAuth handshake. - miro/monday: restore the original `boards:read` OAuth scope instead of the broadened `boards:read + boards:write` I had introduced. No catalog-index rebuild needed beyond the two-file content change. * fix(integrations): add urlEditable/headerFields to transport types; encode catalog invariants in tests Address AI review (all-hands-bot, CHANGES_REQUESTED): 1. Type drift: salesforce.json uses urlEditable but IntegrationTransport in index.d.ts did not declare it (nor headerFields, which the field ships alongside in the ahead-of-main package). Add both optional fields to the shttp and sse transport variants, matching the shape already shipped in @openhands/extensions@0.6.0, so downstream TS consumers can use the flag without casts. 2. Testing gap: the 'no defaultTool' and 'every HTTP connector has an openApiUrl' invariants were only checked in the PR description. Add test_no_default_tool_in_catalog and test_http_connectors_have_openapi_url to tests/test_catalogs.py so the catalog contract is enforced in code. 25 catalog/sync/version tests pass (was 23 + 2 new invariants). * fix(integrations): expose QuickBooks OAuth credentials as envFields Address AI review #2 (all-hands-bot, CHANGES_REQUESTED on 1e6e122): the QuickBooks MCP server needs OAuth app credentials plus the refresh token/realm ID, but the entry exposed no way to provide them. Add envFields for QUICKBOOKS_CLIENT_ID (text), QUICKBOOKS_CLIENT_SECRET (password), QUICKBOOKS_REFRESH_TOKEN (password), QUICKBOOKS_REALM_ID (text), and QUICKBOOKS_ENVIRONMENT (optional text). Each password field carries a helperLink per the existing credential-field test. Update installHint to spell out the one-time OAuth handshake. * fix(integrations): remove GitLab HTTP connector (v3 spec incompatible with v4 base URL) Address AI review #3 (all-hands-bot, CHANGES_REQUESTED on b1ab4e1): the GitLab openApiUrl pointed at the apis.guru v3 Swagger spec while apiBaseUrl is https://gitlab.com/api/v4 — a version mismatch that would generate tools for the wrong API surface. GitLab publishes no official v4 OpenAPI spec (apis.guru only carries v3, and gitlab.com/api/v4/openapi returns 404) and no official MCP server (no gitlab-org MCP repo; only community servers). Per the agreed policy ('if no reliable public OpenAPI spec exists, drop the HTTP option'), and since GitLab has no MCP connection option, the whole GitLab entry is removed. Catalog: 76 -> 75 entries (30 HTTP w/ openApiUrl, 52 MCP, 0 defaultTool). * fix(integrations): remove shopify and dropbox (official MCPs are narrower than the HTTP connectors they replaced) Per maintainer decision: Shopify's only official MCP is the Dev MCP (developer docs/schemas, not store operations) and Dropbox's is the Dash search MCP (not full files/folders/sharing). Both are functional downgrades from the HTTP connectors they replaced, so remove them rather than ship a narrower tool under the same name. Catalog: 75 -> 73 entries (30 HTTP w/ openApiUrl, 50 MCP, 0 defaultTool). * feat(integrations): add strict JSON Schema for catalog + validation test; fix invalid entries Add integrations/catalog.schema.json (Draft 2020-12) mirroring integrations/index.d.ts and encoding the cross-field connectability rules the catalog contract depends on, so invalid entries are caught in CI rather than by PR-review: - provider=='http' => http.apiBaseUrl + http.openApiUrl required - provider=='http' + auth.strategy=='oauth2' => auth.oauth with authorizationUrl + tokenUrl required - provider=='http' + auth.strategy=='api_key' => auth.apiKeyHeaderName - provider=='mcp' => transport required; shttp/sse url https; stdio serverName/command/args - password-type envFields/headerFields => helperText required - all URLs must be https://; no additionalProperties anywhere Add tests/test_catalog_schema.py: parametrized per-entry validation (72 entries) plus a self-validity check for the schema. Add jsonschema to the test dependency group. Fix the entries the schema surfaced: - canva: add missing oauth.authorizationUrl - trello: add oauth block (Atlassian OAuth2: auth.atlassian.com / api.atlassian.com); update notes - plaid: delete (special-case token exchange, not generic OAuth2 — cannot be connected via the standard flow) - figma, notion: drop empty-string notes fields Catalog: 73 -> 72 entries (29 HTTP, 50 MCP). 98 catalog/sync/version/ schema tests pass; full suite 428 passed (5 pre-existing env failures). * fix(integrations): enforce provider-discriminated catalog shape; remove stale http block from github mcp option Address AI review #4 (all-hands-bot, CHANGES_REQUESTED on 7ff3789): 1. Data model: github's mcp oauth option still carried a stale `http` block (leftover from defaultTool removal), so provider was no longer a clean discriminator. Remove the http block. 2. Schema coverage: the schema validated the mixed mcp+http shape, so it was not enforcing the invariant this PR depends on. Tighten the connectionOption rules: provider=='mcp' => transport required AND http forbidden; provider=='http' => http required AND transport forbidden. Verified the schema now rejects both mixed-shape regressions. 3. PR description: stale counts/entries updated (72 not 76; plaid/shopify/ dropbox/gitlab removed with reasons; 29 HTTP, 50 MCP). 98 catalog/sync/version/schema tests pass; schema now rejects mcp+http and http+transport mixed shapes. --------- Co-authored-by: openhands <openhands@all-hands.dev>

openhands-ai Bot mentioned this pull request Dec 1, 2025

Evaluate OH capacity at monitoring async actions OpenHands/software-agent-sdk#1285

Closed

xingyaoww marked this pull request as ready for review December 1, 2025 19:02

xingyaoww commented Dec 1, 2025

View reviewed changes

Comment thread skills/github.md Outdated

Apply suggestion from @xingyaoww

7c0f9f0

enyst reviewed Dec 14, 2025

View reviewed changes

Comment thread skills/github.md Outdated

Update skills/github.md

6faafd3

Co-authored-by: Engel Nyst <engel.nyst@gmail.com>

xingyaoww merged commit 0eff9ec into main Dec 15, 2025

all-hands-bot mentioned this pull request Feb 19, 2026

Update PR review workflows to use extensions plugin #61

Merged

openhands-ai Bot mentioned this pull request May 29, 2026

feat: add GitHub Actions skill for workflow creation and debugging #56

Merged

openhands-release-bot Bot added released: 0.1.0 Shipped in v0.1.0 released: 0.2.0 Shipped in v0.2.0 labels Jun 5, 2026

openhands-release-bot Bot added the released: 0.4.0 Shipped in v0.4.0 label Jun 10, 2026

jlav removed released: 0.1.0 Shipped in v0.1.0 released: 0.2.0 Shipped in v0.2.0 released: 0.4.0 Shipped in v0.4.0 labels Jun 11, 2026

This was referenced Sep 12, 2026

feat(factory): compose canonical implementation, review, QA, and guarded merge #557

Closed

feat: delegate ready issues to stable agent subjects #571

Merged

feat: extend PR review with independent acceptance checks #572

Closed

neubig mentioned this pull request Sep 30, 2026

fix(review): let a higher-priority closing issue keep the approval handoff #710

Merged

1 task

Navigation Menu

Repository navigation

Add gh run watch guidance for GitHub Actions monitoring - #3

Add gh run watch guidance for GitHub Actions monitoring#3
xingyaoww merged 3 commits into
mainfrom
openhands/update-github-doc-gh-run-watch

xingyaoww commented Dec 1, 2025

Uh oh!

Uh oh!

Uh oh!

xingyaoww commented Dec 15, 2025

Uh oh!

openhands-release-bot Bot commented Jun 5, 2026

Uh oh!

openhands-release-bot Bot commented Jun 5, 2026

Uh oh!

openhands-release-bot Bot commented Jun 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

xingyaoww commented Dec 1, 2025

Summary

Changes

Context

Benefits

Uh oh!

Uh oh!

Uh oh!

xingyaoww commented Dec 15, 2025

Uh oh!

openhands-release-bot Bot commented Jun 5, 2026

Uh oh!

openhands-release-bot Bot commented Jun 5, 2026

Uh oh!

openhands-release-bot Bot commented Jun 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants