GitHub API (unofficial showcase)
POST/agents/repos/{owner}/{repo}/automations

Create an automation for a repository

Creates a new automation in a repository. User-owned automations remain private to their creator. Repository-owned automations are visible to anyone with read access to the repository and manageable by anyone with write access to the repository.

Fine-grained access tokens for "Create an automation for a repository"

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

The fine-grained token must have one of the following permission sets for each repository accessed by this request:

  • "Agent tasks" repository permissions (read and write)
  • "Contents" repository permissions (read and write)

The required permission set depends on each repository's Automation permission configuration.

GitHub App installation access tokens are not supported for this endpoint.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

2 parameters · 11 body fields
ownerstringrequired
The account owner of the repository. The name is not case sensitive.
repostringrequired
The name of the repository. The name is not case sensitive.

The automation configuration to create.

namestringrequired
The name of the automation.
triggersobjectoptional
Public trigger configuration keyed by stable public trigger identifier. Each trigger has a closed, trigger-specific configuration schema.
promptstringrequired
The prompt template for the automation.
modelstringoptional
The model to use for sessions triggered by this automation. Omit to use the platform default.
reasoning_effortstringoptional
The reasoning effort to use for sessions triggered by this automation. Omit or leave empty for no override. Currently supported values: `none`, `low`, `medium`, `high`, `xhigh`, `max`
toolsarray<string>optional
The tools available to the automation.
allowed_custom_agentsarray<string>optional
Custom agents (subagents) this automation is allowed to invoke.
enabledbooleanoptional
Whether the automation should be created enabled. Defaults to true when omitted.
Default:true
owner_typestringoptional
Who owns the automation, fixed at creation. `user` keeps it private to its creator and its runs act as that user. `repository` makes it belong to the repository, visible to anyone with read access to the repository and maintainable by anyone with write access to the repository, and its runs act as the Copilot app rather than as a person. `repository` is rejected when repository ownership is not available for the repository. Supported values: `user`, `repository`. Defaults to `user`.
Allowed:userrepositoryDefault:user
write_scopestringoptional
Controls which repository resources a run may modify. `trigger` limits writes to the resource that started the run, when one exists, and resources created during the run; `repository` allows writes to any resource in the repository. Supported values: `trigger`, `repository`.
Allowed:triggerrepositoryDefault:trigger
require_actor_write_permissionbooleanoptional
When true, event-triggered runs require the event actor to have repo write permission, even when the org's allow_read_access_triggers policy is enabled. Does not apply to interval-scheduled runs, which always run as the automation owner. Defaults to false.

6 status codes
201Automation created successfully
idstringrequired
The unique identifier of the automation.
namestringrequired
The name of the automation.
enabledbooleanoptional
Whether the automation is currently enabled.
owner_typestringoptional
Who owns the automation. `user` keeps it private to its creator and its runs act as that user. `repository` makes it belong to the repository, visible to anyone with read access to the repository, and its runs act as the Copilot app rather than as a person.
Allowed:userrepository
write_scopestringoptional
Controls which repository resources a run may modify. `trigger` limits writes to the resource that started the run, when one exists, and resources created during the run; `repository` allows writes to any resource in the repository. Supported values: `trigger`, `repository`.
Allowed:triggerrepositoryDefault:trigger
require_actor_write_permissionbooleanoptional
When true, event-triggered runs require the event actor to have repo write permission, even when the org's allow_read_access_triggers policy is enabled. Does not apply to interval-scheduled runs, which always run as the automation owner.
Default:false
triggersobjectoptional
Public trigger configuration keyed by stable public trigger identifier. Each trigger has a closed, trigger-specific configuration schema.
promptstringrequired
The prompt template for the automation.
toolsarray<string>optional
The tools available to the automation.
allowed_custom_agentsarray<string>optional
Custom agents (subagents) this automation is allowed to invoke.
modelstringoptional
The model to use for sessions triggered by this automation. Omit to use the platform default.
reasoning_effortstringoptional
The reasoning effort to use for sessions triggered by this automation. Omit or leave empty for no override. Currently supported values: `none`, `low`, `medium`, `high`, `xhigh`, `max`
created_atstringrequired
When the automation was created.
updated_atstringrequired
When the automation was last updated.
created_byobjectrequired
A GitHub user
400Bad request
messagestringrequired
Summary message (e.g. "Validation Failed", "Not Found")
errorsarray<object>optional
List of validation errors (present only for 422 responses)
documentation_urlstringrequired
URL to relevant API documentation
401Authentication required
messagestringrequired
Summary message (e.g. "Validation Failed", "Not Found")
errorsarray<object>optional
List of validation errors (present only for 422 responses)
documentation_urlstringrequired
URL to relevant API documentation
403Insufficient permissions
messagestringrequired
Summary message (e.g. "Validation Failed", "Not Found")
errorsarray<object>optional
List of validation errors (present only for 422 responses)
documentation_urlstringrequired
URL to relevant API documentation
404Resource not found
messagestringrequired
Summary message (e.g. "Validation Failed", "Not Found")
errorsarray<object>optional
List of validation errors (present only for 422 responses)
documentation_urlstringrequired
URL to relevant API documentation
422Validation Failed
messagestringrequired
Summary message (e.g. "Validation Failed", "Not Found")
errorsarray<object>optional
List of validation errors (present only for 422 responses)
documentation_urlstringrequired
URL to relevant API documentation

Error handling

A 400 is returned: Bad request. A 401 is returned: Authentication required. A 403 is returned: Insufficient permissions. A 404 is returned: Resource not found. A 422 is returned: Validation Failed.