GitHub: Create an automation for a repository

← Agent automations operations · Get started

Operation github.agent_automations_create_repo_automation

Provider route: POST /agents/repos/{owner}/{repo}/automations. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/github with npm, or alter-sdk-github with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { GitHubIntegration } from "@alter-ai/github";

async function execute(input: Parameters<GitHubIntegration["agentAutomations"]["agentAutomationsCreateRepoAutomation"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new GitHubIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.agentAutomations.agentAutomationsCreateRepoAutomation(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_github import GitHubIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = GitHubIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.agent_automations.agent_automations_create_repo_automation(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
path	object	Required within parent	Additional keys: not allowed
path.owner	string	Required within parent
path.repo	string	Required within parent
body	object	Required within parent	Request body for creating an automation.
body.continuous_history	boolean	Optional	When true, runs of this automation build on the session history of its previous runs, and runs of the same automation are serialized. Not tracked in revision history. Defaults to false.
body.enabled	boolean	Optional	Whether the automation should be created enabled. Defaults to true when omitted. Default: true
body.model	string	Optional	The model to use for sessions triggered by this automation. Omit or leave empty to let the platform select the model.
body.name	string	Required within parent	The name of the automation.
body.prompt	string	Required within parent	The prompt for the automation. Maximum length: 10000
body.reasoning_effort	JSON	Optional	The reasoning effort to use for sessions triggered by this automation. Omit or leave empty to use the model’s default.
body.reasoning_effort (oneOf 1)	string	Alternative	Maximum length: 0
body.reasoning_effort (oneOf 2)	string	Alternative	One of: none, low, medium, high, xhigh, max
body.require_actor_write_permission	boolean	Optional	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. When policy validation is enabled, explicitly setting false returns 422 if effective organization or repository policy disallows read-access triggers. If omitted, defaults to false when policy permits read-access triggers, otherwise true. The actor requirement does not apply to interval-scheduled runs, which always run as the automation owner.
body.tools	array	Optional	The tools available to the automation.
body.tools[]	string	Each item
body.triggers	Model	Optional	Expand Update an automation — request body — body triggers
body.type	string	Optional	The type of automation, fixed at creation. `personal` keeps it private to its creator and its runs act as that user. `shared` 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. `shared` is rejected when repository ownership is not available for the repository. Supported values: `personal`, `shared`. Defaults to `personal`. Default: personal One of: personal, shared

Referenced models: Update an automation — request body — body triggers

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	object	Root	A full representation of an automation including all configuration fields.
continuous_history	boolean	Optional	When true, runs of this automation build on the session history of its previous runs, and runs of the same automation are serialized. Not tracked in revision history. Default: false
created_at	string	Required within parent	When the automation was created. Format: date-time
created_by	object	Required within parent	A GitHub user
created_by.id	JSON	Optional
created_by.id (anyOf 1)	integer	Alternative	The unique identifier of the user Format: int64
created_by.id (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
enabled	boolean	Optional	Whether the automation is currently enabled.
id	string	Required within parent	The unique identifier of the automation.
model	string	Optional	The model override for sessions triggered by this automation. Absent when the platform selects the model.
name	string	Required within parent	The name of the automation.
prompt	string	Required within parent	The prompt for the automation.
reasoning_effort	string	Optional	The reasoning effort override for sessions triggered by this automation. Absent when the model’s default is used.
require_actor_write_permission	boolean	Optional	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
tools	array	Optional	The tools available to the automation.
tools[]	string	Each item
triggers	Model	Optional	Expand Get an automation — response body — triggers
type	string	Optional	The type of automation. `personal` keeps it private to its creator and its runs act as that user. `shared` 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. Known values: personal, shared Read only: true
updated_at	string	Required within parent	When the automation was last updated. Format: date-time

Referenced models: Get an automation — response body — triggers

Schemas

31 more schemas are linked from the tables above, on the schema pages.

Update an automation — request body — body triggers

Field	Type	Presence	Description and constraints
$	object	Root	Trigger configuration for the automation. Additional keys: not allowed
automation_completed	Model	Optional	Expand Update an automation — request body — body triggers automation completed
automation_failed	Model	Optional	Expand Update an automation — request body — body triggers automation failed
code_scanning_alert	Model	Optional	Expand Update an automation — request body — body triggers dependabot alert
dependabot_alert	Model	Optional	Expand Update an automation — request body — body triggers dependabot alert
discussion_comment	Model	Optional	Expand Update an automation — request body — body triggers discussion comment
discussion_opened	Model	Optional	Expand Update an automation — request body — body triggers discussion opened
discussion_updated	Model	Optional	Expand Update an automation — request body — body triggers discussion opened
interval	Model	Optional	Expand Update an automation — request body — body triggers interval
issue_assigned	Model	Optional	Expand Update an automation — request body — body triggers issue assigned
issue_closed	Model	Optional	Expand Update an automation — request body — body triggers issue closed
issue_comment	Model	Optional	Expand Update an automation — request body — body triggers issue comment
issue_labeled	Model	Optional	Expand Update an automation — request body — body triggers issue labeled
issue_opened	Model	Optional	Expand Update an automation — request body — body triggers issue closed
issue_reopened	Model	Optional	Expand Update an automation — request body — body triggers issue closed
pull_request_assigned	Model	Optional	Expand Update an automation — request body — body triggers pull request assigned
pull_request_closed	Model	Optional	Expand Update an automation — request body — body triggers pull request closed
pull_request_comment	Model	Optional	Expand Update an automation — request body — body triggers pull request comment
pull_request_converted_to_draft	Model	Optional	Expand Update an automation — request body — body triggers pull request closed
pull_request_labeled	Model	Optional	Expand Update an automation — request body — body triggers pull request labeled
pull_request_merge_conflict	Model	Optional	Expand Update an automation — request body — body triggers pull request closed
pull_request_merged	Model	Optional	Expand Update an automation — request body — body triggers pull request closed
pull_request_opened	Model	Optional	Expand Update an automation — request body — body triggers pull request closed
pull_request_ready_for_review	Model	Optional	Expand Update an automation — request body — body triggers pull request closed
pull_request_reopened	Model	Optional	Expand Update an automation — request body — body triggers pull request closed
pull_request_review_dismissed	Model	Optional	Expand Update an automation — request body — body triggers pull request closed
pull_request_review_requested	Model	Optional	Expand Update an automation — request body — body triggers pull request closed
pull_request_review_submitted	Model	Optional	Expand Update an automation — request body — body triggers pull request review submitted
pull_request_review_thread_resolved	Model	Optional	Expand Update an automation — request body — body triggers pull request closed
pull_request_review_thread_unresolved	Model	Optional	Expand Update an automation — request body — body triggers pull request closed
pull_request_synchronize	Model	Optional	Expand Update an automation — request body — body triggers pull request closed
secret_scanning_alert	Model	Optional	Expand Update an automation — request body — body triggers dependabot alert
sub_issue_added	Model	Optional	Expand Update an automation — request body — body triggers issue closed
workflow_run	Model	Optional	Expand Update an automation — request body — body triggers workflow run

Referenced models: Update an automation — request body — body triggers automation completed, Update an automation — request body — body triggers automation failed, Update an automation — request body — body triggers dependabot alert, Update an automation — request body — body triggers discussion comment, Update an automation — request body — body triggers discussion opened, Update an automation — request body — body triggers interval, Update an automation — request body — body triggers issue assigned, Update an automation — request body — body triggers issue closed, Update an automation — request body — body triggers issue comment, Update an automation — request body — body triggers issue labeled, Update an automation — request body — body triggers pull request assigned, Update an automation — request body — body triggers pull request closed, Update an automation — request body — body triggers pull request comment, Update an automation — request body — body triggers pull request labeled, Update an automation — request body — body triggers pull request review submitted, Update an automation — request body — body triggers workflow run

Update an automation — request body — body triggers automation completed

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
allow_copilot_triggers	boolean	Optional	When true, events Copilot creates, including from other automations and Copilot sessions, can start this automation through this trigger. Defaults to false. The Copilot coding agent app cannot turn it on: creating a trigger with true, or changing it from false to true, returns 422.
automation_ids	array	Required within parent	Upstream Automation IDs in the same repository. Maximum items: 3 Minimum items: 1 Unique items: true
automation_ids[]	string	Each item
write_scope	string	Optional	Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Explicitly setting `repository` on create or edit returns 422 when policy validation is enabled and that policy applies. One of: trigger, repository

Update an automation — request body — body triggers dependabot alert

Field	Type	Presence	Description and constraints
$	object	Root	Runs on the default branch when a security alert of this kind is created in the repository. These are system events without an issue, pull request, or human actor, and cannot be run manually. Additional keys: not allowed
allow_copilot_triggers	boolean	Optional	When true, events Copilot creates, including from other automations and Copilot sessions, can start this automation through this trigger. Defaults to false. The Copilot coding agent app cannot turn it on: creating a trigger with true, or changing it from false to true, returns 422.
write_scope	string	Optional	Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Explicitly setting `repository` on create or edit returns 422 when policy validation is enabled and that policy applies. One of: trigger, repository

Policy, approvals and errors

SDK function policy ID: github.agent_automations_create_repo_automation. Catalog operation: agent-automations/create-repo-automation. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Pinned headers: {"X-GitHub-Api-Version": "2026-03-10", "User-Agent": "Alter", "Accept": "application/vnd.github+json"}

Official provider source