Skip to main content
Starts a GitHub Actions workflow that has a workflow_dispatch trigger, on the repository’s default branch, with optional inputs. GitHub does not return the run id: find the run with github_list_workflow_runs, then follow it with github_get_workflow_run.

​
Authentication and enablement

Requires a connected native GitHub integration (mcp:github) — a first-party GitHub App connection, not Composio. The connector is shown on Trail and to Nanonets superadmins; it is hidden from Nanonets customers during rollout. Connecting opens GitHub’s install page for the Trail GitHub App, where the user picks the account and either all repositories or only selected ones. Tools act as the app’s bot account through short-lived installation tokens — not as the connecting user — and reach only the repositories of that installation. To change which repositories are included, edit the installation on GitHub (the account’s or organization’s installed GitHub Apps settings) or reconnect. If an organization owner still has to approve the app, calls fail until they do; if the app was uninstalled or suspended, calls fail until GitHub is reconnected. Relies on the app’s Actions (write) permission. This tool changes code or runs CI, so it works only after someone with permission to update connections turns on Allow code changes for the GitHub connection on the connectors page. It is off for every new connection, because code an agent pushes can run in the repository’s CI with the repository’s secrets. Until it is on, calls fail with an error that says so.

​
Inputs

  • owner (required): repository owner (user or organization).
  • repo (required): repository name.
  • workflow (required): workflow file name (e.g. deploy.yml) or numeric id.
  • ref (optional): only the repository’s default branch is accepted; leave it out.
  • inputs (optional): the workflow’s workflow_dispatch inputs, as string values.

​
Output

  • workflow: the workflow requested.
  • ref: the default branch it runs on.
  • message: confirmation that the run was requested; it appears in github_list_workflow_runs within a few seconds.

​
Limits and side effects

  • Writes: starts a real workflow run. Not idempotent — each call starts another run.
  • The run does whatever the workflow does, with the workflow’s own permissions and secrets (for example a deploy).
  • Runs only on the default branch, so a workflow never runs against code an agent pushed to its own branch. inputs are passed as given, though: a workflow that checks out a branch, tag or SHA named in its inputs runs that code, so such workflows are a reason to leave code changes off.
  • owner/repo must be plain GitHub names (letters, numbers, ., _, -); anything else is rejected before any API call.
  • workflow must be a file name or id (letters, numbers, ., _, -).
  • Inputs not declared by the workflow, or missing required inputs, are rejected by GitHub.

​
Expected errors

  • No GitHub connection, a connection still waiting for an organization owner to approve the app, or an app that was uninstalled or suspended (reconnect GitHub).
  • Invalid owner/repo format.
  • Code changes are not turned on for the connection.
  • Invalid workflow, or a ref other than the default branch.
  • Unknown workflow (404).
  • The workflow has no workflow_dispatch trigger, or the inputs do not match (422).
  • GitHub API errors surface as the tool’s error, rewritten to say what to fix: not found or no access to that repository (404), not allowed — missing app permission, protected branch or org policy (403), GitHub refused the change (409/422, with GitHub’s message), the repository is empty (no commits yet, HTTP 409), rate limit reached with the retry time (including GitHub’s secondary limits, which ask for a one-minute wait), rejected app credentials (reconnect).