GitHub: Start a task

← Agent tasks operations · Get started

Operation github.agent_tasks_create_task_in_repo

Provider route: POST /agents/repos/{owner}/{repo}/tasks. 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["agentTasks"]["agentTasksCreateTaskInRepo"]>[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.agentTasks.agentTasksCreateTaskInRepo(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_tasks.agent_tasks_create_task_in_repo(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
body.base_ref	string	Optional	Base ref for new branch/PR
body.create_pull_request	boolean	Optional	Whether to create a PR. Default: false
body.custom_agent	string	Optional	Optional identifier for a custom agent to use for this task. Use the custom agent’s filename without the extension - for example, for a `.github/agents/performance-optimizer.agent.md` custom agent, use `performance-optimizer`.
body.head_ref	string	Optional	Head ref for existing branch/PR. If provided with `base_ref`, the agent looks up open PR context for `head_ref` targeting `base_ref` and commits to `head_ref` instead of creating a new branch.
body.model	string	Optional	The model to use for this task. The allowed models may change over time and depend on the user’s GitHub Copilot plan and organization policies. Currently supported values: `claude-sonnet-4.6`, `claude-opus-4.6`, `gpt-5.2-codex`, `gpt-5.3-codex`, `gpt-5.4`, `claude-sonnet-4.5`, `claude-opus-4.5`
body.prompt	string	Required within parent	The user’s prompt for the agent

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
archived_at	JSON	Optional
archived_at (anyOf 1)	string	Alternative	Timestamp when the task was archived, null if not archived Format: date-time
archived_at (anyOf 2)	null	Alternative
artifacts	array	Optional	Resources created by this task (PRs, branches, etc.)
artifacts[]	Model	Each item	Expand Start a task — response body — artifacts item
created_at	string	Required within parent	Timestamp when the task was created Format: date-time
creator	JSON	Optional	The entity who created this task
creator (anyOf 1)	object	Alternative	A GitHub user
creator (anyOf 1).id	JSON	Optional
creator (anyOf 1).id (anyOf 1)	integer	Alternative	The unique identifier of the user Format: int64
creator (anyOf 1).id (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
creator_type	string	Optional	Type of the task creator Known values: user, organization
custom_agent	object	Optional	Custom agent metadata associated with this task
custom_agent.id	string	Optional	The custom agent’s filename without the extension - for example, `performance-optimizer` for a `.github/agents/performance-optimizer.agent.md` custom agent.
html_url	string	Optional	Web URL for this task
id	string	Required within parent	Unique task identifier
name	string	Optional	Human-readable name derived from the task prompt
owner	object	Optional	The owner of the repository
owner.id	JSON	Optional
owner.id (anyOf 1)	integer	Alternative	The unique identifier of the user Format: int64
owner.id (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
repository	object	Optional	The repository this task belongs to
repository.id	JSON	Optional
repository.id (anyOf 1)	integer	Alternative	The unique identifier of the repository Format: int64
repository.id (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
session_count	JSON	Optional
session_count (anyOf 1)	integer	Alternative	Number of sessions in this task Format: int32
session_count (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
state	string	Required within parent	Current state of the task, derived from its most recent session Known values: queued, in_progress, completed, failed, idle, waiting_for_user, timed_out, cancelled
updated_at	string	Optional	Timestamp of the most recent update Format: date-time
url	string	Optional	API URL for this task
user_collaborators	array	Optional	User objects of collaborators on this task
user_collaborators[]	object	Each item	A GitHub user
user_collaborators[].id	JSON	Optional
user_collaborators[].id (anyOf 1)	integer	Alternative	The unique identifier of the user Format: int64
user_collaborators[].id (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$

Referenced models: Start a task — response body — artifacts item

Schemas

Start a task — response body — artifacts item

Field	Type	Presence	Description and constraints
$	object	Root	A resource generated by the task
data	JSON	Required within parent	Resource data (shape depends on type)
data (anyOf 1)	object	Alternative	A GitHub resource (pull request, issue, etc.)
data (anyOf 1).global_id	string	Optional	GraphQL global ID
data (anyOf 1).id	JSON	Required within parent
data (anyOf 1).id (anyOf 1)	integer	Alternative	GitHub resource ID Format: int64
data (anyOf 1).id (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
data (anyOf 2)	object	Alternative	A Git branch reference
data (anyOf 2).base_ref	string	Required within parent	Base branch name
data (anyOf 2).head_ref	string	Required within parent	Head branch name
provider	string	Required within parent	Provider namespace Known values: github
type	string	Required within parent	Type of artifact. Available Values: `pull`, `branch`. Known values: pull, branch

Policy, approvals and errors

SDK function policy ID: github.agent_tasks_create_task_in_repo. Catalog operation: agent-tasks/create-task-in-repo. 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