GIgithub
agent-automations

Run an automation

Changed on

[!NOTE] This endpoint is in public preview and is subject to change.

Runs an automation in a repository. Set event to manual and optionally include context of up to 10,000 characters, which will be injected into the automation's prompt.

The repository must have the "Allow automations" setting enabled, and the automation must be a personal automation belonging to you or a shared automation.

GitHub App installation access tokens can run shared automations. The installation must belong to the repository owner and the token must have "Agent tasks" repository permissions (write). Personal automations require a user token.

A successful response accepts the run request and includes a preallocated task_id, which can be fetched with the "Get a task by repo" Agent tasks API. It does not confirm execution or task creation. Task creation is asynchronous, so fetching the task immediately may return 404 Not Found, and downstream skips or failures can prevent its creation.

To call this endpoint, you must have write access to the repository.

OAuth app tokens and personal access tokens (classic) need:

  • the repo scope for private or internal repositories
  • the repo scope or public_repo scope for public repositories

Fine-grained access tokens for "Run an automation"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

  • "Agent tasks" repository permissions (write)
post/agents/repos/{owner}/{repo}/automations/{automation_id}/tasks

Request

  • Base URL
    https://api.github.com
  • URL
    https://api.github.com/agents/repos/{owner}/{repo}/automations/{automation_id}/tasks
  • Auth
    none declared

Path parameters

ownerstring required

The account owner of the repository. The name is not case sensitive.

repostring required

The name of the repository. The name is not case sensitive.

automation_idstring required

The unique identifier of the automation.

Request body

event'manual' required

The event to trigger. Only manual is supported.

contextstring

Additional context for this automation run, up to 10,000 characters. Supported only when event is manual. The context supplements the automation's configured instructions.

Response

Automation run request accepted for asynchronous processing

task_idstring required

The preallocated ID of the accepted run. The task may not yet be readable, and downstream skips or failures can prevent its creation.

automation_idstring required

The ID of the automation that was triggered.

event'manual' required

The trigger event name, always "manual" for public API runs.

Changes