repo_tasks

Creates, updates, deletes, gets or lists a repo_tasks resource.

Overview

Name	repo_tasks
Type	Resource
Id	github.agent_tasks.repo_tasks

Fields

The following fields are returned by SELECT queries:

get_task_by_repo_and_id

Task retrieved successfully

Name	Datatype	Description
id	string	Session ID
name	string	Session name
task_id	string	Task ID this session belongs to
base_ref	string	Base branch name
completed_at	string (date-time)	Completion timestamp
created_at	string (date-time)	Creation timestamp
error	object	Error details for a failed session
head_ref	string	Head branch name
model	string	Model used for this session
owner	object	The owner of the repository
prompt	string	Content of the triggering event
repository	object	The repository this session belongs to
state	string	Current state of a session (queued, in_progress, completed, failed, idle, waiting_for_user, timed_out, cancelled)
updated_at	string (date-time)	Last update timestamp
usage	object	Structured information about billing units consumed by the session.
user	object	The user who created this session

list_tasks_for_repo

Tasks retrieved successfully

Name	Datatype	Description
id	string	Unique task identifier
name	string	Human-readable name derived from the task prompt
archived_at	string (date-time)	Timestamp when the task was archived, null if not archived
artifacts	array	Resources created by this task (PRs, branches, etc.)
created_at	string (date-time)	Timestamp when the task was created
creator		The entity who created this task
creator_type	string	Type of the task creator (user, organization)
custom_agent	object	Custom agent metadata associated with this task
html_url	string	Web URL for this task
owner	object	The owner of the repository
repository	object	The repository this task belongs to
session_count	integer (int32)	Number of sessions in this task
state	string	Current state of the task, derived from its most recent session (queued, in_progress, completed, failed, idle, waiting_for_user, timed_out, cancelled)
updated_at	string (date-time)	Timestamp of the most recent update
url	string	API URL for this task
user_collaborators	array	User objects of collaborators on this task

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_task_by_repo_and_id	select	owner, repo, task_id		> [!NOTE] > This endpoint is in public preview and is subject to change. Returns a task by ID scoped to an owner/repo path Fine-grained access tokens for "Get a task by repo" This endpoint works with the following fine-grained token types: * GitHub App user access tokens * Fine-grained personal access tokens The fine-grained token must have the following permission set: * "Agent tasks" repository permissions (read) GitHub App installation access tokens are not supported for this endpoint.
list_tasks_for_repo	select	owner, repo	per_page, page, sort, direction, state, is_archived, since, creator_id	> [!NOTE] > This endpoint is in public preview and is subject to change. Returns a list of tasks for a specific repository Fine-grained access tokens for "List tasks for repository" This endpoint works with the following fine-grained token types: * GitHub App user access tokens * Fine-grained personal access tokens The fine-grained token must have the following permission set: * "Agent tasks" repository permissions (read) GitHub App installation access tokens are not supported for this endpoint.
create_task_in_repo	insert	owner, repo, prompt		> [!NOTE] > This endpoint is in public preview and is subject to change. Starts a new Copilot cloud agent task for a repository. This endpoint is only available to users with a Copilot Business or Copilot Enterprise subscription. Fine-grained access tokens for "Start a task" This endpoint works with the following fine-grained token types: * GitHub App user access tokens * Fine-grained personal access tokens The fine-grained token must have the following permission set: * "Agent tasks" repository permissions (read and write) GitHub App installation access tokens are not supported for this endpoint.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
owner	string	The account owner of the repository. The name is not case sensitive.
repo	string	The name of the repository. The name is not case sensitive.
task_id	string	The unique identifier of the task.
creator_id	array	Filter tasks by creator user ID. Accepts one or more user IDs.
direction	string	The direction to sort results. Can be asc or desc.
is_archived	boolean	Filter by archived status. When true, returns only archived tasks. When false or omitted, returns only non-archived tasks. Defaults to false.
page	integer	The page number of the results to fetch.
per_page	integer	The number of results per page (max 100).
since	string (date-time)	Only show tasks updated at or after this time (ISO 8601 timestamp)
sort	string	The field to sort results by. Can be updated_at or created_at.
state	string	Comma-separated list of task states to filter by. Can be any combination of: queued, in_progress, completed, failed, idle, waiting_for_user, timed_out, cancelled.

SELECT examples

get_task_by_repo_and_id

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

Returns a task by ID scoped to an owner/repo path

Fine-grained access tokens for "Get a task by repo"

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

* GitHub App user access tokens
* Fine-grained personal access tokens

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

* "Agent tasks" repository permissions (read)

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

SELECT
id,
name,
task_id,
base_ref,
completed_at,
created_at,
error,
head_ref,
model,
owner,
prompt,
repository,
state,
updated_at,
usage,
user
FROM github.agent_tasks.repo_tasks
WHERE owner = '{{ owner }}' -- required
AND repo = '{{ repo }}' -- required
AND task_id = '{{ task_id }}' -- required
;

list_tasks_for_repo

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

Returns a list of tasks for a specific repository

Fine-grained access tokens for "List tasks for repository"

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

* GitHub App user access tokens
* Fine-grained personal access tokens

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

* "Agent tasks" repository permissions (read)

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

SELECT
id,
name,
archived_at,
artifacts,
created_at,
creator,
creator_type,
custom_agent,
html_url,
owner,
repository,
session_count,
state,
updated_at,
url,
user_collaborators
FROM github.agent_tasks.repo_tasks
WHERE owner = '{{ owner }}' -- required
AND repo = '{{ repo }}' -- required
AND per_page = '{{ per_page }}'
AND page = '{{ page }}'
AND sort = '{{ sort }}'
AND direction = '{{ direction }}'
AND state = '{{ state }}'
AND is_archived = '{{ is_archived }}'
AND since = '{{ since }}'
AND creator_id = '{{ creator_id }}'
;

INSERT examples

create_task_in_repo

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

Starts a new Copilot cloud agent task for a repository.

This endpoint is only available to users with a Copilot Business or Copilot Enterprise subscription.

Fine-grained access tokens for "Start a task"

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

* GitHub App user access tokens
* Fine-grained personal access tokens

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

* "Agent tasks" repository permissions (read and write)

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

INSERT INTO github.agent_tasks.repo_tasks (
prompt,
model,
custom_agent,
create_pull_request,
base_ref,
head_ref,
owner,
repo
)
SELECT 
'{{ prompt }}' /* required */,
'{{ model }}',
'{{ custom_agent }}',
{{ create_pull_request }},
'{{ base_ref }}',
'{{ head_ref }}',
'{{ owner }}',
'{{ repo }}'
RETURNING
id,
name,
archived_at,
artifacts,
created_at,
creator,
creator_type,
custom_agent,
html_url,
owner,
repository,
session_count,
state,
updated_at,
url,
user_collaborators
;

Manifest

# Description fields are for documentation purposes
- name: repo_tasks
props:
  - name: owner
    value: "{{ owner }}"
    description: Required parameter for the repo_tasks resource.
  - name: repo
    value: "{{ repo }}"
    description: Required parameter for the repo_tasks resource.
  - name: prompt
    value: "{{ prompt }}"
    description: |
      The user's prompt for the agent
  - name: model
    value: "{{ model }}"
    description: |
      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`
  - name: custom_agent
    value: "{{ custom_agent }}"
    description: |
      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`.
  - name: create_pull_request
    value: {{ create_pull_request }}
    description: |
      Whether to create a PR.
    default: false
  - name: base_ref
    value: "{{ base_ref }}"
    description: |
      Base ref for new branch/PR
  - name: head_ref
    value: "{{ head_ref }}"
    description: |
      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.