diff --git a/descriptions/api.github.com/api.github.com.2022-11-28.json b/descriptions/api.github.com/api.github.com.2022-11-28.json index a545ddaf3..d8b39387c 100644 --- a/descriptions/api.github.com/api.github.com.2022-11-28.json +++ b/descriptions/api.github.com/api.github.com.2022-11-28.json @@ -530,6 +530,3164 @@ } } }, + "/agents/repos/{owner}/{repo}/tasks": { + "get": { + "summary": "List tasks for repository", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for a specific repository\n\n**Fine-grained access tokens for \"List tasks for repository\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks-for-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks-for-repository" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "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`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + }, + { + "name": "creator_id", + "in": "query", + "schema": { + "type": "integer" + }, + "description": "Filter tasks by creator user ID" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"prev\" (when current page > 1),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + }, + "post": { + "summary": "Start a task", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nStarts a new Copilot cloud agent task for a repository.\n\nThis endpoint is only available to users with a Copilot Business or Copilot Enterprise subscription.\n\n**Fine-grained access tokens for \"Start a task\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read and write)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/create-task-in-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#start-a-task" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + } + ], + "requestBody": { + "required": true, + "description": "The task creation parameters, including the user's prompt and optional agent settings.", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "prompt" + ], + "properties": { + "prompt": { + "type": "string", + "description": "The user's prompt for the agent" + }, + "model": { + "type": "string", + "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`" + }, + "create_pull_request": { + "type": "boolean", + "description": "Whether to create a PR.", + "default": false + }, + "base_ref": { + "type": "string", + "description": "Base ref for new branch/PR" + } + } + }, + "examples": { + "default": { + "value": { + "prompt": "Fix the login button on the homepage", + "base_ref": "main" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Task created successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "examples": { + "default": { + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "queued", + "session_count": 1, + "artifacts": [], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T00:00:00Z" + } + } + } + } + } + }, + "400": { + "description": "Problems parsing JSON", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/repos/{owner}/{repo}/tasks/{task_id}": { + "get": { + "summary": "Get a task by repo", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID scoped to an owner/repo path\n\n**Fine-grained access tokens for \"Get a task by repo\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-repo-and-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-repo" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks": { + "get": { + "summary": "List tasks", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for the authenticated user\n\n**Fine-grained access tokens for \"List tasks\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "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`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks/{task_id}": { + "get": { + "summary": "Get a task by ID", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID with its associated sessions\n\n**Fine-grained access tokens for \"Get a task by ID\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-id" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Problems parsing request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, "/app": { "get": { "summary": "Get the authenticated app", @@ -27964,7 +31122,7 @@ }, "post": { "summary": "Create a private registry for an organization", - "description": "\nCreates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", + "description": "\nCreates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", "tags": [ "private-registries" ], @@ -28047,7 +31205,387 @@ } }, "auth_type": { - "description": "The authentication type for the private registry. Defaults to `token` if not specified. Use `oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith` for OIDC authentication.", + "description": "The authentication type for the private registry. Defaults to `token` if not specified. Use `oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp` for OIDC authentication.", + "type": "string", + "enum": [ + "token", + "username_password", + "oidc_azure", + "oidc_aws", + "oidc_jfrog", + "oidc_cloudsmith", + "oidc_gcp" + ] + }, + "tenant_id": { + "description": "The tenant ID of the Azure AD application. Required when `auth_type` is `oidc_azure`.", + "type": "string" + }, + "client_id": { + "description": "The client ID of the Azure AD application. Required when `auth_type` is `oidc_azure`.", + "type": "string" + }, + "aws_region": { + "description": "The AWS region. Required when `auth_type` is `oidc_aws`.", + "type": "string" + }, + "account_id": { + "description": "The AWS account ID. Required when `auth_type` is `oidc_aws`.", + "type": "string" + }, + "role_name": { + "description": "The AWS IAM role name. Required when `auth_type` is `oidc_aws`.", + "type": "string" + }, + "domain": { + "description": "The CodeArtifact domain. Required when `auth_type` is `oidc_aws`.", + "type": "string" + }, + "domain_owner": { + "description": "The CodeArtifact domain owner (AWS account ID). Required when `auth_type` is `oidc_aws`.", + "type": "string" + }, + "jfrog_oidc_provider_name": { + "description": "The JFrog OIDC provider name. Required when `auth_type` is `oidc_jfrog`.", + "type": "string" + }, + "audience": { + "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and `oidc_gcp`, and required for `oidc_cloudsmith` auth types.", + "type": "string" + }, + "identity_mapping_name": { + "description": "The JFrog identity mapping name. Optional for `oidc_jfrog` auth type.", + "type": "string" + }, + "namespace": { + "description": "The Cloudsmith organization namespace. Required when `auth_type` is `oidc_cloudsmith`.", + "type": "string" + }, + "service_slug": { + "description": "The Cloudsmith service account slug. Required when `auth_type` is `oidc_cloudsmith`.", + "type": "string" + }, + "api_host": { + "description": "The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default.", + "type": "string" + }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). Required when `auth_type` is `oidc_gcp`.", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. Optional for `oidc_gcp` auth type. If omitted, the federated token is used directly (direct WIF).", + "type": "string" + } + }, + "required": [ + "registry_type", + "url", + "visibility" + ] + }, + "examples": { + "org-private-registry-with-private-visibility": { + "summary": "Example of a private registry configuration with private visibility", + "value": { + "registry_type": "maven_repository", + "url": "https://maven.pkg.github.com/organization/", + "username": "monalisa", + "replaces_base": true, + "encrypted_value": "c2VjcmV0", + "key_id": "012345678912345678", + "visibility": "private" + } + }, + "org-private-registry-with-selected-visibility": { + "summary": "Example of a private registry configuration with selected visibility", + "value": { + "registry_type": "maven_repository", + "url": "https://maven.pkg.github.com/organization/", + "username": "monalisa", + "encrypted_value": "c2VjcmV0", + "key_id": "012345678912345678", + "visibility": "selected", + "selected_repository_ids": [ + 1296269, + 1296280 + ] + } + }, + "org-private-registry-with-oidc-azure": { + "summary": "Example of an OIDC private registry configuration using Azure", + "value": { + "registry_type": "docker_registry", + "url": "https://myregistry.azurecr.io", + "auth_type": "oidc_azure", + "visibility": "all", + "tenant_id": "12345678-1234-1234-1234-123456789012", + "client_id": "abcdef01-2345-6789-abcd-ef0123456789" + } + }, + "org-private-registry-with-oidc-cloudsmith": { + "summary": "Example of an OIDC private registry configuration using Cloudsmith", + "value": { + "registry_type": "npm_registry", + "url": "https://npm.cloudsmith.io/my-org/my-repo/", + "auth_type": "oidc_cloudsmith", + "visibility": "all", + "namespace": "my-org", + "service_slug": "my-service-account", + "audience": "https://github.com/my-org" + } + }, + "org-private-registry-with-oidc-gcp": { + "summary": "Example of an OIDC private registry configuration using Google Cloud Artifact Registry", + "value": { + "registry_type": "docker_registry", + "url": "https://us-docker.pkg.dev/my-project/my-repo", + "auth_type": "oidc_gcp", + "visibility": "all", + "workload_identity_provider": "projects/123456789/locations/global/workloadIdentityPools/github-pool/providers/github-provider", + "service_account": "dependabot@my-project.iam.gserviceaccount.com" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "The organization private registry configuration", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/org-private-registry-configuration-with-selected-repositories" + }, + "examples": { + "org-private-registry-with-selected-visibility": { + "$ref": "#/components/examples/org-private-registry-configuration" + }, + "org-private-registry-with-private-visibility": { + "$ref": "#/components/examples/org-private-registry-configuration-with-selected-repositories" + } + } + } + } + }, + "404": { + "$ref": "#/components/responses/not_found" + }, + "422": { + "$ref": "#/components/responses/validation_failed" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "private-registries", + "subcategory": "organization-configurations" + } + } + }, + "/orgs/{org}/private-registries/public-key": { + "get": { + "summary": "Get private registries public key for an organization", + "description": "\nGets the org public key, which is needed to encrypt private registry secrets. You need to encrypt a secret before you can create or update secrets.\n\nOAuth tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", + "tags": [ + "private-registries" + ], + "operationId": "private-registries/get-org-public-key", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization" + }, + "parameters": [ + { + "$ref": "#/components/parameters/org" + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "key_id", + "key" + ], + "properties": { + "key_id": { + "description": "The identifier for the key.", + "example": "012345678912345678", + "type": "string" + }, + "key": { + "description": "The Base64 encoded public key.", + "example": "2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234", + "type": "string" + } + } + }, + "examples": { + "default": { + "$ref": "#/components/examples/private-registries-public-key" + } + } + } + }, + "headers": { + "Link": { + "$ref": "#/components/headers/link" + } + } + }, + "404": { + "$ref": "#/components/responses/not_found" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "private-registries", + "subcategory": "organization-configurations" + } + } + }, + "/orgs/{org}/private-registries/{secret_name}": { + "get": { + "summary": "Get a private registry for an organization", + "description": "\nGet the configuration of a single private registry defined for an organization, omitting its encrypted value.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", + "tags": [ + "private-registries" + ], + "operationId": "private-registries/get-org-private-registry", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/private-registries/organization-configurations#get-a-private-registry-for-an-organization" + }, + "parameters": [ + { + "$ref": "#/components/parameters/org" + }, + { + "$ref": "#/components/parameters/secret-name" + } + ], + "responses": { + "200": { + "description": "The specified private registry configuration for the organization", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/org-private-registry-configuration" + }, + "examples": { + "default": { + "$ref": "#/components/examples/org-private-registry-configuration" + } + } + } + } + }, + "404": { + "$ref": "#/components/responses/not_found" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "private-registries", + "subcategory": "organization-configurations" + } + }, + "patch": { + "summary": "Update a private registry for an organization", + "description": "\nUpdates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", + "tags": [ + "private-registries" + ], + "operationId": "private-registries/update-org-private-registry", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/private-registries/organization-configurations#update-a-private-registry-for-an-organization" + }, + "parameters": [ + { + "$ref": "#/components/parameters/org" + }, + { + "$ref": "#/components/parameters/secret-name" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "registry_type": { + "description": "The registry type.", + "type": "string", + "enum": [ + "maven_repository", + "nuget_feed", + "goproxy_server", + "npm_registry", + "rubygems_server", + "cargo_registry", + "composer_repository", + "docker_registry", + "git_source", + "helm_registry", + "hex_organization", + "hex_repository", + "pub_repository", + "python_index", + "terraform_registry" + ] + }, + "url": { + "description": "The URL of the private registry.", + "type": "string", + "format": "uri" + }, + "username": { + "description": "The username to use when authenticating with the private registry. This field should be omitted if the private registry does not require a username for authentication.", + "type": "string", + "nullable": true + }, + "replaces_base": { + "description": "Whether this private registry should replace the base registry (e.g., npmjs.org for npm, rubygems.org for rubygems). When set to `true`, Dependabot will only use this registry and will not fall back to the public registry. When set to `false` (default), Dependabot will use this registry for scoped packages but may fall back to the public registry for other packages.", + "type": "boolean", + "default": false + }, + "encrypted_value": { + "description": "The value for your secret, encrypted with [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages) using the public key retrieved from the [Get private registries public key for an organization](https://docs.github.com/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization) endpoint.", + "type": "string", + "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{4})$" + }, + "key_id": { + "description": "The ID of the key you used to encrypt the secret.", + "type": "string" + }, + "visibility": { + "description": "Which type of organization repositories have access to the private registry. `selected` means only the repositories specified by `selected_repository_ids` can access the private registry.", + "type": "string", + "enum": [ + "all", + "private", + "selected" + ] + }, + "selected_repository_ids": { + "description": "An array of repository IDs that can access the organization private registry. You can only provide a list of repository IDs when `visibility` is set to `selected`. This field should be omitted if `visibility` is set to `all` or `private`.", + "type": "array", + "items": { + "type": "integer" + } + }, + "auth_type": { + "description": "The authentication type for the private registry. This field cannot be changed after creation. If provided, it must match the existing `auth_type` of the configuration. To change the authentication type, delete and recreate the configuration.", "type": "string", "enum": [ "token", @@ -28055,7 +31593,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ] }, "tenant_id": { @@ -28091,7 +31630,7 @@ "type": "string" }, "audience": { - "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and required for `oidc_cloudsmith` auth types.", + "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and `oidc_gcp`, and required for `oidc_cloudsmith` auth types.", "type": "string" }, "identity_mapping_name": { @@ -28109,365 +31648,13 @@ "api_host": { "description": "The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default.", "type": "string" - } - }, - "required": [ - "registry_type", - "url", - "visibility" - ] - }, - "examples": { - "org-private-registry-with-private-visibility": { - "summary": "Example of a private registry configuration with private visibility", - "value": { - "registry_type": "maven_repository", - "url": "https://maven.pkg.github.com/organization/", - "username": "monalisa", - "replaces_base": true, - "encrypted_value": "c2VjcmV0", - "key_id": "012345678912345678", - "visibility": "private" - } - }, - "org-private-registry-with-selected-visibility": { - "summary": "Example of a private registry configuration with selected visibility", - "value": { - "registry_type": "maven_repository", - "url": "https://maven.pkg.github.com/organization/", - "username": "monalisa", - "encrypted_value": "c2VjcmV0", - "key_id": "012345678912345678", - "visibility": "selected", - "selected_repository_ids": [ - 1296269, - 1296280 - ] - } - }, - "org-private-registry-with-oidc-azure": { - "summary": "Example of an OIDC private registry configuration using Azure", - "value": { - "registry_type": "docker_registry", - "url": "https://myregistry.azurecr.io", - "auth_type": "oidc_azure", - "visibility": "all", - "tenant_id": "12345678-1234-1234-1234-123456789012", - "client_id": "abcdef01-2345-6789-abcd-ef0123456789" - } - }, - "org-private-registry-with-oidc-cloudsmith": { - "summary": "Example of an OIDC private registry configuration using Cloudsmith", - "value": { - "registry_type": "npm_registry", - "url": "https://npm.cloudsmith.io/my-org/my-repo/", - "auth_type": "oidc_cloudsmith", - "visibility": "all", - "namespace": "my-org", - "service_slug": "my-service-account", - "audience": "https://github.com/my-org" - } - } - } - } - } - }, - "responses": { - "201": { - "description": "The organization private registry configuration", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/org-private-registry-configuration-with-selected-repositories" - }, - "examples": { - "org-private-registry-with-selected-visibility": { - "$ref": "#/components/examples/org-private-registry-configuration" }, - "org-private-registry-with-private-visibility": { - "$ref": "#/components/examples/org-private-registry-configuration-with-selected-repositories" - } - } - } - } - }, - "404": { - "$ref": "#/components/responses/not_found" - }, - "422": { - "$ref": "#/components/responses/validation_failed" - } - }, - "x-github": { - "githubCloudOnly": false, - "enabledForGitHubApps": true, - "category": "private-registries", - "subcategory": "organization-configurations" - } - } - }, - "/orgs/{org}/private-registries/public-key": { - "get": { - "summary": "Get private registries public key for an organization", - "description": "\nGets the org public key, which is needed to encrypt private registry secrets. You need to encrypt a secret before you can create or update secrets.\n\nOAuth tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", - "tags": [ - "private-registries" - ], - "operationId": "private-registries/get-org-public-key", - "externalDocs": { - "description": "API method documentation", - "url": "https://docs.github.com/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization" - }, - "parameters": [ - { - "$ref": "#/components/parameters/org" - } - ], - "responses": { - "200": { - "description": "Response", - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "key_id", - "key" - ], - "properties": { - "key_id": { - "description": "The identifier for the key.", - "example": "012345678912345678", - "type": "string" - }, - "key": { - "description": "The Base64 encoded public key.", - "example": "2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234", - "type": "string" - } - } - }, - "examples": { - "default": { - "$ref": "#/components/examples/private-registries-public-key" - } - } - } - }, - "headers": { - "Link": { - "$ref": "#/components/headers/link" - } - } - }, - "404": { - "$ref": "#/components/responses/not_found" - } - }, - "x-github": { - "githubCloudOnly": false, - "enabledForGitHubApps": true, - "category": "private-registries", - "subcategory": "organization-configurations" - } - } - }, - "/orgs/{org}/private-registries/{secret_name}": { - "get": { - "summary": "Get a private registry for an organization", - "description": "\nGet the configuration of a single private registry defined for an organization, omitting its encrypted value.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", - "tags": [ - "private-registries" - ], - "operationId": "private-registries/get-org-private-registry", - "externalDocs": { - "description": "API method documentation", - "url": "https://docs.github.com/rest/private-registries/organization-configurations#get-a-private-registry-for-an-organization" - }, - "parameters": [ - { - "$ref": "#/components/parameters/org" - }, - { - "$ref": "#/components/parameters/secret-name" - } - ], - "responses": { - "200": { - "description": "The specified private registry configuration for the organization", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/org-private-registry-configuration" - }, - "examples": { - "default": { - "$ref": "#/components/examples/org-private-registry-configuration" - } - } - } - } - }, - "404": { - "$ref": "#/components/responses/not_found" - } - }, - "x-github": { - "githubCloudOnly": false, - "enabledForGitHubApps": true, - "category": "private-registries", - "subcategory": "organization-configurations" - } - }, - "patch": { - "summary": "Update a private registry for an organization", - "description": "\nUpdates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", - "tags": [ - "private-registries" - ], - "operationId": "private-registries/update-org-private-registry", - "externalDocs": { - "description": "API method documentation", - "url": "https://docs.github.com/rest/private-registries/organization-configurations#update-a-private-registry-for-an-organization" - }, - "parameters": [ - { - "$ref": "#/components/parameters/org" - }, - { - "$ref": "#/components/parameters/secret-name" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "registry_type": { - "description": "The registry type.", - "type": "string", - "enum": [ - "maven_repository", - "nuget_feed", - "goproxy_server", - "npm_registry", - "rubygems_server", - "cargo_registry", - "composer_repository", - "docker_registry", - "git_source", - "helm_registry", - "hex_organization", - "hex_repository", - "pub_repository", - "python_index", - "terraform_registry" - ] - }, - "url": { - "description": "The URL of the private registry.", - "type": "string", - "format": "uri" - }, - "username": { - "description": "The username to use when authenticating with the private registry. This field should be omitted if the private registry does not require a username for authentication.", - "type": "string", - "nullable": true - }, - "replaces_base": { - "description": "Whether this private registry should replace the base registry (e.g., npmjs.org for npm, rubygems.org for rubygems). When set to `true`, Dependabot will only use this registry and will not fall back to the public registry. When set to `false` (default), Dependabot will use this registry for scoped packages but may fall back to the public registry for other packages.", - "type": "boolean", - "default": false - }, - "encrypted_value": { - "description": "The value for your secret, encrypted with [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages) using the public key retrieved from the [Get private registries public key for an organization](https://docs.github.com/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization) endpoint.", - "type": "string", - "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{4})$" - }, - "key_id": { - "description": "The ID of the key you used to encrypt the secret.", - "type": "string" - }, - "visibility": { - "description": "Which type of organization repositories have access to the private registry. `selected` means only the repositories specified by `selected_repository_ids` can access the private registry.", - "type": "string", - "enum": [ - "all", - "private", - "selected" - ] - }, - "selected_repository_ids": { - "description": "An array of repository IDs that can access the organization private registry. You can only provide a list of repository IDs when `visibility` is set to `selected`. This field should be omitted if `visibility` is set to `all` or `private`.", - "type": "array", - "items": { - "type": "integer" - } - }, - "auth_type": { - "description": "The authentication type for the private registry. This field cannot be changed after creation. If provided, it must match the existing `auth_type` of the configuration. To change the authentication type, delete and recreate the configuration.", - "type": "string", - "enum": [ - "token", - "username_password", - "oidc_azure", - "oidc_aws", - "oidc_jfrog", - "oidc_cloudsmith" - ] - }, - "tenant_id": { - "description": "The tenant ID of the Azure AD application. Required when `auth_type` is `oidc_azure`.", - "type": "string" - }, - "client_id": { - "description": "The client ID of the Azure AD application. Required when `auth_type` is `oidc_azure`.", - "type": "string" - }, - "aws_region": { - "description": "The AWS region. Required when `auth_type` is `oidc_aws`.", - "type": "string" - }, - "account_id": { - "description": "The AWS account ID. Required when `auth_type` is `oidc_aws`.", - "type": "string" - }, - "role_name": { - "description": "The AWS IAM role name. Required when `auth_type` is `oidc_aws`.", + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). Required when `auth_type` is `oidc_gcp`.", "type": "string" }, - "domain": { - "description": "The CodeArtifact domain. Required when `auth_type` is `oidc_aws`.", - "type": "string" - }, - "domain_owner": { - "description": "The CodeArtifact domain owner (AWS account ID). Required when `auth_type` is `oidc_aws`.", - "type": "string" - }, - "jfrog_oidc_provider_name": { - "description": "The JFrog OIDC provider name. Required when `auth_type` is `oidc_jfrog`.", - "type": "string" - }, - "audience": { - "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and required for `oidc_cloudsmith` auth types.", - "type": "string" - }, - "identity_mapping_name": { - "description": "The JFrog identity mapping name. Optional for `oidc_jfrog` auth type.", - "type": "string" - }, - "namespace": { - "description": "The Cloudsmith organization namespace. Required when `auth_type` is `oidc_cloudsmith`.", - "type": "string" - }, - "service_slug": { - "description": "The Cloudsmith service account slug. Required when `auth_type` is `oidc_cloudsmith`.", - "type": "string" - }, - "api_host": { - "description": "The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default.", + "service_account": { + "description": "The GCP service account email to impersonate. Optional for `oidc_gcp` auth type. If omitted, the federated token is used directly (direct WIF).", "type": "string" } } @@ -35066,6 +38253,139 @@ } } }, + "/repos/{owner}/{repo}/actions/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a repository", + "description": "Lists the active concurrency groups for a repository.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository" + }, + "parameters": [ + { + "$ref": "#/components/parameters/owner" + }, + { + "$ref": "#/components/parameters/repo" + }, + { + "$ref": "#/components/parameters/per-page" + }, + { + "$ref": "#/components/parameters/pagination-after" + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/concurrency-group-list" + }, + "examples": { + "default": { + "$ref": "#/components/examples/concurrency-group-list" + } + } + } + }, + "headers": { + "Link": { + "$ref": "#/components/headers/link" + } + } + }, + "422": { + "$ref": "#/components/responses/validation_failed" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": { + "get": { + "summary": "Get a concurrency group for a repository", + "description": "Gets a specific concurrency group for a repository, including all instances in the group's queue.\nReturns 404 if the group is inactive or does not exist.\n\nOptionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items\nahead of the specified workflow run or job in the queue, plus the specified item itself\n(returned as the last element). This is useful for determining what is blocking a particular\nrun or job. Returns 422 if the specified run or job is not in this concurrency group.\n\nWhen using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow\nleases held on behalf of that run. Job-level leases within the run are not considered to\nblock the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow\nleases on the job's ancestor paths.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/get-concurrency-group-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository" + }, + "parameters": [ + { + "$ref": "#/components/parameters/owner" + }, + { + "$ref": "#/components/parameters/repo" + }, + { + "$ref": "#/components/parameters/concurrency-group-name" + }, + { + "name": "ahead_of_run", + "description": "Filter to items ahead of this workflow run ID in the queue, plus the run itself.\nMatches workflow-level concurrency and reusable-workflow leases held on behalf of\nthe run. Mutually exclusive with `ahead_of_job`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + }, + { + "name": "ahead_of_job", + "description": "Filter to items ahead of this job ID in the queue, plus the job itself.\nMatches job-level concurrency and reusable-workflow leases on the job's\nancestor paths. Mutually exclusive with `ahead_of_run`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/concurrency-group" + }, + "examples": { + "default": { + "$ref": "#/components/examples/concurrency-group" + } + } + } + } + }, + "404": { + "$ref": "#/components/responses/not_found" + }, + "422": { + "$ref": "#/components/responses/validation_failed" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/jobs/{job_id}": { "get": { "summary": "Get a job for a workflow run", @@ -37477,6 +40797,74 @@ } } }, + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a workflow run", + "description": "Lists all concurrency groups associated with a workflow run or its jobs.\n\nThe set of groups is derived from the run's configuration, so a group is\nincluded even when the run no longer has any items currently holding or\nwaiting in it. In that case the `group_members` array will be empty.\n`total_count` reflects the number of groups the run participates in by\nconfiguration, not the number with active items.\n\nThis differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`,\nwhich returns 404 when a group has no active items. That endpoint reports\nthe live state of a group repo-wide, while this endpoint reports the\ngroups associated with a specific run by configuration.\n\nResults are sorted by group name and support cursor-based pagination via\n`before` and `after`. The `after` cursor paginates forward only and does\nnot emit a `rel=\"prev\"` Link; use `before` to page backward from a\nforward page's `next` cursor.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-workflow-run", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run" + }, + "parameters": [ + { + "$ref": "#/components/parameters/owner" + }, + { + "$ref": "#/components/parameters/repo" + }, + { + "$ref": "#/components/parameters/run-id" + }, + { + "$ref": "#/components/parameters/per-page" + }, + { + "$ref": "#/components/parameters/pagination-before" + }, + { + "$ref": "#/components/parameters/pagination-after" + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/concurrency-group-run-list" + }, + "examples": { + "default": { + "$ref": "#/components/examples/concurrency-group-run-list" + } + } + } + }, + "headers": { + "Link": { + "$ref": "#/components/headers/link" + } + } + }, + "404": { + "$ref": "#/components/responses/not_found" + }, + "422": { + "$ref": "#/components/responses/validation_failed" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": { "post": { "summary": "Review custom deployment protection rules for a workflow run", @@ -122005,7 +125393,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ], "type": "string" }, @@ -122086,6 +125475,14 @@ "description": "The Cloudsmith API host.", "type": "string" }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`).", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. If omitted, the federated token is used directly (direct WIF).", + "type": "string" + }, "created_at": { "type": "string", "format": "date-time" @@ -122142,7 +125539,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ], "type": "string" }, @@ -122229,6 +125627,14 @@ "description": "The Cloudsmith API host.", "type": "string" }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`).", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. If omitted, the federated token is used directly (direct WIF).", + "type": "string" + }, "created_at": { "type": "string", "format": "date-time" @@ -128912,6 +132318,134 @@ "actions_caches" ] }, + "concurrency-group-list": { + "title": "Concurrency Group List", + "description": "A list of active concurrency groups for a repository.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer" + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "last_acquired_at" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "last_acquired_at": { + "type": "string", + "format": "date-time", + "nullable": true + } + } + } + } + } + }, + "concurrency-group": { + "title": "Concurrency Group", + "description": "A concurrency group with the workflow runs and jobs that are either currently holding\nor waiting for the concurrency group lease.", + "type": "object", + "required": [ + "group_name", + "group_url", + "total_count", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "total_count": { + "type": "integer" + }, + "group_members": { + "type": "array", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": "string", + "format": "uri", + "description": "API URL for the workflow run.", + "nullable": true + }, + "run_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the workflow run.", + "nullable": true + }, + "job_id": { + "type": "integer", + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_name": { + "type": "string", + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_url": { + "type": "string", + "format": "uri", + "description": "API URL for the job.", + "nullable": true + }, + "job_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the job.", + "nullable": true + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + }, "job": { "title": "Job", "description": "Information of a job execution in a workflow run", @@ -129646,6 +133180,119 @@ "comment" ] }, + "concurrency-group-run-list": { + "title": "Concurrency Group Run List", + "description": "A list of concurrency groups associated with a workflow run.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer", + "description": "The total number of concurrency groups this workflow run participates in,\nderived from the run's configuration. This count is not filtered by\nwhether the run currently holds or is waiting in each group, so it can\ninclude groups whose `group_members` array is empty (for example, when\nthe run has already released its lease in that group)." + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group. May return 404 if the group\nhas no active items at the time it is requested, since the\nget-by-name endpoint reports the live repo-wide state of a group\nwhile this endpoint lists groups associated with a run by\nconfiguration." + }, + "group_members": { + "type": "array", + "description": "Items belonging to this workflow run that are either currently holding or\nwaiting for the concurrency group lease. May be empty if the run no\nlonger has any active or queued items in this group.", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status", + "position", + "position_url" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": "string", + "format": "uri", + "description": "API URL for the workflow run.", + "nullable": true + }, + "run_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the workflow run.", + "nullable": true + }, + "position": { + "type": "integer", + "description": "Queue position. 0 means the item holds the concurrency lease (in_progress), 1 or higher means queued (pending)." + }, + "position_url": { + "type": "string", + "format": "uri", + "description": "API URL to get items ahead of this item in the concurrency group." + }, + "job_id": { + "type": "integer", + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease.", + "nullable": true + }, + "job_name": { + "type": "string", + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease.", + "nullable": true + }, + "job_url": { + "type": "string", + "format": "uri", + "description": "API URL for the job.", + "nullable": true + }, + "job_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the job.", + "nullable": true + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + } + } + } + }, "review-custom-gates-comment-required": { "type": "object", "properties": { @@ -303317,6 +306964,57 @@ ] } }, + "concurrency-group-list": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "last_acquired_at": "2026-01-15T16:14:23Z" + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "last_acquired_at": "2026-01-15T16:13:55Z" + } + ] + } + }, + "concurrency-group": { + "value": { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "total_count": 3, + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress" + }, + { + "run_id": 30433643, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433643", + "status": "pending" + }, + { + "run_id": 30433644, + "run_name": "Deploy hotfix", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644", + "job_id": 798245260, + "job_name": "deploy", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260", + "status": "pending" + } + ] + } + }, "job": { "value": { "id": 399444496, @@ -304105,6 +307803,47 @@ ] } }, + "concurrency-group-run-list": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress", + "position": 0, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642" + } + ] + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "pending", + "position": 2, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260", + "job_id": 798245260, + "job_name": "build", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260" + } + ] + } + ] + } + }, "pending-deployment-items": { "value": [ { @@ -324239,6 +327978,15 @@ "type": "integer" } }, + "concurrency-group-name": { + "name": "concurrency_group_name", + "description": "The name of the concurrency group.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, "job-id": { "name": "job_id", "description": "The unique identifier of the job.", diff --git a/descriptions/api.github.com/api.github.com.2022-11-28.yaml b/descriptions/api.github.com/api.github.com.2022-11-28.yaml index c1277e1db..c78a037f7 100644 --- a/descriptions/api.github.com/api.github.com.2022-11-28.yaml +++ b/descriptions/api.github.com/api.github.com.2022-11-28.yaml @@ -343,6 +343,2525 @@ paths: enabledForGitHubApps: true category: security-advisories subcategory: global-advisories + "/agents/repos/{owner}/{repo}/tasks": + get: + summary: List tasks for repository + description: | + > [!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](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks-for-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks-for-repository + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: '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`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + - name: creator_id + in: query + schema: + type: integer + description: Filter tasks by creator user ID + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="prev" (when current page > 1), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; + rel="next", ; + rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + post: + summary: Start a task + description: | + > [!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](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/create-task-in-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#start-a-task + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + requestBody: + required: true + description: The task creation parameters, including the user's prompt and + optional agent settings. + content: + application/json: + schema: + type: object + required: + - prompt + properties: + prompt: + type: string + description: The user's prompt for the agent + model: + type: string + 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`' + create_pull_request: + type: boolean + description: Whether to create a PR. + default: false + base_ref: + type: string + description: Base ref for new branch/PR + examples: + default: + value: + prompt: Fix the login button on the homepage + base_ref: main + responses: + '201': + description: Task created successfully + content: + application/json: + schema: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + examples: + default: + value: + id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: queued + session_count: 1 + artifacts: [] + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T00:00:00Z' + '400': + description: Problems parsing JSON + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/repos/{owner}/{repo}/tasks/{task_id}": + get: + summary: Get a task by repo + description: | + > [!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](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-repo-and-id + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-repo + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks": + get: + summary: List tasks + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a list of tasks for the authenticated user + + **Fine-grained access tokens for "List tasks"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: '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`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; rel="next", + ; rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks/{task_id}": + get: + summary: Get a task by ID + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a task by ID with its associated sessions + + **Fine-grained access tokens for "Get a task by ID"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-id + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-id + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Problems parsing request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation "/app": get: summary: Get the authenticated app @@ -20417,7 +22936,7 @@ paths: description: |2- Creates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see "[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api)." - For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted. + For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted. OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. tags: @@ -20510,7 +23029,332 @@ paths: auth_type: description: The authentication type for the private registry. Defaults to `token` if not specified. Use `oidc_azure`, `oidc_aws`, `oidc_jfrog`, - or `oidc_cloudsmith` for OIDC authentication. + `oidc_cloudsmith`, or `oidc_gcp` for OIDC authentication. + type: string + enum: + - token + - username_password + - oidc_azure + - oidc_aws + - oidc_jfrog + - oidc_cloudsmith + - oidc_gcp + tenant_id: + description: The tenant ID of the Azure AD application. Required + when `auth_type` is `oidc_azure`. + type: string + client_id: + description: The client ID of the Azure AD application. Required + when `auth_type` is `oidc_azure`. + type: string + aws_region: + description: The AWS region. Required when `auth_type` is `oidc_aws`. + type: string + account_id: + description: The AWS account ID. Required when `auth_type` is `oidc_aws`. + type: string + role_name: + description: The AWS IAM role name. Required when `auth_type` is + `oidc_aws`. + type: string + domain: + description: The CodeArtifact domain. Required when `auth_type` + is `oidc_aws`. + type: string + domain_owner: + description: The CodeArtifact domain owner (AWS account ID). Required + when `auth_type` is `oidc_aws`. + type: string + jfrog_oidc_provider_name: + description: The JFrog OIDC provider name. Required when `auth_type` + is `oidc_jfrog`. + type: string + audience: + description: The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, + and `oidc_gcp`, and required for `oidc_cloudsmith` auth types. + type: string + identity_mapping_name: + description: The JFrog identity mapping name. Optional for `oidc_jfrog` + auth type. + type: string + namespace: + description: The Cloudsmith organization namespace. Required when + `auth_type` is `oidc_cloudsmith`. + type: string + service_slug: + description: The Cloudsmith service account slug. Required when + `auth_type` is `oidc_cloudsmith`. + type: string + api_host: + description: The Cloudsmith API host. Optional for `oidc_cloudsmith` + auth type. If omitted, `api.cloudsmith.io` is used by default. + type: string + workload_identity_provider: + description: The full resource name of the GCP Workload Identity + Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + Required when `auth_type` is `oidc_gcp`. + type: string + service_account: + description: The GCP service account email to impersonate. Optional + for `oidc_gcp` auth type. If omitted, the federated token is used + directly (direct WIF). + type: string + required: + - registry_type + - url + - visibility + examples: + org-private-registry-with-private-visibility: + summary: Example of a private registry configuration with private + visibility + value: + registry_type: maven_repository + url: https://maven.pkg.github.com/organization/ + username: monalisa + replaces_base: true + encrypted_value: c2VjcmV0 + key_id: '012345678912345678' + visibility: private + org-private-registry-with-selected-visibility: + summary: Example of a private registry configuration with selected + visibility + value: + registry_type: maven_repository + url: https://maven.pkg.github.com/organization/ + username: monalisa + encrypted_value: c2VjcmV0 + key_id: '012345678912345678' + visibility: selected + selected_repository_ids: + - 1296269 + - 1296280 + org-private-registry-with-oidc-azure: + summary: Example of an OIDC private registry configuration using Azure + value: + registry_type: docker_registry + url: https://myregistry.azurecr.io + auth_type: oidc_azure + visibility: all + tenant_id: 12345678-1234-1234-1234-123456789012 + client_id: abcdef01-2345-6789-abcd-ef0123456789 + org-private-registry-with-oidc-cloudsmith: + summary: Example of an OIDC private registry configuration using Cloudsmith + value: + registry_type: npm_registry + url: https://npm.cloudsmith.io/my-org/my-repo/ + auth_type: oidc_cloudsmith + visibility: all + namespace: my-org + service_slug: my-service-account + audience: https://github.com/my-org + org-private-registry-with-oidc-gcp: + summary: Example of an OIDC private registry configuration using Google + Cloud Artifact Registry + value: + registry_type: docker_registry + url: https://us-docker.pkg.dev/my-project/my-repo + auth_type: oidc_gcp + visibility: all + workload_identity_provider: projects/123456789/locations/global/workloadIdentityPools/github-pool/providers/github-provider + service_account: dependabot@my-project.iam.gserviceaccount.com + responses: + '201': + description: The organization private registry configuration + content: + application/json: + schema: + "$ref": "#/components/schemas/org-private-registry-configuration-with-selected-repositories" + examples: + org-private-registry-with-selected-visibility: + "$ref": "#/components/examples/org-private-registry-configuration" + org-private-registry-with-private-visibility: + "$ref": "#/components/examples/org-private-registry-configuration-with-selected-repositories" + '404': + "$ref": "#/components/responses/not_found" + '422': + "$ref": "#/components/responses/validation_failed" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: private-registries + subcategory: organization-configurations + "/orgs/{org}/private-registries/public-key": + get: + summary: Get private registries public key for an organization + description: |2- + + Gets the org public key, which is needed to encrypt private registry secrets. You need to encrypt a secret before you can create or update secrets. + + OAuth tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. + tags: + - private-registries + operationId: private-registries/get-org-public-key + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization + parameters: + - "$ref": "#/components/parameters/org" + responses: + '200': + description: Response + content: + application/json: + schema: + type: object + required: + - key_id + - key + properties: + key_id: + description: The identifier for the key. + example: '012345678912345678' + type: string + key: + description: The Base64 encoded public key. + example: 2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234 + type: string + examples: + default: + "$ref": "#/components/examples/private-registries-public-key" + headers: + Link: + "$ref": "#/components/headers/link" + '404': + "$ref": "#/components/responses/not_found" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: private-registries + subcategory: organization-configurations + "/orgs/{org}/private-registries/{secret_name}": + get: + summary: Get a private registry for an organization + description: |2- + + Get the configuration of a single private registry defined for an organization, omitting its encrypted value. + + OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. + tags: + - private-registries + operationId: private-registries/get-org-private-registry + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/private-registries/organization-configurations#get-a-private-registry-for-an-organization + parameters: + - "$ref": "#/components/parameters/org" + - "$ref": "#/components/parameters/secret-name" + responses: + '200': + description: The specified private registry configuration for the organization + content: + application/json: + schema: + "$ref": "#/components/schemas/org-private-registry-configuration" + examples: + default: + "$ref": "#/components/examples/org-private-registry-configuration" + '404': + "$ref": "#/components/responses/not_found" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: private-registries + subcategory: organization-configurations + patch: + summary: Update a private registry for an organization + description: |2- + + Updates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see "[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api)." + For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted. + + OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. + tags: + - private-registries + operationId: private-registries/update-org-private-registry + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/private-registries/organization-configurations#update-a-private-registry-for-an-organization + parameters: + - "$ref": "#/components/parameters/org" + - "$ref": "#/components/parameters/secret-name" + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + registry_type: + description: The registry type. + type: string + enum: + - maven_repository + - nuget_feed + - goproxy_server + - npm_registry + - rubygems_server + - cargo_registry + - composer_repository + - docker_registry + - git_source + - helm_registry + - hex_organization + - hex_repository + - pub_repository + - python_index + - terraform_registry + url: + description: The URL of the private registry. + type: string + format: uri + username: + description: The username to use when authenticating with the private + registry. This field should be omitted if the private registry + does not require a username for authentication. + type: string + nullable: true + replaces_base: + description: Whether this private registry should replace the base + registry (e.g., npmjs.org for npm, rubygems.org for rubygems). + When set to `true`, Dependabot will only use this registry and + will not fall back to the public registry. When set to `false` + (default), Dependabot will use this registry for scoped packages + but may fall back to the public registry for other packages. + type: boolean + default: false + encrypted_value: + description: The value for your secret, encrypted with [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages) + using the public key retrieved from the [Get private registries + public key for an organization](https://docs.github.com/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization) + endpoint. + type: string + pattern: "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{4})$" + key_id: + description: The ID of the key you used to encrypt the secret. + type: string + visibility: + description: Which type of organization repositories have access + to the private registry. `selected` means only the repositories + specified by `selected_repository_ids` can access the private + registry. + type: string + enum: + - all + - private + - selected + selected_repository_ids: + description: An array of repository IDs that can access the organization + private registry. You can only provide a list of repository IDs + when `visibility` is set to `selected`. This field should be omitted + if `visibility` is set to `all` or `private`. + type: array + items: + type: integer + auth_type: + description: The authentication type for the private registry. This + field cannot be changed after creation. If provided, it must match + the existing `auth_type` of the configuration. To change the authentication + type, delete and recreate the configuration. type: string enum: - token @@ -20519,6 +23363,7 @@ paths: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp tenant_id: description: The tenant ID of the Azure AD application. Required when `auth_type` is `oidc_azure`. @@ -20551,7 +23396,7 @@ paths: type: string audience: description: The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, - and required for `oidc_cloudsmith` auth types. + and `oidc_gcp`, and required for `oidc_cloudsmith` auth types. type: string identity_mapping_name: description: The JFrog identity mapping name. Optional for `oidc_jfrog` @@ -20569,309 +23414,15 @@ paths: description: The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default. type: string - required: - - registry_type - - url - - visibility - examples: - org-private-registry-with-private-visibility: - summary: Example of a private registry configuration with private - visibility - value: - registry_type: maven_repository - url: https://maven.pkg.github.com/organization/ - username: monalisa - replaces_base: true - encrypted_value: c2VjcmV0 - key_id: '012345678912345678' - visibility: private - org-private-registry-with-selected-visibility: - summary: Example of a private registry configuration with selected - visibility - value: - registry_type: maven_repository - url: https://maven.pkg.github.com/organization/ - username: monalisa - encrypted_value: c2VjcmV0 - key_id: '012345678912345678' - visibility: selected - selected_repository_ids: - - 1296269 - - 1296280 - org-private-registry-with-oidc-azure: - summary: Example of an OIDC private registry configuration using Azure - value: - registry_type: docker_registry - url: https://myregistry.azurecr.io - auth_type: oidc_azure - visibility: all - tenant_id: 12345678-1234-1234-1234-123456789012 - client_id: abcdef01-2345-6789-abcd-ef0123456789 - org-private-registry-with-oidc-cloudsmith: - summary: Example of an OIDC private registry configuration using Cloudsmith - value: - registry_type: npm_registry - url: https://npm.cloudsmith.io/my-org/my-repo/ - auth_type: oidc_cloudsmith - visibility: all - namespace: my-org - service_slug: my-service-account - audience: https://github.com/my-org - responses: - '201': - description: The organization private registry configuration - content: - application/json: - schema: - "$ref": "#/components/schemas/org-private-registry-configuration-with-selected-repositories" - examples: - org-private-registry-with-selected-visibility: - "$ref": "#/components/examples/org-private-registry-configuration" - org-private-registry-with-private-visibility: - "$ref": "#/components/examples/org-private-registry-configuration-with-selected-repositories" - '404': - "$ref": "#/components/responses/not_found" - '422': - "$ref": "#/components/responses/validation_failed" - x-github: - githubCloudOnly: false - enabledForGitHubApps: true - category: private-registries - subcategory: organization-configurations - "/orgs/{org}/private-registries/public-key": - get: - summary: Get private registries public key for an organization - description: |2- - - Gets the org public key, which is needed to encrypt private registry secrets. You need to encrypt a secret before you can create or update secrets. - - OAuth tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. - tags: - - private-registries - operationId: private-registries/get-org-public-key - externalDocs: - description: API method documentation - url: https://docs.github.com/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization - parameters: - - "$ref": "#/components/parameters/org" - responses: - '200': - description: Response - content: - application/json: - schema: - type: object - required: - - key_id - - key - properties: - key_id: - description: The identifier for the key. - example: '012345678912345678' - type: string - key: - description: The Base64 encoded public key. - example: 2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234 - type: string - examples: - default: - "$ref": "#/components/examples/private-registries-public-key" - headers: - Link: - "$ref": "#/components/headers/link" - '404': - "$ref": "#/components/responses/not_found" - x-github: - githubCloudOnly: false - enabledForGitHubApps: true - category: private-registries - subcategory: organization-configurations - "/orgs/{org}/private-registries/{secret_name}": - get: - summary: Get a private registry for an organization - description: |2- - - Get the configuration of a single private registry defined for an organization, omitting its encrypted value. - - OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. - tags: - - private-registries - operationId: private-registries/get-org-private-registry - externalDocs: - description: API method documentation - url: https://docs.github.com/rest/private-registries/organization-configurations#get-a-private-registry-for-an-organization - parameters: - - "$ref": "#/components/parameters/org" - - "$ref": "#/components/parameters/secret-name" - responses: - '200': - description: The specified private registry configuration for the organization - content: - application/json: - schema: - "$ref": "#/components/schemas/org-private-registry-configuration" - examples: - default: - "$ref": "#/components/examples/org-private-registry-configuration" - '404': - "$ref": "#/components/responses/not_found" - x-github: - githubCloudOnly: false - enabledForGitHubApps: true - category: private-registries - subcategory: organization-configurations - patch: - summary: Update a private registry for an organization - description: |2- - - Updates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see "[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api)." - For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted. - - OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. - tags: - - private-registries - operationId: private-registries/update-org-private-registry - externalDocs: - description: API method documentation - url: https://docs.github.com/rest/private-registries/organization-configurations#update-a-private-registry-for-an-organization - parameters: - - "$ref": "#/components/parameters/org" - - "$ref": "#/components/parameters/secret-name" - requestBody: - required: true - content: - application/json: - schema: - type: object - properties: - registry_type: - description: The registry type. - type: string - enum: - - maven_repository - - nuget_feed - - goproxy_server - - npm_registry - - rubygems_server - - cargo_registry - - composer_repository - - docker_registry - - git_source - - helm_registry - - hex_organization - - hex_repository - - pub_repository - - python_index - - terraform_registry - url: - description: The URL of the private registry. - type: string - format: uri - username: - description: The username to use when authenticating with the private - registry. This field should be omitted if the private registry - does not require a username for authentication. - type: string - nullable: true - replaces_base: - description: Whether this private registry should replace the base - registry (e.g., npmjs.org for npm, rubygems.org for rubygems). - When set to `true`, Dependabot will only use this registry and - will not fall back to the public registry. When set to `false` - (default), Dependabot will use this registry for scoped packages - but may fall back to the public registry for other packages. - type: boolean - default: false - encrypted_value: - description: The value for your secret, encrypted with [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages) - using the public key retrieved from the [Get private registries - public key for an organization](https://docs.github.com/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization) - endpoint. - type: string - pattern: "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{4})$" - key_id: - description: The ID of the key you used to encrypt the secret. - type: string - visibility: - description: Which type of organization repositories have access - to the private registry. `selected` means only the repositories - specified by `selected_repository_ids` can access the private - registry. - type: string - enum: - - all - - private - - selected - selected_repository_ids: - description: An array of repository IDs that can access the organization - private registry. You can only provide a list of repository IDs - when `visibility` is set to `selected`. This field should be omitted - if `visibility` is set to `all` or `private`. - type: array - items: - type: integer - auth_type: - description: The authentication type for the private registry. This - field cannot be changed after creation. If provided, it must match - the existing `auth_type` of the configuration. To change the authentication - type, delete and recreate the configuration. + workload_identity_provider: + description: The full resource name of the GCP Workload Identity + Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + Required when `auth_type` is `oidc_gcp`. type: string - enum: - - token - - username_password - - oidc_azure - - oidc_aws - - oidc_jfrog - - oidc_cloudsmith - tenant_id: - description: The tenant ID of the Azure AD application. Required - when `auth_type` is `oidc_azure`. - type: string - client_id: - description: The client ID of the Azure AD application. Required - when `auth_type` is `oidc_azure`. - type: string - aws_region: - description: The AWS region. Required when `auth_type` is `oidc_aws`. - type: string - account_id: - description: The AWS account ID. Required when `auth_type` is `oidc_aws`. - type: string - role_name: - description: The AWS IAM role name. Required when `auth_type` is - `oidc_aws`. - type: string - domain: - description: The CodeArtifact domain. Required when `auth_type` - is `oidc_aws`. - type: string - domain_owner: - description: The CodeArtifact domain owner (AWS account ID). Required - when `auth_type` is `oidc_aws`. - type: string - jfrog_oidc_provider_name: - description: The JFrog OIDC provider name. Required when `auth_type` - is `oidc_jfrog`. - type: string - audience: - description: The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, - and required for `oidc_cloudsmith` auth types. - type: string - identity_mapping_name: - description: The JFrog identity mapping name. Optional for `oidc_jfrog` - auth type. - type: string - namespace: - description: The Cloudsmith organization namespace. Required when - `auth_type` is `oidc_cloudsmith`. - type: string - service_slug: - description: The Cloudsmith service account slug. Required when - `auth_type` is `oidc_cloudsmith`. - type: string - api_host: - description: The Cloudsmith API host. Optional for `oidc_cloudsmith` - auth type. If omitted, `api.cloudsmith.io` is used by default. + service_account: + description: The GCP service account email to impersonate. Optional + for `oidc_gcp` auth type. If omitted, the federated token is used + directly (direct WIF). type: string examples: secret-based-update: @@ -25646,6 +28197,111 @@ paths: enabledForGitHubApps: true category: actions subcategory: cache + "/repos/{owner}/{repo}/actions/concurrency_groups": + get: + summary: List concurrency groups for a repository + description: |- + Lists the active concurrency groups for a repository. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository + parameters: + - "$ref": "#/components/parameters/owner" + - "$ref": "#/components/parameters/repo" + - "$ref": "#/components/parameters/per-page" + - "$ref": "#/components/parameters/pagination-after" + responses: + '200': + description: Response + content: + application/json: + schema: + "$ref": "#/components/schemas/concurrency-group-list" + examples: + default: + "$ref": "#/components/examples/concurrency-group-list" + headers: + Link: + "$ref": "#/components/headers/link" + '422': + "$ref": "#/components/responses/validation_failed" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": + get: + summary: Get a concurrency group for a repository + description: |- + Gets a specific concurrency group for a repository, including all instances in the group's queue. + Returns 404 if the group is inactive or does not exist. + + Optionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items + ahead of the specified workflow run or job in the queue, plus the specified item itself + (returned as the last element). This is useful for determining what is blocking a particular + run or job. Returns 422 if the specified run or job is not in this concurrency group. + + When using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow + leases held on behalf of that run. Job-level leases within the run are not considered to + block the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow + leases on the job's ancestor paths. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/get-concurrency-group-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository + parameters: + - "$ref": "#/components/parameters/owner" + - "$ref": "#/components/parameters/repo" + - "$ref": "#/components/parameters/concurrency-group-name" + - name: ahead_of_run + description: |- + Filter to items ahead of this workflow run ID in the queue, plus the run itself. + Matches workflow-level concurrency and reusable-workflow leases held on behalf of + the run. Mutually exclusive with `ahead_of_job`. + in: query + required: false + schema: + type: integer + minimum: 1 + - name: ahead_of_job + description: |- + Filter to items ahead of this job ID in the queue, plus the job itself. + Matches job-level concurrency and reusable-workflow leases on the job's + ancestor paths. Mutually exclusive with `ahead_of_run`. + in: query + required: false + schema: + type: integer + minimum: 1 + responses: + '200': + description: Response + content: + application/json: + schema: + "$ref": "#/components/schemas/concurrency-group" + examples: + default: + "$ref": "#/components/examples/concurrency-group" + '404': + "$ref": "#/components/responses/not_found" + '422': + "$ref": "#/components/responses/validation_failed" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/jobs/{job_id}": get: summary: Get a job for a workflow run @@ -27347,6 +30003,64 @@ paths: enabledForGitHubApps: true category: actions subcategory: workflow-runs + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": + get: + summary: List concurrency groups for a workflow run + description: |- + Lists all concurrency groups associated with a workflow run or its jobs. + + The set of groups is derived from the run's configuration, so a group is + included even when the run no longer has any items currently holding or + waiting in it. In that case the `group_members` array will be empty. + `total_count` reflects the number of groups the run participates in by + configuration, not the number with active items. + + This differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`, + which returns 404 when a group has no active items. That endpoint reports + the live state of a group repo-wide, while this endpoint reports the + groups associated with a specific run by configuration. + + Results are sorted by group name and support cursor-based pagination via + `before` and `after`. The `after` cursor paginates forward only and does + not emit a `rel="prev"` Link; use `before` to page backward from a + forward page's `next` cursor. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-workflow-run + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run + parameters: + - "$ref": "#/components/parameters/owner" + - "$ref": "#/components/parameters/repo" + - "$ref": "#/components/parameters/run-id" + - "$ref": "#/components/parameters/per-page" + - "$ref": "#/components/parameters/pagination-before" + - "$ref": "#/components/parameters/pagination-after" + responses: + '200': + description: Response + content: + application/json: + schema: + "$ref": "#/components/schemas/concurrency-group-run-list" + examples: + default: + "$ref": "#/components/examples/concurrency-group-run-list" + headers: + Link: + "$ref": "#/components/headers/link" + '404': + "$ref": "#/components/responses/not_found" + '422': + "$ref": "#/components/responses/validation_failed" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": post: summary: Review custom deployment protection rules for a workflow run @@ -89433,6 +92147,7 @@ components: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp type: string url: description: The URL of the private registry. @@ -89498,6 +92213,14 @@ components: api_host: description: The Cloudsmith API host. type: string + workload_identity_provider: + description: The full resource name of the GCP Workload Identity Provider + (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + type: string + service_account: + description: The GCP service account email to impersonate. If omitted, the + federated token is used directly (direct WIF). + type: string created_at: type: string format: date-time @@ -89547,6 +92270,7 @@ components: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp type: string url: description: The URL of the private registry. @@ -89618,6 +92342,14 @@ components: api_host: description: The Cloudsmith API host. type: string + workload_identity_provider: + description: The full resource name of the GCP Workload Identity Provider + (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + type: string + service_account: + description: The GCP service account email to impersonate. If omitted, the + federated token is used directly (direct WIF). + type: string created_at: type: string format: date-time @@ -94838,6 +97570,107 @@ components: required: - total_count - actions_caches + concurrency-group-list: + title: Concurrency Group List + description: A list of active concurrency groups for a repository. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - last_acquired_at + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + last_acquired_at: + type: string + format: date-time + nullable: true + concurrency-group: + title: Concurrency Group + description: |- + A concurrency group with the workflow runs and jobs that are either currently holding + or waiting for the concurrency group lease. + type: object + required: + - group_name + - group_url + - total_count + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + total_count: + type: integer + group_members: + type: array + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: string + format: uri + description: API URL for the workflow run. + nullable: true + run_html_url: + type: string + format: uri + description: Web URL for the workflow run. + nullable: true + job_id: + type: integer + description: The ID of the job, when the item represents a job-level + or reusable-workflow-level lease. + job_name: + type: string + description: The display name of the job, when the item represents + a job-level or reusable-workflow-level lease. + job_url: + type: string + format: uri + description: API URL for the job. + nullable: true + job_html_url: + type: string + format: uri + description: Web URL for the job. + nullable: true + status: + type: string + enum: + - in_progress + - pending job: title: Job description: Information of a job execution in a workflow run @@ -95444,6 +98277,110 @@ components: - state - user - comment + concurrency-group-run-list: + title: Concurrency Group Run List + description: A list of concurrency groups associated with a workflow run. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + description: |- + The total number of concurrency groups this workflow run participates in, + derived from the run's configuration. This count is not filtered by + whether the run currently holds or is waiting in each group, so it can + include groups whose `group_members` array is empty (for example, when + the run has already released its lease in that group). + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: |- + API URL for this concurrency group. May return 404 if the group + has no active items at the time it is requested, since the + get-by-name endpoint reports the live repo-wide state of a group + while this endpoint lists groups associated with a run by + configuration. + group_members: + type: array + description: |- + Items belonging to this workflow run that are either currently holding or + waiting for the concurrency group lease. May be empty if the run no + longer has any active or queued items in this group. + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + - position + - position_url + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: string + format: uri + description: API URL for the workflow run. + nullable: true + run_html_url: + type: string + format: uri + description: Web URL for the workflow run. + nullable: true + position: + type: integer + description: Queue position. 0 means the item holds the concurrency + lease (in_progress), 1 or higher means queued (pending). + position_url: + type: string + format: uri + description: API URL to get items ahead of this item in the + concurrency group. + job_id: + type: integer + description: The ID of the job, when the item represents a job-level + or reusable-workflow-level lease. + nullable: true + job_name: + type: string + description: The display name of the job, when the item represents + a job-level or reusable-workflow-level lease. + nullable: true + job_url: + type: string + format: uri + description: API URL for the job. + nullable: true + job_html_url: + type: string + format: uri + description: Web URL for the job. + nullable: true + status: + type: string + enum: + - in_progress + - pending review-custom-gates-comment-required: type: object properties: @@ -228091,6 +231028,41 @@ components: last_accessed_at: '2019-01-24T22:45:36.000Z' created_at: '2019-01-24T22:45:36.000Z' size_in_bytes: 1024 + concurrency-group-list: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + last_acquired_at: '2026-01-15T16:14:23Z' + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + last_acquired_at: '2026-01-15T16:13:55Z' + concurrency-group: + value: + group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + total_count: 3 + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + - run_id: 30433643 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433643 + status: pending + - run_id: 30433644 + run_name: Deploy hotfix + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644 + job_id: 798245260 + job_name: deploy + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260 + status: pending job: value: id: 399444496 @@ -228767,6 +231739,34 @@ components: runner_group_name: my runner group workflow_name: CI head_branch: main + concurrency-group-run-list: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + position: 0 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642 + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: pending + position: 2 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260 + job_id: 798245260 + job_name: build + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260 pending-deployment-items: value: - environment: @@ -246186,6 +249186,13 @@ components: required: true schema: type: integer + concurrency-group-name: + name: concurrency_group_name + description: The name of the concurrency group. + in: path + required: true + schema: + type: string job-id: name: job_id description: The unique identifier of the job. diff --git a/descriptions/api.github.com/api.github.com.2026-03-10.json b/descriptions/api.github.com/api.github.com.2026-03-10.json index eff49dadc..3a9f727c3 100644 --- a/descriptions/api.github.com/api.github.com.2026-03-10.json +++ b/descriptions/api.github.com/api.github.com.2026-03-10.json @@ -530,6 +530,3164 @@ } } }, + "/agents/repos/{owner}/{repo}/tasks": { + "get": { + "summary": "List tasks for repository", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for a specific repository\n\n**Fine-grained access tokens for \"List tasks for repository\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks-for-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks-for-repository" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "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`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + }, + { + "name": "creator_id", + "in": "query", + "schema": { + "type": "integer" + }, + "description": "Filter tasks by creator user ID" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"prev\" (when current page > 1),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + }, + "post": { + "summary": "Start a task", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nStarts a new Copilot cloud agent task for a repository.\n\nThis endpoint is only available to users with a Copilot Business or Copilot Enterprise subscription.\n\n**Fine-grained access tokens for \"Start a task\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read and write)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/create-task-in-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#start-a-task" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + } + ], + "requestBody": { + "required": true, + "description": "The task creation parameters, including the user's prompt and optional agent settings.", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "prompt" + ], + "properties": { + "prompt": { + "type": "string", + "description": "The user's prompt for the agent" + }, + "model": { + "type": "string", + "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`" + }, + "create_pull_request": { + "type": "boolean", + "description": "Whether to create a PR.", + "default": false + }, + "base_ref": { + "type": "string", + "description": "Base ref for new branch/PR" + } + } + }, + "examples": { + "default": { + "value": { + "prompt": "Fix the login button on the homepage", + "base_ref": "main" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Task created successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "examples": { + "default": { + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "queued", + "session_count": 1, + "artifacts": [], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T00:00:00Z" + } + } + } + } + } + }, + "400": { + "description": "Problems parsing JSON", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/repos/{owner}/{repo}/tasks/{task_id}": { + "get": { + "summary": "Get a task by repo", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID scoped to an owner/repo path\n\n**Fine-grained access tokens for \"Get a task by repo\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-repo-and-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-repo" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks": { + "get": { + "summary": "List tasks", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for the authenticated user\n\n**Fine-grained access tokens for \"List tasks\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "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`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks/{task_id}": { + "get": { + "summary": "Get a task by ID", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID with its associated sessions\n\n**Fine-grained access tokens for \"Get a task by ID\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-id" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Problems parsing request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, "/app": { "get": { "summary": "Get the authenticated app", @@ -27923,7 +31081,7 @@ }, "post": { "summary": "Create a private registry for an organization", - "description": "\nCreates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", + "description": "\nCreates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", "tags": [ "private-registries" ], @@ -28006,7 +31164,387 @@ } }, "auth_type": { - "description": "The authentication type for the private registry. Defaults to `token` if not specified. Use `oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith` for OIDC authentication.", + "description": "The authentication type for the private registry. Defaults to `token` if not specified. Use `oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp` for OIDC authentication.", + "type": "string", + "enum": [ + "token", + "username_password", + "oidc_azure", + "oidc_aws", + "oidc_jfrog", + "oidc_cloudsmith", + "oidc_gcp" + ] + }, + "tenant_id": { + "description": "The tenant ID of the Azure AD application. Required when `auth_type` is `oidc_azure`.", + "type": "string" + }, + "client_id": { + "description": "The client ID of the Azure AD application. Required when `auth_type` is `oidc_azure`.", + "type": "string" + }, + "aws_region": { + "description": "The AWS region. Required when `auth_type` is `oidc_aws`.", + "type": "string" + }, + "account_id": { + "description": "The AWS account ID. Required when `auth_type` is `oidc_aws`.", + "type": "string" + }, + "role_name": { + "description": "The AWS IAM role name. Required when `auth_type` is `oidc_aws`.", + "type": "string" + }, + "domain": { + "description": "The CodeArtifact domain. Required when `auth_type` is `oidc_aws`.", + "type": "string" + }, + "domain_owner": { + "description": "The CodeArtifact domain owner (AWS account ID). Required when `auth_type` is `oidc_aws`.", + "type": "string" + }, + "jfrog_oidc_provider_name": { + "description": "The JFrog OIDC provider name. Required when `auth_type` is `oidc_jfrog`.", + "type": "string" + }, + "audience": { + "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and `oidc_gcp`, and required for `oidc_cloudsmith` auth types.", + "type": "string" + }, + "identity_mapping_name": { + "description": "The JFrog identity mapping name. Optional for `oidc_jfrog` auth type.", + "type": "string" + }, + "namespace": { + "description": "The Cloudsmith organization namespace. Required when `auth_type` is `oidc_cloudsmith`.", + "type": "string" + }, + "service_slug": { + "description": "The Cloudsmith service account slug. Required when `auth_type` is `oidc_cloudsmith`.", + "type": "string" + }, + "api_host": { + "description": "The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default.", + "type": "string" + }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). Required when `auth_type` is `oidc_gcp`.", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. Optional for `oidc_gcp` auth type. If omitted, the federated token is used directly (direct WIF).", + "type": "string" + } + }, + "required": [ + "registry_type", + "url", + "visibility" + ] + }, + "examples": { + "org-private-registry-with-private-visibility": { + "summary": "Example of a private registry configuration with private visibility", + "value": { + "registry_type": "maven_repository", + "url": "https://maven.pkg.github.com/organization/", + "username": "monalisa", + "replaces_base": true, + "encrypted_value": "c2VjcmV0", + "key_id": "012345678912345678", + "visibility": "private" + } + }, + "org-private-registry-with-selected-visibility": { + "summary": "Example of a private registry configuration with selected visibility", + "value": { + "registry_type": "maven_repository", + "url": "https://maven.pkg.github.com/organization/", + "username": "monalisa", + "encrypted_value": "c2VjcmV0", + "key_id": "012345678912345678", + "visibility": "selected", + "selected_repository_ids": [ + 1296269, + 1296280 + ] + } + }, + "org-private-registry-with-oidc-azure": { + "summary": "Example of an OIDC private registry configuration using Azure", + "value": { + "registry_type": "docker_registry", + "url": "https://myregistry.azurecr.io", + "auth_type": "oidc_azure", + "visibility": "all", + "tenant_id": "12345678-1234-1234-1234-123456789012", + "client_id": "abcdef01-2345-6789-abcd-ef0123456789" + } + }, + "org-private-registry-with-oidc-cloudsmith": { + "summary": "Example of an OIDC private registry configuration using Cloudsmith", + "value": { + "registry_type": "npm_registry", + "url": "https://npm.cloudsmith.io/my-org/my-repo/", + "auth_type": "oidc_cloudsmith", + "visibility": "all", + "namespace": "my-org", + "service_slug": "my-service-account", + "audience": "https://github.com/my-org" + } + }, + "org-private-registry-with-oidc-gcp": { + "summary": "Example of an OIDC private registry configuration using Google Cloud Artifact Registry", + "value": { + "registry_type": "docker_registry", + "url": "https://us-docker.pkg.dev/my-project/my-repo", + "auth_type": "oidc_gcp", + "visibility": "all", + "workload_identity_provider": "projects/123456789/locations/global/workloadIdentityPools/github-pool/providers/github-provider", + "service_account": "dependabot@my-project.iam.gserviceaccount.com" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "The organization private registry configuration", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/org-private-registry-configuration-with-selected-repositories" + }, + "examples": { + "org-private-registry-with-selected-visibility": { + "$ref": "#/components/examples/org-private-registry-configuration" + }, + "org-private-registry-with-private-visibility": { + "$ref": "#/components/examples/org-private-registry-configuration-with-selected-repositories" + } + } + } + } + }, + "404": { + "$ref": "#/components/responses/not_found" + }, + "422": { + "$ref": "#/components/responses/validation_failed" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "private-registries", + "subcategory": "organization-configurations" + } + } + }, + "/orgs/{org}/private-registries/public-key": { + "get": { + "summary": "Get private registries public key for an organization", + "description": "\nGets the org public key, which is needed to encrypt private registry secrets. You need to encrypt a secret before you can create or update secrets.\n\nOAuth tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", + "tags": [ + "private-registries" + ], + "operationId": "private-registries/get-org-public-key", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization" + }, + "parameters": [ + { + "$ref": "#/components/parameters/org" + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "key_id", + "key" + ], + "properties": { + "key_id": { + "description": "The identifier for the key.", + "example": "012345678912345678", + "type": "string" + }, + "key": { + "description": "The Base64 encoded public key.", + "example": "2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234", + "type": "string" + } + } + }, + "examples": { + "default": { + "$ref": "#/components/examples/private-registries-public-key" + } + } + } + }, + "headers": { + "Link": { + "$ref": "#/components/headers/link" + } + } + }, + "404": { + "$ref": "#/components/responses/not_found" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "private-registries", + "subcategory": "organization-configurations" + } + } + }, + "/orgs/{org}/private-registries/{secret_name}": { + "get": { + "summary": "Get a private registry for an organization", + "description": "\nGet the configuration of a single private registry defined for an organization, omitting its encrypted value.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", + "tags": [ + "private-registries" + ], + "operationId": "private-registries/get-org-private-registry", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/private-registries/organization-configurations#get-a-private-registry-for-an-organization" + }, + "parameters": [ + { + "$ref": "#/components/parameters/org" + }, + { + "$ref": "#/components/parameters/secret-name" + } + ], + "responses": { + "200": { + "description": "The specified private registry configuration for the organization", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/org-private-registry-configuration" + }, + "examples": { + "default": { + "$ref": "#/components/examples/org-private-registry-configuration" + } + } + } + } + }, + "404": { + "$ref": "#/components/responses/not_found" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "private-registries", + "subcategory": "organization-configurations" + } + }, + "patch": { + "summary": "Update a private registry for an organization", + "description": "\nUpdates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", + "tags": [ + "private-registries" + ], + "operationId": "private-registries/update-org-private-registry", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/private-registries/organization-configurations#update-a-private-registry-for-an-organization" + }, + "parameters": [ + { + "$ref": "#/components/parameters/org" + }, + { + "$ref": "#/components/parameters/secret-name" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "registry_type": { + "description": "The registry type.", + "type": "string", + "enum": [ + "maven_repository", + "nuget_feed", + "goproxy_server", + "npm_registry", + "rubygems_server", + "cargo_registry", + "composer_repository", + "docker_registry", + "git_source", + "helm_registry", + "hex_organization", + "hex_repository", + "pub_repository", + "python_index", + "terraform_registry" + ] + }, + "url": { + "description": "The URL of the private registry.", + "type": "string", + "format": "uri" + }, + "username": { + "description": "The username to use when authenticating with the private registry. This field should be omitted if the private registry does not require a username for authentication.", + "type": "string", + "nullable": true + }, + "replaces_base": { + "description": "Whether this private registry should replace the base registry (e.g., npmjs.org for npm, rubygems.org for rubygems). When set to `true`, Dependabot will only use this registry and will not fall back to the public registry. When set to `false` (default), Dependabot will use this registry for scoped packages but may fall back to the public registry for other packages.", + "type": "boolean", + "default": false + }, + "encrypted_value": { + "description": "The value for your secret, encrypted with [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages) using the public key retrieved from the [Get private registries public key for an organization](https://docs.github.com/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization) endpoint.", + "type": "string", + "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{4})$" + }, + "key_id": { + "description": "The ID of the key you used to encrypt the secret.", + "type": "string" + }, + "visibility": { + "description": "Which type of organization repositories have access to the private registry. `selected` means only the repositories specified by `selected_repository_ids` can access the private registry.", + "type": "string", + "enum": [ + "all", + "private", + "selected" + ] + }, + "selected_repository_ids": { + "description": "An array of repository IDs that can access the organization private registry. You can only provide a list of repository IDs when `visibility` is set to `selected`. This field should be omitted if `visibility` is set to `all` or `private`.", + "type": "array", + "items": { + "type": "integer" + } + }, + "auth_type": { + "description": "The authentication type for the private registry. This field cannot be changed after creation. If provided, it must match the existing `auth_type` of the configuration. To change the authentication type, delete and recreate the configuration.", "type": "string", "enum": [ "token", @@ -28014,7 +31552,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ] }, "tenant_id": { @@ -28050,7 +31589,7 @@ "type": "string" }, "audience": { - "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and required for `oidc_cloudsmith` auth types.", + "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and `oidc_gcp`, and required for `oidc_cloudsmith` auth types.", "type": "string" }, "identity_mapping_name": { @@ -28068,365 +31607,13 @@ "api_host": { "description": "The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default.", "type": "string" - } - }, - "required": [ - "registry_type", - "url", - "visibility" - ] - }, - "examples": { - "org-private-registry-with-private-visibility": { - "summary": "Example of a private registry configuration with private visibility", - "value": { - "registry_type": "maven_repository", - "url": "https://maven.pkg.github.com/organization/", - "username": "monalisa", - "replaces_base": true, - "encrypted_value": "c2VjcmV0", - "key_id": "012345678912345678", - "visibility": "private" - } - }, - "org-private-registry-with-selected-visibility": { - "summary": "Example of a private registry configuration with selected visibility", - "value": { - "registry_type": "maven_repository", - "url": "https://maven.pkg.github.com/organization/", - "username": "monalisa", - "encrypted_value": "c2VjcmV0", - "key_id": "012345678912345678", - "visibility": "selected", - "selected_repository_ids": [ - 1296269, - 1296280 - ] - } - }, - "org-private-registry-with-oidc-azure": { - "summary": "Example of an OIDC private registry configuration using Azure", - "value": { - "registry_type": "docker_registry", - "url": "https://myregistry.azurecr.io", - "auth_type": "oidc_azure", - "visibility": "all", - "tenant_id": "12345678-1234-1234-1234-123456789012", - "client_id": "abcdef01-2345-6789-abcd-ef0123456789" - } - }, - "org-private-registry-with-oidc-cloudsmith": { - "summary": "Example of an OIDC private registry configuration using Cloudsmith", - "value": { - "registry_type": "npm_registry", - "url": "https://npm.cloudsmith.io/my-org/my-repo/", - "auth_type": "oidc_cloudsmith", - "visibility": "all", - "namespace": "my-org", - "service_slug": "my-service-account", - "audience": "https://github.com/my-org" - } - } - } - } - } - }, - "responses": { - "201": { - "description": "The organization private registry configuration", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/org-private-registry-configuration-with-selected-repositories" - }, - "examples": { - "org-private-registry-with-selected-visibility": { - "$ref": "#/components/examples/org-private-registry-configuration" }, - "org-private-registry-with-private-visibility": { - "$ref": "#/components/examples/org-private-registry-configuration-with-selected-repositories" - } - } - } - } - }, - "404": { - "$ref": "#/components/responses/not_found" - }, - "422": { - "$ref": "#/components/responses/validation_failed" - } - }, - "x-github": { - "githubCloudOnly": false, - "enabledForGitHubApps": true, - "category": "private-registries", - "subcategory": "organization-configurations" - } - } - }, - "/orgs/{org}/private-registries/public-key": { - "get": { - "summary": "Get private registries public key for an organization", - "description": "\nGets the org public key, which is needed to encrypt private registry secrets. You need to encrypt a secret before you can create or update secrets.\n\nOAuth tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", - "tags": [ - "private-registries" - ], - "operationId": "private-registries/get-org-public-key", - "externalDocs": { - "description": "API method documentation", - "url": "https://docs.github.com/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization" - }, - "parameters": [ - { - "$ref": "#/components/parameters/org" - } - ], - "responses": { - "200": { - "description": "Response", - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "key_id", - "key" - ], - "properties": { - "key_id": { - "description": "The identifier for the key.", - "example": "012345678912345678", - "type": "string" - }, - "key": { - "description": "The Base64 encoded public key.", - "example": "2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234", - "type": "string" - } - } - }, - "examples": { - "default": { - "$ref": "#/components/examples/private-registries-public-key" - } - } - } - }, - "headers": { - "Link": { - "$ref": "#/components/headers/link" - } - } - }, - "404": { - "$ref": "#/components/responses/not_found" - } - }, - "x-github": { - "githubCloudOnly": false, - "enabledForGitHubApps": true, - "category": "private-registries", - "subcategory": "organization-configurations" - } - } - }, - "/orgs/{org}/private-registries/{secret_name}": { - "get": { - "summary": "Get a private registry for an organization", - "description": "\nGet the configuration of a single private registry defined for an organization, omitting its encrypted value.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", - "tags": [ - "private-registries" - ], - "operationId": "private-registries/get-org-private-registry", - "externalDocs": { - "description": "API method documentation", - "url": "https://docs.github.com/rest/private-registries/organization-configurations#get-a-private-registry-for-an-organization" - }, - "parameters": [ - { - "$ref": "#/components/parameters/org" - }, - { - "$ref": "#/components/parameters/secret-name" - } - ], - "responses": { - "200": { - "description": "The specified private registry configuration for the organization", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/org-private-registry-configuration" - }, - "examples": { - "default": { - "$ref": "#/components/examples/org-private-registry-configuration" - } - } - } - } - }, - "404": { - "$ref": "#/components/responses/not_found" - } - }, - "x-github": { - "githubCloudOnly": false, - "enabledForGitHubApps": true, - "category": "private-registries", - "subcategory": "organization-configurations" - } - }, - "patch": { - "summary": "Update a private registry for an organization", - "description": "\nUpdates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", - "tags": [ - "private-registries" - ], - "operationId": "private-registries/update-org-private-registry", - "externalDocs": { - "description": "API method documentation", - "url": "https://docs.github.com/rest/private-registries/organization-configurations#update-a-private-registry-for-an-organization" - }, - "parameters": [ - { - "$ref": "#/components/parameters/org" - }, - { - "$ref": "#/components/parameters/secret-name" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "registry_type": { - "description": "The registry type.", - "type": "string", - "enum": [ - "maven_repository", - "nuget_feed", - "goproxy_server", - "npm_registry", - "rubygems_server", - "cargo_registry", - "composer_repository", - "docker_registry", - "git_source", - "helm_registry", - "hex_organization", - "hex_repository", - "pub_repository", - "python_index", - "terraform_registry" - ] - }, - "url": { - "description": "The URL of the private registry.", - "type": "string", - "format": "uri" - }, - "username": { - "description": "The username to use when authenticating with the private registry. This field should be omitted if the private registry does not require a username for authentication.", - "type": "string", - "nullable": true - }, - "replaces_base": { - "description": "Whether this private registry should replace the base registry (e.g., npmjs.org for npm, rubygems.org for rubygems). When set to `true`, Dependabot will only use this registry and will not fall back to the public registry. When set to `false` (default), Dependabot will use this registry for scoped packages but may fall back to the public registry for other packages.", - "type": "boolean", - "default": false - }, - "encrypted_value": { - "description": "The value for your secret, encrypted with [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages) using the public key retrieved from the [Get private registries public key for an organization](https://docs.github.com/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization) endpoint.", - "type": "string", - "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{4})$" - }, - "key_id": { - "description": "The ID of the key you used to encrypt the secret.", - "type": "string" - }, - "visibility": { - "description": "Which type of organization repositories have access to the private registry. `selected` means only the repositories specified by `selected_repository_ids` can access the private registry.", - "type": "string", - "enum": [ - "all", - "private", - "selected" - ] - }, - "selected_repository_ids": { - "description": "An array of repository IDs that can access the organization private registry. You can only provide a list of repository IDs when `visibility` is set to `selected`. This field should be omitted if `visibility` is set to `all` or `private`.", - "type": "array", - "items": { - "type": "integer" - } - }, - "auth_type": { - "description": "The authentication type for the private registry. This field cannot be changed after creation. If provided, it must match the existing `auth_type` of the configuration. To change the authentication type, delete and recreate the configuration.", - "type": "string", - "enum": [ - "token", - "username_password", - "oidc_azure", - "oidc_aws", - "oidc_jfrog", - "oidc_cloudsmith" - ] - }, - "tenant_id": { - "description": "The tenant ID of the Azure AD application. Required when `auth_type` is `oidc_azure`.", - "type": "string" - }, - "client_id": { - "description": "The client ID of the Azure AD application. Required when `auth_type` is `oidc_azure`.", - "type": "string" - }, - "aws_region": { - "description": "The AWS region. Required when `auth_type` is `oidc_aws`.", - "type": "string" - }, - "account_id": { - "description": "The AWS account ID. Required when `auth_type` is `oidc_aws`.", - "type": "string" - }, - "role_name": { - "description": "The AWS IAM role name. Required when `auth_type` is `oidc_aws`.", + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). Required when `auth_type` is `oidc_gcp`.", "type": "string" }, - "domain": { - "description": "The CodeArtifact domain. Required when `auth_type` is `oidc_aws`.", - "type": "string" - }, - "domain_owner": { - "description": "The CodeArtifact domain owner (AWS account ID). Required when `auth_type` is `oidc_aws`.", - "type": "string" - }, - "jfrog_oidc_provider_name": { - "description": "The JFrog OIDC provider name. Required when `auth_type` is `oidc_jfrog`.", - "type": "string" - }, - "audience": { - "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and required for `oidc_cloudsmith` auth types.", - "type": "string" - }, - "identity_mapping_name": { - "description": "The JFrog identity mapping name. Optional for `oidc_jfrog` auth type.", - "type": "string" - }, - "namespace": { - "description": "The Cloudsmith organization namespace. Required when `auth_type` is `oidc_cloudsmith`.", - "type": "string" - }, - "service_slug": { - "description": "The Cloudsmith service account slug. Required when `auth_type` is `oidc_cloudsmith`.", - "type": "string" - }, - "api_host": { - "description": "The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default.", + "service_account": { + "description": "The GCP service account email to impersonate. Optional for `oidc_gcp` auth type. If omitted, the federated token is used directly (direct WIF).", "type": "string" } } @@ -35019,6 +38206,139 @@ } } }, + "/repos/{owner}/{repo}/actions/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a repository", + "description": "Lists the active concurrency groups for a repository.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository" + }, + "parameters": [ + { + "$ref": "#/components/parameters/owner" + }, + { + "$ref": "#/components/parameters/repo" + }, + { + "$ref": "#/components/parameters/per-page" + }, + { + "$ref": "#/components/parameters/pagination-after" + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/concurrency-group-list" + }, + "examples": { + "default": { + "$ref": "#/components/examples/concurrency-group-list" + } + } + } + }, + "headers": { + "Link": { + "$ref": "#/components/headers/link" + } + } + }, + "422": { + "$ref": "#/components/responses/validation_failed" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": { + "get": { + "summary": "Get a concurrency group for a repository", + "description": "Gets a specific concurrency group for a repository, including all instances in the group's queue.\nReturns 404 if the group is inactive or does not exist.\n\nOptionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items\nahead of the specified workflow run or job in the queue, plus the specified item itself\n(returned as the last element). This is useful for determining what is blocking a particular\nrun or job. Returns 422 if the specified run or job is not in this concurrency group.\n\nWhen using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow\nleases held on behalf of that run. Job-level leases within the run are not considered to\nblock the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow\nleases on the job's ancestor paths.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/get-concurrency-group-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository" + }, + "parameters": [ + { + "$ref": "#/components/parameters/owner" + }, + { + "$ref": "#/components/parameters/repo" + }, + { + "$ref": "#/components/parameters/concurrency-group-name" + }, + { + "name": "ahead_of_run", + "description": "Filter to items ahead of this workflow run ID in the queue, plus the run itself.\nMatches workflow-level concurrency and reusable-workflow leases held on behalf of\nthe run. Mutually exclusive with `ahead_of_job`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + }, + { + "name": "ahead_of_job", + "description": "Filter to items ahead of this job ID in the queue, plus the job itself.\nMatches job-level concurrency and reusable-workflow leases on the job's\nancestor paths. Mutually exclusive with `ahead_of_run`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/concurrency-group" + }, + "examples": { + "default": { + "$ref": "#/components/examples/concurrency-group" + } + } + } + } + }, + "404": { + "$ref": "#/components/responses/not_found" + }, + "422": { + "$ref": "#/components/responses/validation_failed" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/jobs/{job_id}": { "get": { "summary": "Get a job for a workflow run", @@ -37430,6 +40750,74 @@ } } }, + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a workflow run", + "description": "Lists all concurrency groups associated with a workflow run or its jobs.\n\nThe set of groups is derived from the run's configuration, so a group is\nincluded even when the run no longer has any items currently holding or\nwaiting in it. In that case the `group_members` array will be empty.\n`total_count` reflects the number of groups the run participates in by\nconfiguration, not the number with active items.\n\nThis differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`,\nwhich returns 404 when a group has no active items. That endpoint reports\nthe live state of a group repo-wide, while this endpoint reports the\ngroups associated with a specific run by configuration.\n\nResults are sorted by group name and support cursor-based pagination via\n`before` and `after`. The `after` cursor paginates forward only and does\nnot emit a `rel=\"prev\"` Link; use `before` to page backward from a\nforward page's `next` cursor.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-workflow-run", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run" + }, + "parameters": [ + { + "$ref": "#/components/parameters/owner" + }, + { + "$ref": "#/components/parameters/repo" + }, + { + "$ref": "#/components/parameters/run-id" + }, + { + "$ref": "#/components/parameters/per-page" + }, + { + "$ref": "#/components/parameters/pagination-before" + }, + { + "$ref": "#/components/parameters/pagination-after" + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/concurrency-group-run-list" + }, + "examples": { + "default": { + "$ref": "#/components/examples/concurrency-group-run-list" + } + } + } + }, + "headers": { + "Link": { + "$ref": "#/components/headers/link" + } + } + }, + "404": { + "$ref": "#/components/responses/not_found" + }, + "422": { + "$ref": "#/components/responses/validation_failed" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": { "post": { "summary": "Review custom deployment protection rules for a workflow run", @@ -121506,7 +124894,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ], "type": "string" }, @@ -121587,6 +124976,14 @@ "description": "The Cloudsmith API host.", "type": "string" }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`).", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. If omitted, the federated token is used directly (direct WIF).", + "type": "string" + }, "created_at": { "type": "string", "format": "date-time" @@ -121643,7 +125040,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ], "type": "string" }, @@ -121730,6 +125128,14 @@ "description": "The Cloudsmith API host.", "type": "string" }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`).", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. If omitted, the federated token is used directly (direct WIF).", + "type": "string" + }, "created_at": { "type": "string", "format": "date-time" @@ -128343,6 +131749,134 @@ "actions_caches" ] }, + "concurrency-group-list": { + "title": "Concurrency Group List", + "description": "A list of active concurrency groups for a repository.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer" + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "last_acquired_at" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "last_acquired_at": { + "type": "string", + "format": "date-time", + "nullable": true + } + } + } + } + } + }, + "concurrency-group": { + "title": "Concurrency Group", + "description": "A concurrency group with the workflow runs and jobs that are either currently holding\nor waiting for the concurrency group lease.", + "type": "object", + "required": [ + "group_name", + "group_url", + "total_count", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "total_count": { + "type": "integer" + }, + "group_members": { + "type": "array", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": "string", + "format": "uri", + "description": "API URL for the workflow run.", + "nullable": true + }, + "run_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the workflow run.", + "nullable": true + }, + "job_id": { + "type": "integer", + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_name": { + "type": "string", + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_url": { + "type": "string", + "format": "uri", + "description": "API URL for the job.", + "nullable": true + }, + "job_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the job.", + "nullable": true + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + }, "job": { "title": "Job", "description": "Information of a job execution in a workflow run", @@ -129077,6 +132611,119 @@ "comment" ] }, + "concurrency-group-run-list": { + "title": "Concurrency Group Run List", + "description": "A list of concurrency groups associated with a workflow run.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer", + "description": "The total number of concurrency groups this workflow run participates in,\nderived from the run's configuration. This count is not filtered by\nwhether the run currently holds or is waiting in each group, so it can\ninclude groups whose `group_members` array is empty (for example, when\nthe run has already released its lease in that group)." + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group. May return 404 if the group\nhas no active items at the time it is requested, since the\nget-by-name endpoint reports the live repo-wide state of a group\nwhile this endpoint lists groups associated with a run by\nconfiguration." + }, + "group_members": { + "type": "array", + "description": "Items belonging to this workflow run that are either currently holding or\nwaiting for the concurrency group lease. May be empty if the run no\nlonger has any active or queued items in this group.", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status", + "position", + "position_url" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": "string", + "format": "uri", + "description": "API URL for the workflow run.", + "nullable": true + }, + "run_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the workflow run.", + "nullable": true + }, + "position": { + "type": "integer", + "description": "Queue position. 0 means the item holds the concurrency lease (in_progress), 1 or higher means queued (pending)." + }, + "position_url": { + "type": "string", + "format": "uri", + "description": "API URL to get items ahead of this item in the concurrency group." + }, + "job_id": { + "type": "integer", + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease.", + "nullable": true + }, + "job_name": { + "type": "string", + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease.", + "nullable": true + }, + "job_url": { + "type": "string", + "format": "uri", + "description": "API URL for the job.", + "nullable": true + }, + "job_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the job.", + "nullable": true + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + } + } + } + }, "review-custom-gates-comment-required": { "type": "object", "properties": { @@ -302562,6 +306209,57 @@ ] } }, + "concurrency-group-list": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "last_acquired_at": "2026-01-15T16:14:23Z" + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "last_acquired_at": "2026-01-15T16:13:55Z" + } + ] + } + }, + "concurrency-group": { + "value": { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "total_count": 3, + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress" + }, + { + "run_id": 30433643, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433643", + "status": "pending" + }, + { + "run_id": 30433644, + "run_name": "Deploy hotfix", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644", + "job_id": 798245260, + "job_name": "deploy", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260", + "status": "pending" + } + ] + } + }, "job": { "value": { "id": 399444496, @@ -303350,6 +307048,47 @@ ] } }, + "concurrency-group-run-list": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress", + "position": 0, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642" + } + ] + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "pending", + "position": 2, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260", + "job_id": 798245260, + "job_name": "build", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260" + } + ] + } + ] + } + }, "pending-deployment-items": { "value": [ { @@ -323394,6 +327133,15 @@ "type": "integer" } }, + "concurrency-group-name": { + "name": "concurrency_group_name", + "description": "The name of the concurrency group.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, "job-id": { "name": "job_id", "description": "The unique identifier of the job.", diff --git a/descriptions/api.github.com/api.github.com.2026-03-10.yaml b/descriptions/api.github.com/api.github.com.2026-03-10.yaml index 93cb1e7c8..a3e6c7043 100644 --- a/descriptions/api.github.com/api.github.com.2026-03-10.yaml +++ b/descriptions/api.github.com/api.github.com.2026-03-10.yaml @@ -343,6 +343,2525 @@ paths: enabledForGitHubApps: true category: security-advisories subcategory: global-advisories + "/agents/repos/{owner}/{repo}/tasks": + get: + summary: List tasks for repository + description: | + > [!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](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks-for-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks-for-repository + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: '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`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + - name: creator_id + in: query + schema: + type: integer + description: Filter tasks by creator user ID + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="prev" (when current page > 1), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; + rel="next", ; + rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + post: + summary: Start a task + description: | + > [!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](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/create-task-in-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#start-a-task + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + requestBody: + required: true + description: The task creation parameters, including the user's prompt and + optional agent settings. + content: + application/json: + schema: + type: object + required: + - prompt + properties: + prompt: + type: string + description: The user's prompt for the agent + model: + type: string + 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`' + create_pull_request: + type: boolean + description: Whether to create a PR. + default: false + base_ref: + type: string + description: Base ref for new branch/PR + examples: + default: + value: + prompt: Fix the login button on the homepage + base_ref: main + responses: + '201': + description: Task created successfully + content: + application/json: + schema: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + examples: + default: + value: + id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: queued + session_count: 1 + artifacts: [] + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T00:00:00Z' + '400': + description: Problems parsing JSON + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/repos/{owner}/{repo}/tasks/{task_id}": + get: + summary: Get a task by repo + description: | + > [!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](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-repo-and-id + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-repo + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks": + get: + summary: List tasks + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a list of tasks for the authenticated user + + **Fine-grained access tokens for "List tasks"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: '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`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; rel="next", + ; rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks/{task_id}": + get: + summary: Get a task by ID + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a task by ID with its associated sessions + + **Fine-grained access tokens for "Get a task by ID"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-id + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-id + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Problems parsing request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation "/app": get: summary: Get the authenticated app @@ -20386,7 +22905,7 @@ paths: description: |2- Creates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see "[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api)." - For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted. + For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted. OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. tags: @@ -20479,7 +22998,332 @@ paths: auth_type: description: The authentication type for the private registry. Defaults to `token` if not specified. Use `oidc_azure`, `oidc_aws`, `oidc_jfrog`, - or `oidc_cloudsmith` for OIDC authentication. + `oidc_cloudsmith`, or `oidc_gcp` for OIDC authentication. + type: string + enum: + - token + - username_password + - oidc_azure + - oidc_aws + - oidc_jfrog + - oidc_cloudsmith + - oidc_gcp + tenant_id: + description: The tenant ID of the Azure AD application. Required + when `auth_type` is `oidc_azure`. + type: string + client_id: + description: The client ID of the Azure AD application. Required + when `auth_type` is `oidc_azure`. + type: string + aws_region: + description: The AWS region. Required when `auth_type` is `oidc_aws`. + type: string + account_id: + description: The AWS account ID. Required when `auth_type` is `oidc_aws`. + type: string + role_name: + description: The AWS IAM role name. Required when `auth_type` is + `oidc_aws`. + type: string + domain: + description: The CodeArtifact domain. Required when `auth_type` + is `oidc_aws`. + type: string + domain_owner: + description: The CodeArtifact domain owner (AWS account ID). Required + when `auth_type` is `oidc_aws`. + type: string + jfrog_oidc_provider_name: + description: The JFrog OIDC provider name. Required when `auth_type` + is `oidc_jfrog`. + type: string + audience: + description: The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, + and `oidc_gcp`, and required for `oidc_cloudsmith` auth types. + type: string + identity_mapping_name: + description: The JFrog identity mapping name. Optional for `oidc_jfrog` + auth type. + type: string + namespace: + description: The Cloudsmith organization namespace. Required when + `auth_type` is `oidc_cloudsmith`. + type: string + service_slug: + description: The Cloudsmith service account slug. Required when + `auth_type` is `oidc_cloudsmith`. + type: string + api_host: + description: The Cloudsmith API host. Optional for `oidc_cloudsmith` + auth type. If omitted, `api.cloudsmith.io` is used by default. + type: string + workload_identity_provider: + description: The full resource name of the GCP Workload Identity + Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + Required when `auth_type` is `oidc_gcp`. + type: string + service_account: + description: The GCP service account email to impersonate. Optional + for `oidc_gcp` auth type. If omitted, the federated token is used + directly (direct WIF). + type: string + required: + - registry_type + - url + - visibility + examples: + org-private-registry-with-private-visibility: + summary: Example of a private registry configuration with private + visibility + value: + registry_type: maven_repository + url: https://maven.pkg.github.com/organization/ + username: monalisa + replaces_base: true + encrypted_value: c2VjcmV0 + key_id: '012345678912345678' + visibility: private + org-private-registry-with-selected-visibility: + summary: Example of a private registry configuration with selected + visibility + value: + registry_type: maven_repository + url: https://maven.pkg.github.com/organization/ + username: monalisa + encrypted_value: c2VjcmV0 + key_id: '012345678912345678' + visibility: selected + selected_repository_ids: + - 1296269 + - 1296280 + org-private-registry-with-oidc-azure: + summary: Example of an OIDC private registry configuration using Azure + value: + registry_type: docker_registry + url: https://myregistry.azurecr.io + auth_type: oidc_azure + visibility: all + tenant_id: 12345678-1234-1234-1234-123456789012 + client_id: abcdef01-2345-6789-abcd-ef0123456789 + org-private-registry-with-oidc-cloudsmith: + summary: Example of an OIDC private registry configuration using Cloudsmith + value: + registry_type: npm_registry + url: https://npm.cloudsmith.io/my-org/my-repo/ + auth_type: oidc_cloudsmith + visibility: all + namespace: my-org + service_slug: my-service-account + audience: https://github.com/my-org + org-private-registry-with-oidc-gcp: + summary: Example of an OIDC private registry configuration using Google + Cloud Artifact Registry + value: + registry_type: docker_registry + url: https://us-docker.pkg.dev/my-project/my-repo + auth_type: oidc_gcp + visibility: all + workload_identity_provider: projects/123456789/locations/global/workloadIdentityPools/github-pool/providers/github-provider + service_account: dependabot@my-project.iam.gserviceaccount.com + responses: + '201': + description: The organization private registry configuration + content: + application/json: + schema: + "$ref": "#/components/schemas/org-private-registry-configuration-with-selected-repositories" + examples: + org-private-registry-with-selected-visibility: + "$ref": "#/components/examples/org-private-registry-configuration" + org-private-registry-with-private-visibility: + "$ref": "#/components/examples/org-private-registry-configuration-with-selected-repositories" + '404': + "$ref": "#/components/responses/not_found" + '422': + "$ref": "#/components/responses/validation_failed" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: private-registries + subcategory: organization-configurations + "/orgs/{org}/private-registries/public-key": + get: + summary: Get private registries public key for an organization + description: |2- + + Gets the org public key, which is needed to encrypt private registry secrets. You need to encrypt a secret before you can create or update secrets. + + OAuth tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. + tags: + - private-registries + operationId: private-registries/get-org-public-key + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization + parameters: + - "$ref": "#/components/parameters/org" + responses: + '200': + description: Response + content: + application/json: + schema: + type: object + required: + - key_id + - key + properties: + key_id: + description: The identifier for the key. + example: '012345678912345678' + type: string + key: + description: The Base64 encoded public key. + example: 2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234 + type: string + examples: + default: + "$ref": "#/components/examples/private-registries-public-key" + headers: + Link: + "$ref": "#/components/headers/link" + '404': + "$ref": "#/components/responses/not_found" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: private-registries + subcategory: organization-configurations + "/orgs/{org}/private-registries/{secret_name}": + get: + summary: Get a private registry for an organization + description: |2- + + Get the configuration of a single private registry defined for an organization, omitting its encrypted value. + + OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. + tags: + - private-registries + operationId: private-registries/get-org-private-registry + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/private-registries/organization-configurations#get-a-private-registry-for-an-organization + parameters: + - "$ref": "#/components/parameters/org" + - "$ref": "#/components/parameters/secret-name" + responses: + '200': + description: The specified private registry configuration for the organization + content: + application/json: + schema: + "$ref": "#/components/schemas/org-private-registry-configuration" + examples: + default: + "$ref": "#/components/examples/org-private-registry-configuration" + '404': + "$ref": "#/components/responses/not_found" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: private-registries + subcategory: organization-configurations + patch: + summary: Update a private registry for an organization + description: |2- + + Updates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see "[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api)." + For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted. + + OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. + tags: + - private-registries + operationId: private-registries/update-org-private-registry + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/private-registries/organization-configurations#update-a-private-registry-for-an-organization + parameters: + - "$ref": "#/components/parameters/org" + - "$ref": "#/components/parameters/secret-name" + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + registry_type: + description: The registry type. + type: string + enum: + - maven_repository + - nuget_feed + - goproxy_server + - npm_registry + - rubygems_server + - cargo_registry + - composer_repository + - docker_registry + - git_source + - helm_registry + - hex_organization + - hex_repository + - pub_repository + - python_index + - terraform_registry + url: + description: The URL of the private registry. + type: string + format: uri + username: + description: The username to use when authenticating with the private + registry. This field should be omitted if the private registry + does not require a username for authentication. + type: string + nullable: true + replaces_base: + description: Whether this private registry should replace the base + registry (e.g., npmjs.org for npm, rubygems.org for rubygems). + When set to `true`, Dependabot will only use this registry and + will not fall back to the public registry. When set to `false` + (default), Dependabot will use this registry for scoped packages + but may fall back to the public registry for other packages. + type: boolean + default: false + encrypted_value: + description: The value for your secret, encrypted with [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages) + using the public key retrieved from the [Get private registries + public key for an organization](https://docs.github.com/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization) + endpoint. + type: string + pattern: "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{4})$" + key_id: + description: The ID of the key you used to encrypt the secret. + type: string + visibility: + description: Which type of organization repositories have access + to the private registry. `selected` means only the repositories + specified by `selected_repository_ids` can access the private + registry. + type: string + enum: + - all + - private + - selected + selected_repository_ids: + description: An array of repository IDs that can access the organization + private registry. You can only provide a list of repository IDs + when `visibility` is set to `selected`. This field should be omitted + if `visibility` is set to `all` or `private`. + type: array + items: + type: integer + auth_type: + description: The authentication type for the private registry. This + field cannot be changed after creation. If provided, it must match + the existing `auth_type` of the configuration. To change the authentication + type, delete and recreate the configuration. type: string enum: - token @@ -20488,6 +23332,7 @@ paths: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp tenant_id: description: The tenant ID of the Azure AD application. Required when `auth_type` is `oidc_azure`. @@ -20520,7 +23365,7 @@ paths: type: string audience: description: The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, - and required for `oidc_cloudsmith` auth types. + and `oidc_gcp`, and required for `oidc_cloudsmith` auth types. type: string identity_mapping_name: description: The JFrog identity mapping name. Optional for `oidc_jfrog` @@ -20538,309 +23383,15 @@ paths: description: The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default. type: string - required: - - registry_type - - url - - visibility - examples: - org-private-registry-with-private-visibility: - summary: Example of a private registry configuration with private - visibility - value: - registry_type: maven_repository - url: https://maven.pkg.github.com/organization/ - username: monalisa - replaces_base: true - encrypted_value: c2VjcmV0 - key_id: '012345678912345678' - visibility: private - org-private-registry-with-selected-visibility: - summary: Example of a private registry configuration with selected - visibility - value: - registry_type: maven_repository - url: https://maven.pkg.github.com/organization/ - username: monalisa - encrypted_value: c2VjcmV0 - key_id: '012345678912345678' - visibility: selected - selected_repository_ids: - - 1296269 - - 1296280 - org-private-registry-with-oidc-azure: - summary: Example of an OIDC private registry configuration using Azure - value: - registry_type: docker_registry - url: https://myregistry.azurecr.io - auth_type: oidc_azure - visibility: all - tenant_id: 12345678-1234-1234-1234-123456789012 - client_id: abcdef01-2345-6789-abcd-ef0123456789 - org-private-registry-with-oidc-cloudsmith: - summary: Example of an OIDC private registry configuration using Cloudsmith - value: - registry_type: npm_registry - url: https://npm.cloudsmith.io/my-org/my-repo/ - auth_type: oidc_cloudsmith - visibility: all - namespace: my-org - service_slug: my-service-account - audience: https://github.com/my-org - responses: - '201': - description: The organization private registry configuration - content: - application/json: - schema: - "$ref": "#/components/schemas/org-private-registry-configuration-with-selected-repositories" - examples: - org-private-registry-with-selected-visibility: - "$ref": "#/components/examples/org-private-registry-configuration" - org-private-registry-with-private-visibility: - "$ref": "#/components/examples/org-private-registry-configuration-with-selected-repositories" - '404': - "$ref": "#/components/responses/not_found" - '422': - "$ref": "#/components/responses/validation_failed" - x-github: - githubCloudOnly: false - enabledForGitHubApps: true - category: private-registries - subcategory: organization-configurations - "/orgs/{org}/private-registries/public-key": - get: - summary: Get private registries public key for an organization - description: |2- - - Gets the org public key, which is needed to encrypt private registry secrets. You need to encrypt a secret before you can create or update secrets. - - OAuth tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. - tags: - - private-registries - operationId: private-registries/get-org-public-key - externalDocs: - description: API method documentation - url: https://docs.github.com/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization - parameters: - - "$ref": "#/components/parameters/org" - responses: - '200': - description: Response - content: - application/json: - schema: - type: object - required: - - key_id - - key - properties: - key_id: - description: The identifier for the key. - example: '012345678912345678' - type: string - key: - description: The Base64 encoded public key. - example: 2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234 - type: string - examples: - default: - "$ref": "#/components/examples/private-registries-public-key" - headers: - Link: - "$ref": "#/components/headers/link" - '404': - "$ref": "#/components/responses/not_found" - x-github: - githubCloudOnly: false - enabledForGitHubApps: true - category: private-registries - subcategory: organization-configurations - "/orgs/{org}/private-registries/{secret_name}": - get: - summary: Get a private registry for an organization - description: |2- - - Get the configuration of a single private registry defined for an organization, omitting its encrypted value. - - OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. - tags: - - private-registries - operationId: private-registries/get-org-private-registry - externalDocs: - description: API method documentation - url: https://docs.github.com/rest/private-registries/organization-configurations#get-a-private-registry-for-an-organization - parameters: - - "$ref": "#/components/parameters/org" - - "$ref": "#/components/parameters/secret-name" - responses: - '200': - description: The specified private registry configuration for the organization - content: - application/json: - schema: - "$ref": "#/components/schemas/org-private-registry-configuration" - examples: - default: - "$ref": "#/components/examples/org-private-registry-configuration" - '404': - "$ref": "#/components/responses/not_found" - x-github: - githubCloudOnly: false - enabledForGitHubApps: true - category: private-registries - subcategory: organization-configurations - patch: - summary: Update a private registry for an organization - description: |2- - - Updates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see "[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api)." - For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted. - - OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. - tags: - - private-registries - operationId: private-registries/update-org-private-registry - externalDocs: - description: API method documentation - url: https://docs.github.com/rest/private-registries/organization-configurations#update-a-private-registry-for-an-organization - parameters: - - "$ref": "#/components/parameters/org" - - "$ref": "#/components/parameters/secret-name" - requestBody: - required: true - content: - application/json: - schema: - type: object - properties: - registry_type: - description: The registry type. - type: string - enum: - - maven_repository - - nuget_feed - - goproxy_server - - npm_registry - - rubygems_server - - cargo_registry - - composer_repository - - docker_registry - - git_source - - helm_registry - - hex_organization - - hex_repository - - pub_repository - - python_index - - terraform_registry - url: - description: The URL of the private registry. - type: string - format: uri - username: - description: The username to use when authenticating with the private - registry. This field should be omitted if the private registry - does not require a username for authentication. - type: string - nullable: true - replaces_base: - description: Whether this private registry should replace the base - registry (e.g., npmjs.org for npm, rubygems.org for rubygems). - When set to `true`, Dependabot will only use this registry and - will not fall back to the public registry. When set to `false` - (default), Dependabot will use this registry for scoped packages - but may fall back to the public registry for other packages. - type: boolean - default: false - encrypted_value: - description: The value for your secret, encrypted with [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages) - using the public key retrieved from the [Get private registries - public key for an organization](https://docs.github.com/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization) - endpoint. - type: string - pattern: "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{4})$" - key_id: - description: The ID of the key you used to encrypt the secret. - type: string - visibility: - description: Which type of organization repositories have access - to the private registry. `selected` means only the repositories - specified by `selected_repository_ids` can access the private - registry. - type: string - enum: - - all - - private - - selected - selected_repository_ids: - description: An array of repository IDs that can access the organization - private registry. You can only provide a list of repository IDs - when `visibility` is set to `selected`. This field should be omitted - if `visibility` is set to `all` or `private`. - type: array - items: - type: integer - auth_type: - description: The authentication type for the private registry. This - field cannot be changed after creation. If provided, it must match - the existing `auth_type` of the configuration. To change the authentication - type, delete and recreate the configuration. + workload_identity_provider: + description: The full resource name of the GCP Workload Identity + Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + Required when `auth_type` is `oidc_gcp`. type: string - enum: - - token - - username_password - - oidc_azure - - oidc_aws - - oidc_jfrog - - oidc_cloudsmith - tenant_id: - description: The tenant ID of the Azure AD application. Required - when `auth_type` is `oidc_azure`. - type: string - client_id: - description: The client ID of the Azure AD application. Required - when `auth_type` is `oidc_azure`. - type: string - aws_region: - description: The AWS region. Required when `auth_type` is `oidc_aws`. - type: string - account_id: - description: The AWS account ID. Required when `auth_type` is `oidc_aws`. - type: string - role_name: - description: The AWS IAM role name. Required when `auth_type` is - `oidc_aws`. - type: string - domain: - description: The CodeArtifact domain. Required when `auth_type` - is `oidc_aws`. - type: string - domain_owner: - description: The CodeArtifact domain owner (AWS account ID). Required - when `auth_type` is `oidc_aws`. - type: string - jfrog_oidc_provider_name: - description: The JFrog OIDC provider name. Required when `auth_type` - is `oidc_jfrog`. - type: string - audience: - description: The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, - and required for `oidc_cloudsmith` auth types. - type: string - identity_mapping_name: - description: The JFrog identity mapping name. Optional for `oidc_jfrog` - auth type. - type: string - namespace: - description: The Cloudsmith organization namespace. Required when - `auth_type` is `oidc_cloudsmith`. - type: string - service_slug: - description: The Cloudsmith service account slug. Required when - `auth_type` is `oidc_cloudsmith`. - type: string - api_host: - description: The Cloudsmith API host. Optional for `oidc_cloudsmith` - auth type. If omitted, `api.cloudsmith.io` is used by default. + service_account: + description: The GCP service account email to impersonate. Optional + for `oidc_gcp` auth type. If omitted, the federated token is used + directly (direct WIF). type: string examples: secret-based-update: @@ -25609,6 +28160,111 @@ paths: enabledForGitHubApps: true category: actions subcategory: cache + "/repos/{owner}/{repo}/actions/concurrency_groups": + get: + summary: List concurrency groups for a repository + description: |- + Lists the active concurrency groups for a repository. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository + parameters: + - "$ref": "#/components/parameters/owner" + - "$ref": "#/components/parameters/repo" + - "$ref": "#/components/parameters/per-page" + - "$ref": "#/components/parameters/pagination-after" + responses: + '200': + description: Response + content: + application/json: + schema: + "$ref": "#/components/schemas/concurrency-group-list" + examples: + default: + "$ref": "#/components/examples/concurrency-group-list" + headers: + Link: + "$ref": "#/components/headers/link" + '422': + "$ref": "#/components/responses/validation_failed" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": + get: + summary: Get a concurrency group for a repository + description: |- + Gets a specific concurrency group for a repository, including all instances in the group's queue. + Returns 404 if the group is inactive or does not exist. + + Optionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items + ahead of the specified workflow run or job in the queue, plus the specified item itself + (returned as the last element). This is useful for determining what is blocking a particular + run or job. Returns 422 if the specified run or job is not in this concurrency group. + + When using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow + leases held on behalf of that run. Job-level leases within the run are not considered to + block the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow + leases on the job's ancestor paths. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/get-concurrency-group-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository + parameters: + - "$ref": "#/components/parameters/owner" + - "$ref": "#/components/parameters/repo" + - "$ref": "#/components/parameters/concurrency-group-name" + - name: ahead_of_run + description: |- + Filter to items ahead of this workflow run ID in the queue, plus the run itself. + Matches workflow-level concurrency and reusable-workflow leases held on behalf of + the run. Mutually exclusive with `ahead_of_job`. + in: query + required: false + schema: + type: integer + minimum: 1 + - name: ahead_of_job + description: |- + Filter to items ahead of this job ID in the queue, plus the job itself. + Matches job-level concurrency and reusable-workflow leases on the job's + ancestor paths. Mutually exclusive with `ahead_of_run`. + in: query + required: false + schema: + type: integer + minimum: 1 + responses: + '200': + description: Response + content: + application/json: + schema: + "$ref": "#/components/schemas/concurrency-group" + examples: + default: + "$ref": "#/components/examples/concurrency-group" + '404': + "$ref": "#/components/responses/not_found" + '422': + "$ref": "#/components/responses/validation_failed" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/jobs/{job_id}": get: summary: Get a job for a workflow run @@ -27310,6 +29966,64 @@ paths: enabledForGitHubApps: true category: actions subcategory: workflow-runs + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": + get: + summary: List concurrency groups for a workflow run + description: |- + Lists all concurrency groups associated with a workflow run or its jobs. + + The set of groups is derived from the run's configuration, so a group is + included even when the run no longer has any items currently holding or + waiting in it. In that case the `group_members` array will be empty. + `total_count` reflects the number of groups the run participates in by + configuration, not the number with active items. + + This differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`, + which returns 404 when a group has no active items. That endpoint reports + the live state of a group repo-wide, while this endpoint reports the + groups associated with a specific run by configuration. + + Results are sorted by group name and support cursor-based pagination via + `before` and `after`. The `after` cursor paginates forward only and does + not emit a `rel="prev"` Link; use `before` to page backward from a + forward page's `next` cursor. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-workflow-run + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run + parameters: + - "$ref": "#/components/parameters/owner" + - "$ref": "#/components/parameters/repo" + - "$ref": "#/components/parameters/run-id" + - "$ref": "#/components/parameters/per-page" + - "$ref": "#/components/parameters/pagination-before" + - "$ref": "#/components/parameters/pagination-after" + responses: + '200': + description: Response + content: + application/json: + schema: + "$ref": "#/components/schemas/concurrency-group-run-list" + examples: + default: + "$ref": "#/components/examples/concurrency-group-run-list" + headers: + Link: + "$ref": "#/components/headers/link" + '404': + "$ref": "#/components/responses/not_found" + '422': + "$ref": "#/components/responses/validation_failed" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": post: summary: Review custom deployment protection rules for a workflow run @@ -89039,6 +91753,7 @@ components: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp type: string url: description: The URL of the private registry. @@ -89104,6 +91819,14 @@ components: api_host: description: The Cloudsmith API host. type: string + workload_identity_provider: + description: The full resource name of the GCP Workload Identity Provider + (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + type: string + service_account: + description: The GCP service account email to impersonate. If omitted, the + federated token is used directly (direct WIF). + type: string created_at: type: string format: date-time @@ -89153,6 +91876,7 @@ components: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp type: string url: description: The URL of the private registry. @@ -89224,6 +91948,14 @@ components: api_host: description: The Cloudsmith API host. type: string + workload_identity_provider: + description: The full resource name of the GCP Workload Identity Provider + (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + type: string + service_account: + description: The GCP service account email to impersonate. If omitted, the + federated token is used directly (direct WIF). + type: string created_at: type: string format: date-time @@ -94386,6 +97118,107 @@ components: required: - total_count - actions_caches + concurrency-group-list: + title: Concurrency Group List + description: A list of active concurrency groups for a repository. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - last_acquired_at + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + last_acquired_at: + type: string + format: date-time + nullable: true + concurrency-group: + title: Concurrency Group + description: |- + A concurrency group with the workflow runs and jobs that are either currently holding + or waiting for the concurrency group lease. + type: object + required: + - group_name + - group_url + - total_count + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + total_count: + type: integer + group_members: + type: array + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: string + format: uri + description: API URL for the workflow run. + nullable: true + run_html_url: + type: string + format: uri + description: Web URL for the workflow run. + nullable: true + job_id: + type: integer + description: The ID of the job, when the item represents a job-level + or reusable-workflow-level lease. + job_name: + type: string + description: The display name of the job, when the item represents + a job-level or reusable-workflow-level lease. + job_url: + type: string + format: uri + description: API URL for the job. + nullable: true + job_html_url: + type: string + format: uri + description: Web URL for the job. + nullable: true + status: + type: string + enum: + - in_progress + - pending job: title: Job description: Information of a job execution in a workflow run @@ -94992,6 +97825,110 @@ components: - state - user - comment + concurrency-group-run-list: + title: Concurrency Group Run List + description: A list of concurrency groups associated with a workflow run. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + description: |- + The total number of concurrency groups this workflow run participates in, + derived from the run's configuration. This count is not filtered by + whether the run currently holds or is waiting in each group, so it can + include groups whose `group_members` array is empty (for example, when + the run has already released its lease in that group). + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: |- + API URL for this concurrency group. May return 404 if the group + has no active items at the time it is requested, since the + get-by-name endpoint reports the live repo-wide state of a group + while this endpoint lists groups associated with a run by + configuration. + group_members: + type: array + description: |- + Items belonging to this workflow run that are either currently holding or + waiting for the concurrency group lease. May be empty if the run no + longer has any active or queued items in this group. + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + - position + - position_url + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: string + format: uri + description: API URL for the workflow run. + nullable: true + run_html_url: + type: string + format: uri + description: Web URL for the workflow run. + nullable: true + position: + type: integer + description: Queue position. 0 means the item holds the concurrency + lease (in_progress), 1 or higher means queued (pending). + position_url: + type: string + format: uri + description: API URL to get items ahead of this item in the + concurrency group. + job_id: + type: integer + description: The ID of the job, when the item represents a job-level + or reusable-workflow-level lease. + nullable: true + job_name: + type: string + description: The display name of the job, when the item represents + a job-level or reusable-workflow-level lease. + nullable: true + job_url: + type: string + format: uri + description: API URL for the job. + nullable: true + job_html_url: + type: string + format: uri + description: Web URL for the job. + nullable: true + status: + type: string + enum: + - in_progress + - pending review-custom-gates-comment-required: type: object properties: @@ -227410,6 +230347,41 @@ components: last_accessed_at: '2019-01-24T22:45:36.000Z' created_at: '2019-01-24T22:45:36.000Z' size_in_bytes: 1024 + concurrency-group-list: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + last_acquired_at: '2026-01-15T16:14:23Z' + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + last_acquired_at: '2026-01-15T16:13:55Z' + concurrency-group: + value: + group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + total_count: 3 + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + - run_id: 30433643 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433643 + status: pending + - run_id: 30433644 + run_name: Deploy hotfix + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644 + job_id: 798245260 + job_name: deploy + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260 + status: pending job: value: id: 399444496 @@ -228086,6 +231058,34 @@ components: runner_group_name: my runner group workflow_name: CI head_branch: main + concurrency-group-run-list: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + position: 0 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642 + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: pending + position: 2 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260 + job_id: 798245260 + job_name: build + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260 pending-deployment-items: value: - environment: @@ -245420,6 +248420,13 @@ components: required: true schema: type: integer + concurrency-group-name: + name: concurrency_group_name + description: The name of the concurrency group. + in: path + required: true + schema: + type: string job-id: name: job_id description: The unique identifier of the job. diff --git a/descriptions/api.github.com/api.github.com.json b/descriptions/api.github.com/api.github.com.json index 805b21cf4..b82aed9d0 100644 --- a/descriptions/api.github.com/api.github.com.json +++ b/descriptions/api.github.com/api.github.com.json @@ -530,6 +530,3164 @@ } } }, + "/agents/repos/{owner}/{repo}/tasks": { + "get": { + "summary": "List tasks for repository", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for a specific repository\n\n**Fine-grained access tokens for \"List tasks for repository\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks-for-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks-for-repository" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "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`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + }, + { + "name": "creator_id", + "in": "query", + "schema": { + "type": "integer" + }, + "description": "Filter tasks by creator user ID" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"prev\" (when current page > 1),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + }, + "post": { + "summary": "Start a task", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nStarts a new Copilot cloud agent task for a repository.\n\nThis endpoint is only available to users with a Copilot Business or Copilot Enterprise subscription.\n\n**Fine-grained access tokens for \"Start a task\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read and write)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/create-task-in-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#start-a-task" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + } + ], + "requestBody": { + "required": true, + "description": "The task creation parameters, including the user's prompt and optional agent settings.", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "prompt" + ], + "properties": { + "prompt": { + "type": "string", + "description": "The user's prompt for the agent" + }, + "model": { + "type": "string", + "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`" + }, + "create_pull_request": { + "type": "boolean", + "description": "Whether to create a PR.", + "default": false + }, + "base_ref": { + "type": "string", + "description": "Base ref for new branch/PR" + } + } + }, + "examples": { + "default": { + "value": { + "prompt": "Fix the login button on the homepage", + "base_ref": "main" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Task created successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "examples": { + "default": { + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "queued", + "session_count": 1, + "artifacts": [], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T00:00:00Z" + } + } + } + } + } + }, + "400": { + "description": "Problems parsing JSON", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/repos/{owner}/{repo}/tasks/{task_id}": { + "get": { + "summary": "Get a task by repo", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID scoped to an owner/repo path\n\n**Fine-grained access tokens for \"Get a task by repo\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-repo-and-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-repo" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks": { + "get": { + "summary": "List tasks", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for the authenticated user\n\n**Fine-grained access tokens for \"List tasks\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "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`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks/{task_id}": { + "get": { + "summary": "Get a task by ID", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID with its associated sessions\n\n**Fine-grained access tokens for \"Get a task by ID\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-id" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Problems parsing request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, "/app": { "get": { "summary": "Get the authenticated app", @@ -28143,7 +31301,7 @@ }, "post": { "summary": "Create a private registry for an organization", - "description": "\nCreates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", + "description": "\nCreates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", "tags": [ "private-registries" ], @@ -28226,7 +31384,387 @@ } }, "auth_type": { - "description": "The authentication type for the private registry. Defaults to `token` if not specified. Use `oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith` for OIDC authentication.", + "description": "The authentication type for the private registry. Defaults to `token` if not specified. Use `oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp` for OIDC authentication.", + "type": "string", + "enum": [ + "token", + "username_password", + "oidc_azure", + "oidc_aws", + "oidc_jfrog", + "oidc_cloudsmith", + "oidc_gcp" + ] + }, + "tenant_id": { + "description": "The tenant ID of the Azure AD application. Required when `auth_type` is `oidc_azure`.", + "type": "string" + }, + "client_id": { + "description": "The client ID of the Azure AD application. Required when `auth_type` is `oidc_azure`.", + "type": "string" + }, + "aws_region": { + "description": "The AWS region. Required when `auth_type` is `oidc_aws`.", + "type": "string" + }, + "account_id": { + "description": "The AWS account ID. Required when `auth_type` is `oidc_aws`.", + "type": "string" + }, + "role_name": { + "description": "The AWS IAM role name. Required when `auth_type` is `oidc_aws`.", + "type": "string" + }, + "domain": { + "description": "The CodeArtifact domain. Required when `auth_type` is `oidc_aws`.", + "type": "string" + }, + "domain_owner": { + "description": "The CodeArtifact domain owner (AWS account ID). Required when `auth_type` is `oidc_aws`.", + "type": "string" + }, + "jfrog_oidc_provider_name": { + "description": "The JFrog OIDC provider name. Required when `auth_type` is `oidc_jfrog`.", + "type": "string" + }, + "audience": { + "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and `oidc_gcp`, and required for `oidc_cloudsmith` auth types.", + "type": "string" + }, + "identity_mapping_name": { + "description": "The JFrog identity mapping name. Optional for `oidc_jfrog` auth type.", + "type": "string" + }, + "namespace": { + "description": "The Cloudsmith organization namespace. Required when `auth_type` is `oidc_cloudsmith`.", + "type": "string" + }, + "service_slug": { + "description": "The Cloudsmith service account slug. Required when `auth_type` is `oidc_cloudsmith`.", + "type": "string" + }, + "api_host": { + "description": "The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default.", + "type": "string" + }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). Required when `auth_type` is `oidc_gcp`.", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. Optional for `oidc_gcp` auth type. If omitted, the federated token is used directly (direct WIF).", + "type": "string" + } + }, + "required": [ + "registry_type", + "url", + "visibility" + ] + }, + "examples": { + "org-private-registry-with-private-visibility": { + "summary": "Example of a private registry configuration with private visibility", + "value": { + "registry_type": "maven_repository", + "url": "https://maven.pkg.github.com/organization/", + "username": "monalisa", + "replaces_base": true, + "encrypted_value": "c2VjcmV0", + "key_id": "012345678912345678", + "visibility": "private" + } + }, + "org-private-registry-with-selected-visibility": { + "summary": "Example of a private registry configuration with selected visibility", + "value": { + "registry_type": "maven_repository", + "url": "https://maven.pkg.github.com/organization/", + "username": "monalisa", + "encrypted_value": "c2VjcmV0", + "key_id": "012345678912345678", + "visibility": "selected", + "selected_repository_ids": [ + 1296269, + 1296280 + ] + } + }, + "org-private-registry-with-oidc-azure": { + "summary": "Example of an OIDC private registry configuration using Azure", + "value": { + "registry_type": "docker_registry", + "url": "https://myregistry.azurecr.io", + "auth_type": "oidc_azure", + "visibility": "all", + "tenant_id": "12345678-1234-1234-1234-123456789012", + "client_id": "abcdef01-2345-6789-abcd-ef0123456789" + } + }, + "org-private-registry-with-oidc-cloudsmith": { + "summary": "Example of an OIDC private registry configuration using Cloudsmith", + "value": { + "registry_type": "npm_registry", + "url": "https://npm.cloudsmith.io/my-org/my-repo/", + "auth_type": "oidc_cloudsmith", + "visibility": "all", + "namespace": "my-org", + "service_slug": "my-service-account", + "audience": "https://github.com/my-org" + } + }, + "org-private-registry-with-oidc-gcp": { + "summary": "Example of an OIDC private registry configuration using Google Cloud Artifact Registry", + "value": { + "registry_type": "docker_registry", + "url": "https://us-docker.pkg.dev/my-project/my-repo", + "auth_type": "oidc_gcp", + "visibility": "all", + "workload_identity_provider": "projects/123456789/locations/global/workloadIdentityPools/github-pool/providers/github-provider", + "service_account": "dependabot@my-project.iam.gserviceaccount.com" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "The organization private registry configuration", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/org-private-registry-configuration-with-selected-repositories" + }, + "examples": { + "org-private-registry-with-selected-visibility": { + "$ref": "#/components/examples/org-private-registry-configuration" + }, + "org-private-registry-with-private-visibility": { + "$ref": "#/components/examples/org-private-registry-configuration-with-selected-repositories" + } + } + } + } + }, + "404": { + "$ref": "#/components/responses/not_found" + }, + "422": { + "$ref": "#/components/responses/validation_failed" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "private-registries", + "subcategory": "organization-configurations" + } + } + }, + "/orgs/{org}/private-registries/public-key": { + "get": { + "summary": "Get private registries public key for an organization", + "description": "\nGets the org public key, which is needed to encrypt private registry secrets. You need to encrypt a secret before you can create or update secrets.\n\nOAuth tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", + "tags": [ + "private-registries" + ], + "operationId": "private-registries/get-org-public-key", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization" + }, + "parameters": [ + { + "$ref": "#/components/parameters/org" + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "key_id", + "key" + ], + "properties": { + "key_id": { + "description": "The identifier for the key.", + "example": "012345678912345678", + "type": "string" + }, + "key": { + "description": "The Base64 encoded public key.", + "example": "2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234", + "type": "string" + } + } + }, + "examples": { + "default": { + "$ref": "#/components/examples/private-registries-public-key" + } + } + } + }, + "headers": { + "Link": { + "$ref": "#/components/headers/link" + } + } + }, + "404": { + "$ref": "#/components/responses/not_found" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "private-registries", + "subcategory": "organization-configurations" + } + } + }, + "/orgs/{org}/private-registries/{secret_name}": { + "get": { + "summary": "Get a private registry for an organization", + "description": "\nGet the configuration of a single private registry defined for an organization, omitting its encrypted value.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", + "tags": [ + "private-registries" + ], + "operationId": "private-registries/get-org-private-registry", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/private-registries/organization-configurations#get-a-private-registry-for-an-organization" + }, + "parameters": [ + { + "$ref": "#/components/parameters/org" + }, + { + "$ref": "#/components/parameters/secret-name" + } + ], + "responses": { + "200": { + "description": "The specified private registry configuration for the organization", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/org-private-registry-configuration" + }, + "examples": { + "default": { + "$ref": "#/components/examples/org-private-registry-configuration" + } + } + } + } + }, + "404": { + "$ref": "#/components/responses/not_found" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "private-registries", + "subcategory": "organization-configurations" + } + }, + "patch": { + "summary": "Update a private registry for an organization", + "description": "\nUpdates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", + "tags": [ + "private-registries" + ], + "operationId": "private-registries/update-org-private-registry", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/private-registries/organization-configurations#update-a-private-registry-for-an-organization" + }, + "parameters": [ + { + "$ref": "#/components/parameters/org" + }, + { + "$ref": "#/components/parameters/secret-name" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "registry_type": { + "description": "The registry type.", + "type": "string", + "enum": [ + "maven_repository", + "nuget_feed", + "goproxy_server", + "npm_registry", + "rubygems_server", + "cargo_registry", + "composer_repository", + "docker_registry", + "git_source", + "helm_registry", + "hex_organization", + "hex_repository", + "pub_repository", + "python_index", + "terraform_registry" + ] + }, + "url": { + "description": "The URL of the private registry.", + "type": "string", + "format": "uri" + }, + "username": { + "description": "The username to use when authenticating with the private registry. This field should be omitted if the private registry does not require a username for authentication.", + "type": "string", + "nullable": true + }, + "replaces_base": { + "description": "Whether this private registry should replace the base registry (e.g., npmjs.org for npm, rubygems.org for rubygems). When set to `true`, Dependabot will only use this registry and will not fall back to the public registry. When set to `false` (default), Dependabot will use this registry for scoped packages but may fall back to the public registry for other packages.", + "type": "boolean", + "default": false + }, + "encrypted_value": { + "description": "The value for your secret, encrypted with [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages) using the public key retrieved from the [Get private registries public key for an organization](https://docs.github.com/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization) endpoint.", + "type": "string", + "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{4})$" + }, + "key_id": { + "description": "The ID of the key you used to encrypt the secret.", + "type": "string" + }, + "visibility": { + "description": "Which type of organization repositories have access to the private registry. `selected` means only the repositories specified by `selected_repository_ids` can access the private registry.", + "type": "string", + "enum": [ + "all", + "private", + "selected" + ] + }, + "selected_repository_ids": { + "description": "An array of repository IDs that can access the organization private registry. You can only provide a list of repository IDs when `visibility` is set to `selected`. This field should be omitted if `visibility` is set to `all` or `private`.", + "type": "array", + "items": { + "type": "integer" + } + }, + "auth_type": { + "description": "The authentication type for the private registry. This field cannot be changed after creation. If provided, it must match the existing `auth_type` of the configuration. To change the authentication type, delete and recreate the configuration.", "type": "string", "enum": [ "token", @@ -28234,7 +31772,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ] }, "tenant_id": { @@ -28270,7 +31809,7 @@ "type": "string" }, "audience": { - "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and required for `oidc_cloudsmith` auth types.", + "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and `oidc_gcp`, and required for `oidc_cloudsmith` auth types.", "type": "string" }, "identity_mapping_name": { @@ -28288,365 +31827,13 @@ "api_host": { "description": "The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default.", "type": "string" - } - }, - "required": [ - "registry_type", - "url", - "visibility" - ] - }, - "examples": { - "org-private-registry-with-private-visibility": { - "summary": "Example of a private registry configuration with private visibility", - "value": { - "registry_type": "maven_repository", - "url": "https://maven.pkg.github.com/organization/", - "username": "monalisa", - "replaces_base": true, - "encrypted_value": "c2VjcmV0", - "key_id": "012345678912345678", - "visibility": "private" - } - }, - "org-private-registry-with-selected-visibility": { - "summary": "Example of a private registry configuration with selected visibility", - "value": { - "registry_type": "maven_repository", - "url": "https://maven.pkg.github.com/organization/", - "username": "monalisa", - "encrypted_value": "c2VjcmV0", - "key_id": "012345678912345678", - "visibility": "selected", - "selected_repository_ids": [ - 1296269, - 1296280 - ] - } - }, - "org-private-registry-with-oidc-azure": { - "summary": "Example of an OIDC private registry configuration using Azure", - "value": { - "registry_type": "docker_registry", - "url": "https://myregistry.azurecr.io", - "auth_type": "oidc_azure", - "visibility": "all", - "tenant_id": "12345678-1234-1234-1234-123456789012", - "client_id": "abcdef01-2345-6789-abcd-ef0123456789" - } - }, - "org-private-registry-with-oidc-cloudsmith": { - "summary": "Example of an OIDC private registry configuration using Cloudsmith", - "value": { - "registry_type": "npm_registry", - "url": "https://npm.cloudsmith.io/my-org/my-repo/", - "auth_type": "oidc_cloudsmith", - "visibility": "all", - "namespace": "my-org", - "service_slug": "my-service-account", - "audience": "https://github.com/my-org" - } - } - } - } - } - }, - "responses": { - "201": { - "description": "The organization private registry configuration", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/org-private-registry-configuration-with-selected-repositories" - }, - "examples": { - "org-private-registry-with-selected-visibility": { - "$ref": "#/components/examples/org-private-registry-configuration" }, - "org-private-registry-with-private-visibility": { - "$ref": "#/components/examples/org-private-registry-configuration-with-selected-repositories" - } - } - } - } - }, - "404": { - "$ref": "#/components/responses/not_found" - }, - "422": { - "$ref": "#/components/responses/validation_failed" - } - }, - "x-github": { - "githubCloudOnly": false, - "enabledForGitHubApps": true, - "category": "private-registries", - "subcategory": "organization-configurations" - } - } - }, - "/orgs/{org}/private-registries/public-key": { - "get": { - "summary": "Get private registries public key for an organization", - "description": "\nGets the org public key, which is needed to encrypt private registry secrets. You need to encrypt a secret before you can create or update secrets.\n\nOAuth tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", - "tags": [ - "private-registries" - ], - "operationId": "private-registries/get-org-public-key", - "externalDocs": { - "description": "API method documentation", - "url": "https://docs.github.com/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization" - }, - "parameters": [ - { - "$ref": "#/components/parameters/org" - } - ], - "responses": { - "200": { - "description": "Response", - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "key_id", - "key" - ], - "properties": { - "key_id": { - "description": "The identifier for the key.", - "example": "012345678912345678", - "type": "string" - }, - "key": { - "description": "The Base64 encoded public key.", - "example": "2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234", - "type": "string" - } - } - }, - "examples": { - "default": { - "$ref": "#/components/examples/private-registries-public-key" - } - } - } - }, - "headers": { - "Link": { - "$ref": "#/components/headers/link" - } - } - }, - "404": { - "$ref": "#/components/responses/not_found" - } - }, - "x-github": { - "githubCloudOnly": false, - "enabledForGitHubApps": true, - "category": "private-registries", - "subcategory": "organization-configurations" - } - } - }, - "/orgs/{org}/private-registries/{secret_name}": { - "get": { - "summary": "Get a private registry for an organization", - "description": "\nGet the configuration of a single private registry defined for an organization, omitting its encrypted value.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", - "tags": [ - "private-registries" - ], - "operationId": "private-registries/get-org-private-registry", - "externalDocs": { - "description": "API method documentation", - "url": "https://docs.github.com/rest/private-registries/organization-configurations#get-a-private-registry-for-an-organization" - }, - "parameters": [ - { - "$ref": "#/components/parameters/org" - }, - { - "$ref": "#/components/parameters/secret-name" - } - ], - "responses": { - "200": { - "description": "The specified private registry configuration for the organization", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/org-private-registry-configuration" - }, - "examples": { - "default": { - "$ref": "#/components/examples/org-private-registry-configuration" - } - } - } - } - }, - "404": { - "$ref": "#/components/responses/not_found" - } - }, - "x-github": { - "githubCloudOnly": false, - "enabledForGitHubApps": true, - "category": "private-registries", - "subcategory": "organization-configurations" - } - }, - "patch": { - "summary": "Update a private registry for an organization", - "description": "\nUpdates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", - "tags": [ - "private-registries" - ], - "operationId": "private-registries/update-org-private-registry", - "externalDocs": { - "description": "API method documentation", - "url": "https://docs.github.com/rest/private-registries/organization-configurations#update-a-private-registry-for-an-organization" - }, - "parameters": [ - { - "$ref": "#/components/parameters/org" - }, - { - "$ref": "#/components/parameters/secret-name" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "registry_type": { - "description": "The registry type.", - "type": "string", - "enum": [ - "maven_repository", - "nuget_feed", - "goproxy_server", - "npm_registry", - "rubygems_server", - "cargo_registry", - "composer_repository", - "docker_registry", - "git_source", - "helm_registry", - "hex_organization", - "hex_repository", - "pub_repository", - "python_index", - "terraform_registry" - ] - }, - "url": { - "description": "The URL of the private registry.", - "type": "string", - "format": "uri" - }, - "username": { - "description": "The username to use when authenticating with the private registry. This field should be omitted if the private registry does not require a username for authentication.", - "type": "string", - "nullable": true - }, - "replaces_base": { - "description": "Whether this private registry should replace the base registry (e.g., npmjs.org for npm, rubygems.org for rubygems). When set to `true`, Dependabot will only use this registry and will not fall back to the public registry. When set to `false` (default), Dependabot will use this registry for scoped packages but may fall back to the public registry for other packages.", - "type": "boolean", - "default": false - }, - "encrypted_value": { - "description": "The value for your secret, encrypted with [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages) using the public key retrieved from the [Get private registries public key for an organization](https://docs.github.com/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization) endpoint.", - "type": "string", - "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{4})$" - }, - "key_id": { - "description": "The ID of the key you used to encrypt the secret.", - "type": "string" - }, - "visibility": { - "description": "Which type of organization repositories have access to the private registry. `selected` means only the repositories specified by `selected_repository_ids` can access the private registry.", - "type": "string", - "enum": [ - "all", - "private", - "selected" - ] - }, - "selected_repository_ids": { - "description": "An array of repository IDs that can access the organization private registry. You can only provide a list of repository IDs when `visibility` is set to `selected`. This field should be omitted if `visibility` is set to `all` or `private`.", - "type": "array", - "items": { - "type": "integer" - } - }, - "auth_type": { - "description": "The authentication type for the private registry. This field cannot be changed after creation. If provided, it must match the existing `auth_type` of the configuration. To change the authentication type, delete and recreate the configuration.", - "type": "string", - "enum": [ - "token", - "username_password", - "oidc_azure", - "oidc_aws", - "oidc_jfrog", - "oidc_cloudsmith" - ] - }, - "tenant_id": { - "description": "The tenant ID of the Azure AD application. Required when `auth_type` is `oidc_azure`.", - "type": "string" - }, - "client_id": { - "description": "The client ID of the Azure AD application. Required when `auth_type` is `oidc_azure`.", - "type": "string" - }, - "aws_region": { - "description": "The AWS region. Required when `auth_type` is `oidc_aws`.", - "type": "string" - }, - "account_id": { - "description": "The AWS account ID. Required when `auth_type` is `oidc_aws`.", - "type": "string" - }, - "role_name": { - "description": "The AWS IAM role name. Required when `auth_type` is `oidc_aws`.", + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). Required when `auth_type` is `oidc_gcp`.", "type": "string" }, - "domain": { - "description": "The CodeArtifact domain. Required when `auth_type` is `oidc_aws`.", - "type": "string" - }, - "domain_owner": { - "description": "The CodeArtifact domain owner (AWS account ID). Required when `auth_type` is `oidc_aws`.", - "type": "string" - }, - "jfrog_oidc_provider_name": { - "description": "The JFrog OIDC provider name. Required when `auth_type` is `oidc_jfrog`.", - "type": "string" - }, - "audience": { - "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and required for `oidc_cloudsmith` auth types.", - "type": "string" - }, - "identity_mapping_name": { - "description": "The JFrog identity mapping name. Optional for `oidc_jfrog` auth type.", - "type": "string" - }, - "namespace": { - "description": "The Cloudsmith organization namespace. Required when `auth_type` is `oidc_cloudsmith`.", - "type": "string" - }, - "service_slug": { - "description": "The Cloudsmith service account slug. Required when `auth_type` is `oidc_cloudsmith`.", - "type": "string" - }, - "api_host": { - "description": "The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default.", + "service_account": { + "description": "The GCP service account email to impersonate. Optional for `oidc_gcp` auth type. If omitted, the federated token is used directly (direct WIF).", "type": "string" } } @@ -35278,6 +38465,139 @@ } } }, + "/repos/{owner}/{repo}/actions/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a repository", + "description": "Lists the active concurrency groups for a repository.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository" + }, + "parameters": [ + { + "$ref": "#/components/parameters/owner" + }, + { + "$ref": "#/components/parameters/repo" + }, + { + "$ref": "#/components/parameters/per-page" + }, + { + "$ref": "#/components/parameters/pagination-after" + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/concurrency-group-list" + }, + "examples": { + "default": { + "$ref": "#/components/examples/concurrency-group-list" + } + } + } + }, + "headers": { + "Link": { + "$ref": "#/components/headers/link" + } + } + }, + "422": { + "$ref": "#/components/responses/validation_failed" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": { + "get": { + "summary": "Get a concurrency group for a repository", + "description": "Gets a specific concurrency group for a repository, including all instances in the group's queue.\nReturns 404 if the group is inactive or does not exist.\n\nOptionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items\nahead of the specified workflow run or job in the queue, plus the specified item itself\n(returned as the last element). This is useful for determining what is blocking a particular\nrun or job. Returns 422 if the specified run or job is not in this concurrency group.\n\nWhen using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow\nleases held on behalf of that run. Job-level leases within the run are not considered to\nblock the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow\nleases on the job's ancestor paths.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/get-concurrency-group-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository" + }, + "parameters": [ + { + "$ref": "#/components/parameters/owner" + }, + { + "$ref": "#/components/parameters/repo" + }, + { + "$ref": "#/components/parameters/concurrency-group-name" + }, + { + "name": "ahead_of_run", + "description": "Filter to items ahead of this workflow run ID in the queue, plus the run itself.\nMatches workflow-level concurrency and reusable-workflow leases held on behalf of\nthe run. Mutually exclusive with `ahead_of_job`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + }, + { + "name": "ahead_of_job", + "description": "Filter to items ahead of this job ID in the queue, plus the job itself.\nMatches job-level concurrency and reusable-workflow leases on the job's\nancestor paths. Mutually exclusive with `ahead_of_run`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/concurrency-group" + }, + "examples": { + "default": { + "$ref": "#/components/examples/concurrency-group" + } + } + } + } + }, + "404": { + "$ref": "#/components/responses/not_found" + }, + "422": { + "$ref": "#/components/responses/validation_failed" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/jobs/{job_id}": { "get": { "summary": "Get a job for a workflow run", @@ -37689,6 +41009,74 @@ } } }, + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a workflow run", + "description": "Lists all concurrency groups associated with a workflow run or its jobs.\n\nThe set of groups is derived from the run's configuration, so a group is\nincluded even when the run no longer has any items currently holding or\nwaiting in it. In that case the `group_members` array will be empty.\n`total_count` reflects the number of groups the run participates in by\nconfiguration, not the number with active items.\n\nThis differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`,\nwhich returns 404 when a group has no active items. That endpoint reports\nthe live state of a group repo-wide, while this endpoint reports the\ngroups associated with a specific run by configuration.\n\nResults are sorted by group name and support cursor-based pagination via\n`before` and `after`. The `after` cursor paginates forward only and does\nnot emit a `rel=\"prev\"` Link; use `before` to page backward from a\nforward page's `next` cursor.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-workflow-run", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run" + }, + "parameters": [ + { + "$ref": "#/components/parameters/owner" + }, + { + "$ref": "#/components/parameters/repo" + }, + { + "$ref": "#/components/parameters/run-id" + }, + { + "$ref": "#/components/parameters/per-page" + }, + { + "$ref": "#/components/parameters/pagination-before" + }, + { + "$ref": "#/components/parameters/pagination-after" + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/concurrency-group-run-list" + }, + "examples": { + "default": { + "$ref": "#/components/examples/concurrency-group-run-list" + } + } + } + }, + "headers": { + "Link": { + "$ref": "#/components/headers/link" + } + } + }, + "404": { + "$ref": "#/components/responses/not_found" + }, + "422": { + "$ref": "#/components/responses/validation_failed" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": { "post": { "summary": "Review custom deployment protection rules for a workflow run", @@ -122787,7 +126175,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ], "type": "string" }, @@ -122868,6 +126257,14 @@ "description": "The Cloudsmith API host.", "type": "string" }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`).", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. If omitted, the federated token is used directly (direct WIF).", + "type": "string" + }, "created_at": { "type": "string", "format": "date-time" @@ -122924,7 +126321,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ], "type": "string" }, @@ -123011,6 +126409,14 @@ "description": "The Cloudsmith API host.", "type": "string" }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`).", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. If omitted, the federated token is used directly (direct WIF).", + "type": "string" + }, "created_at": { "type": "string", "format": "date-time" @@ -130037,6 +133443,134 @@ "actions_caches" ] }, + "concurrency-group-list": { + "title": "Concurrency Group List", + "description": "A list of active concurrency groups for a repository.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer" + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "last_acquired_at" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "last_acquired_at": { + "type": "string", + "format": "date-time", + "nullable": true + } + } + } + } + } + }, + "concurrency-group": { + "title": "Concurrency Group", + "description": "A concurrency group with the workflow runs and jobs that are either currently holding\nor waiting for the concurrency group lease.", + "type": "object", + "required": [ + "group_name", + "group_url", + "total_count", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "total_count": { + "type": "integer" + }, + "group_members": { + "type": "array", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": "string", + "format": "uri", + "description": "API URL for the workflow run.", + "nullable": true + }, + "run_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the workflow run.", + "nullable": true + }, + "job_id": { + "type": "integer", + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_name": { + "type": "string", + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_url": { + "type": "string", + "format": "uri", + "description": "API URL for the job.", + "nullable": true + }, + "job_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the job.", + "nullable": true + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + }, "job": { "title": "Job", "description": "Information of a job execution in a workflow run", @@ -130771,6 +134305,119 @@ "comment" ] }, + "concurrency-group-run-list": { + "title": "Concurrency Group Run List", + "description": "A list of concurrency groups associated with a workflow run.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer", + "description": "The total number of concurrency groups this workflow run participates in,\nderived from the run's configuration. This count is not filtered by\nwhether the run currently holds or is waiting in each group, so it can\ninclude groups whose `group_members` array is empty (for example, when\nthe run has already released its lease in that group)." + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group. May return 404 if the group\nhas no active items at the time it is requested, since the\nget-by-name endpoint reports the live repo-wide state of a group\nwhile this endpoint lists groups associated with a run by\nconfiguration." + }, + "group_members": { + "type": "array", + "description": "Items belonging to this workflow run that are either currently holding or\nwaiting for the concurrency group lease. May be empty if the run no\nlonger has any active or queued items in this group.", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status", + "position", + "position_url" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": "string", + "format": "uri", + "description": "API URL for the workflow run.", + "nullable": true + }, + "run_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the workflow run.", + "nullable": true + }, + "position": { + "type": "integer", + "description": "Queue position. 0 means the item holds the concurrency lease (in_progress), 1 or higher means queued (pending)." + }, + "position_url": { + "type": "string", + "format": "uri", + "description": "API URL to get items ahead of this item in the concurrency group." + }, + "job_id": { + "type": "integer", + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease.", + "nullable": true + }, + "job_name": { + "type": "string", + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease.", + "nullable": true + }, + "job_url": { + "type": "string", + "format": "uri", + "description": "API URL for the job.", + "nullable": true + }, + "job_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the job.", + "nullable": true + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + } + } + } + }, "review-custom-gates-comment-required": { "type": "object", "properties": { @@ -305500,6 +309147,57 @@ ] } }, + "concurrency-group-list": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "last_acquired_at": "2026-01-15T16:14:23Z" + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "last_acquired_at": "2026-01-15T16:13:55Z" + } + ] + } + }, + "concurrency-group": { + "value": { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "total_count": 3, + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress" + }, + { + "run_id": 30433643, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433643", + "status": "pending" + }, + { + "run_id": 30433644, + "run_name": "Deploy hotfix", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644", + "job_id": 798245260, + "job_name": "deploy", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260", + "status": "pending" + } + ] + } + }, "job": { "value": { "id": 399444496, @@ -306288,6 +309986,47 @@ ] } }, + "concurrency-group-run-list": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress", + "position": 0, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642" + } + ] + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "pending", + "position": 2, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260", + "job_id": 798245260, + "job_name": "build", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260" + } + ] + } + ] + } + }, "pending-deployment-items": { "value": [ { @@ -326550,6 +330289,15 @@ "type": "integer" } }, + "concurrency-group-name": { + "name": "concurrency_group_name", + "description": "The name of the concurrency group.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, "job-id": { "name": "job_id", "description": "The unique identifier of the job.", diff --git a/descriptions/api.github.com/api.github.com.yaml b/descriptions/api.github.com/api.github.com.yaml index e056574f0..59ac047a6 100644 --- a/descriptions/api.github.com/api.github.com.yaml +++ b/descriptions/api.github.com/api.github.com.yaml @@ -343,6 +343,2525 @@ paths: enabledForGitHubApps: true category: security-advisories subcategory: global-advisories + "/agents/repos/{owner}/{repo}/tasks": + get: + summary: List tasks for repository + description: | + > [!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](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks-for-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks-for-repository + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: '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`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + - name: creator_id + in: query + schema: + type: integer + description: Filter tasks by creator user ID + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="prev" (when current page > 1), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; + rel="next", ; + rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + post: + summary: Start a task + description: | + > [!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](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/create-task-in-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#start-a-task + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + requestBody: + required: true + description: The task creation parameters, including the user's prompt and + optional agent settings. + content: + application/json: + schema: + type: object + required: + - prompt + properties: + prompt: + type: string + description: The user's prompt for the agent + model: + type: string + 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`' + create_pull_request: + type: boolean + description: Whether to create a PR. + default: false + base_ref: + type: string + description: Base ref for new branch/PR + examples: + default: + value: + prompt: Fix the login button on the homepage + base_ref: main + responses: + '201': + description: Task created successfully + content: + application/json: + schema: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + examples: + default: + value: + id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: queued + session_count: 1 + artifacts: [] + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T00:00:00Z' + '400': + description: Problems parsing JSON + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/repos/{owner}/{repo}/tasks/{task_id}": + get: + summary: Get a task by repo + description: | + > [!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](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-repo-and-id + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-repo + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks": + get: + summary: List tasks + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a list of tasks for the authenticated user + + **Fine-grained access tokens for "List tasks"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: '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`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; rel="next", + ; rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks/{task_id}": + get: + summary: Get a task by ID + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a task by ID with its associated sessions + + **Fine-grained access tokens for "Get a task by ID"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-id + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-id + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Problems parsing request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation "/app": get: summary: Get the authenticated app @@ -20512,7 +23031,7 @@ paths: description: |2- Creates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see "[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api)." - For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted. + For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted. OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. tags: @@ -20605,7 +23124,332 @@ paths: auth_type: description: The authentication type for the private registry. Defaults to `token` if not specified. Use `oidc_azure`, `oidc_aws`, `oidc_jfrog`, - or `oidc_cloudsmith` for OIDC authentication. + `oidc_cloudsmith`, or `oidc_gcp` for OIDC authentication. + type: string + enum: + - token + - username_password + - oidc_azure + - oidc_aws + - oidc_jfrog + - oidc_cloudsmith + - oidc_gcp + tenant_id: + description: The tenant ID of the Azure AD application. Required + when `auth_type` is `oidc_azure`. + type: string + client_id: + description: The client ID of the Azure AD application. Required + when `auth_type` is `oidc_azure`. + type: string + aws_region: + description: The AWS region. Required when `auth_type` is `oidc_aws`. + type: string + account_id: + description: The AWS account ID. Required when `auth_type` is `oidc_aws`. + type: string + role_name: + description: The AWS IAM role name. Required when `auth_type` is + `oidc_aws`. + type: string + domain: + description: The CodeArtifact domain. Required when `auth_type` + is `oidc_aws`. + type: string + domain_owner: + description: The CodeArtifact domain owner (AWS account ID). Required + when `auth_type` is `oidc_aws`. + type: string + jfrog_oidc_provider_name: + description: The JFrog OIDC provider name. Required when `auth_type` + is `oidc_jfrog`. + type: string + audience: + description: The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, + and `oidc_gcp`, and required for `oidc_cloudsmith` auth types. + type: string + identity_mapping_name: + description: The JFrog identity mapping name. Optional for `oidc_jfrog` + auth type. + type: string + namespace: + description: The Cloudsmith organization namespace. Required when + `auth_type` is `oidc_cloudsmith`. + type: string + service_slug: + description: The Cloudsmith service account slug. Required when + `auth_type` is `oidc_cloudsmith`. + type: string + api_host: + description: The Cloudsmith API host. Optional for `oidc_cloudsmith` + auth type. If omitted, `api.cloudsmith.io` is used by default. + type: string + workload_identity_provider: + description: The full resource name of the GCP Workload Identity + Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + Required when `auth_type` is `oidc_gcp`. + type: string + service_account: + description: The GCP service account email to impersonate. Optional + for `oidc_gcp` auth type. If omitted, the federated token is used + directly (direct WIF). + type: string + required: + - registry_type + - url + - visibility + examples: + org-private-registry-with-private-visibility: + summary: Example of a private registry configuration with private + visibility + value: + registry_type: maven_repository + url: https://maven.pkg.github.com/organization/ + username: monalisa + replaces_base: true + encrypted_value: c2VjcmV0 + key_id: '012345678912345678' + visibility: private + org-private-registry-with-selected-visibility: + summary: Example of a private registry configuration with selected + visibility + value: + registry_type: maven_repository + url: https://maven.pkg.github.com/organization/ + username: monalisa + encrypted_value: c2VjcmV0 + key_id: '012345678912345678' + visibility: selected + selected_repository_ids: + - 1296269 + - 1296280 + org-private-registry-with-oidc-azure: + summary: Example of an OIDC private registry configuration using Azure + value: + registry_type: docker_registry + url: https://myregistry.azurecr.io + auth_type: oidc_azure + visibility: all + tenant_id: 12345678-1234-1234-1234-123456789012 + client_id: abcdef01-2345-6789-abcd-ef0123456789 + org-private-registry-with-oidc-cloudsmith: + summary: Example of an OIDC private registry configuration using Cloudsmith + value: + registry_type: npm_registry + url: https://npm.cloudsmith.io/my-org/my-repo/ + auth_type: oidc_cloudsmith + visibility: all + namespace: my-org + service_slug: my-service-account + audience: https://github.com/my-org + org-private-registry-with-oidc-gcp: + summary: Example of an OIDC private registry configuration using Google + Cloud Artifact Registry + value: + registry_type: docker_registry + url: https://us-docker.pkg.dev/my-project/my-repo + auth_type: oidc_gcp + visibility: all + workload_identity_provider: projects/123456789/locations/global/workloadIdentityPools/github-pool/providers/github-provider + service_account: dependabot@my-project.iam.gserviceaccount.com + responses: + '201': + description: The organization private registry configuration + content: + application/json: + schema: + "$ref": "#/components/schemas/org-private-registry-configuration-with-selected-repositories" + examples: + org-private-registry-with-selected-visibility: + "$ref": "#/components/examples/org-private-registry-configuration" + org-private-registry-with-private-visibility: + "$ref": "#/components/examples/org-private-registry-configuration-with-selected-repositories" + '404': + "$ref": "#/components/responses/not_found" + '422': + "$ref": "#/components/responses/validation_failed" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: private-registries + subcategory: organization-configurations + "/orgs/{org}/private-registries/public-key": + get: + summary: Get private registries public key for an organization + description: |2- + + Gets the org public key, which is needed to encrypt private registry secrets. You need to encrypt a secret before you can create or update secrets. + + OAuth tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. + tags: + - private-registries + operationId: private-registries/get-org-public-key + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization + parameters: + - "$ref": "#/components/parameters/org" + responses: + '200': + description: Response + content: + application/json: + schema: + type: object + required: + - key_id + - key + properties: + key_id: + description: The identifier for the key. + example: '012345678912345678' + type: string + key: + description: The Base64 encoded public key. + example: 2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234 + type: string + examples: + default: + "$ref": "#/components/examples/private-registries-public-key" + headers: + Link: + "$ref": "#/components/headers/link" + '404': + "$ref": "#/components/responses/not_found" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: private-registries + subcategory: organization-configurations + "/orgs/{org}/private-registries/{secret_name}": + get: + summary: Get a private registry for an organization + description: |2- + + Get the configuration of a single private registry defined for an organization, omitting its encrypted value. + + OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. + tags: + - private-registries + operationId: private-registries/get-org-private-registry + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/private-registries/organization-configurations#get-a-private-registry-for-an-organization + parameters: + - "$ref": "#/components/parameters/org" + - "$ref": "#/components/parameters/secret-name" + responses: + '200': + description: The specified private registry configuration for the organization + content: + application/json: + schema: + "$ref": "#/components/schemas/org-private-registry-configuration" + examples: + default: + "$ref": "#/components/examples/org-private-registry-configuration" + '404': + "$ref": "#/components/responses/not_found" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: private-registries + subcategory: organization-configurations + patch: + summary: Update a private registry for an organization + description: |2- + + Updates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see "[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api)." + For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted. + + OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. + tags: + - private-registries + operationId: private-registries/update-org-private-registry + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/private-registries/organization-configurations#update-a-private-registry-for-an-organization + parameters: + - "$ref": "#/components/parameters/org" + - "$ref": "#/components/parameters/secret-name" + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + registry_type: + description: The registry type. + type: string + enum: + - maven_repository + - nuget_feed + - goproxy_server + - npm_registry + - rubygems_server + - cargo_registry + - composer_repository + - docker_registry + - git_source + - helm_registry + - hex_organization + - hex_repository + - pub_repository + - python_index + - terraform_registry + url: + description: The URL of the private registry. + type: string + format: uri + username: + description: The username to use when authenticating with the private + registry. This field should be omitted if the private registry + does not require a username for authentication. + type: string + nullable: true + replaces_base: + description: Whether this private registry should replace the base + registry (e.g., npmjs.org for npm, rubygems.org for rubygems). + When set to `true`, Dependabot will only use this registry and + will not fall back to the public registry. When set to `false` + (default), Dependabot will use this registry for scoped packages + but may fall back to the public registry for other packages. + type: boolean + default: false + encrypted_value: + description: The value for your secret, encrypted with [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages) + using the public key retrieved from the [Get private registries + public key for an organization](https://docs.github.com/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization) + endpoint. + type: string + pattern: "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{4})$" + key_id: + description: The ID of the key you used to encrypt the secret. + type: string + visibility: + description: Which type of organization repositories have access + to the private registry. `selected` means only the repositories + specified by `selected_repository_ids` can access the private + registry. + type: string + enum: + - all + - private + - selected + selected_repository_ids: + description: An array of repository IDs that can access the organization + private registry. You can only provide a list of repository IDs + when `visibility` is set to `selected`. This field should be omitted + if `visibility` is set to `all` or `private`. + type: array + items: + type: integer + auth_type: + description: The authentication type for the private registry. This + field cannot be changed after creation. If provided, it must match + the existing `auth_type` of the configuration. To change the authentication + type, delete and recreate the configuration. type: string enum: - token @@ -20614,6 +23458,7 @@ paths: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp tenant_id: description: The tenant ID of the Azure AD application. Required when `auth_type` is `oidc_azure`. @@ -20646,7 +23491,7 @@ paths: type: string audience: description: The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, - and required for `oidc_cloudsmith` auth types. + and `oidc_gcp`, and required for `oidc_cloudsmith` auth types. type: string identity_mapping_name: description: The JFrog identity mapping name. Optional for `oidc_jfrog` @@ -20664,309 +23509,15 @@ paths: description: The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default. type: string - required: - - registry_type - - url - - visibility - examples: - org-private-registry-with-private-visibility: - summary: Example of a private registry configuration with private - visibility - value: - registry_type: maven_repository - url: https://maven.pkg.github.com/organization/ - username: monalisa - replaces_base: true - encrypted_value: c2VjcmV0 - key_id: '012345678912345678' - visibility: private - org-private-registry-with-selected-visibility: - summary: Example of a private registry configuration with selected - visibility - value: - registry_type: maven_repository - url: https://maven.pkg.github.com/organization/ - username: monalisa - encrypted_value: c2VjcmV0 - key_id: '012345678912345678' - visibility: selected - selected_repository_ids: - - 1296269 - - 1296280 - org-private-registry-with-oidc-azure: - summary: Example of an OIDC private registry configuration using Azure - value: - registry_type: docker_registry - url: https://myregistry.azurecr.io - auth_type: oidc_azure - visibility: all - tenant_id: 12345678-1234-1234-1234-123456789012 - client_id: abcdef01-2345-6789-abcd-ef0123456789 - org-private-registry-with-oidc-cloudsmith: - summary: Example of an OIDC private registry configuration using Cloudsmith - value: - registry_type: npm_registry - url: https://npm.cloudsmith.io/my-org/my-repo/ - auth_type: oidc_cloudsmith - visibility: all - namespace: my-org - service_slug: my-service-account - audience: https://github.com/my-org - responses: - '201': - description: The organization private registry configuration - content: - application/json: - schema: - "$ref": "#/components/schemas/org-private-registry-configuration-with-selected-repositories" - examples: - org-private-registry-with-selected-visibility: - "$ref": "#/components/examples/org-private-registry-configuration" - org-private-registry-with-private-visibility: - "$ref": "#/components/examples/org-private-registry-configuration-with-selected-repositories" - '404': - "$ref": "#/components/responses/not_found" - '422': - "$ref": "#/components/responses/validation_failed" - x-github: - githubCloudOnly: false - enabledForGitHubApps: true - category: private-registries - subcategory: organization-configurations - "/orgs/{org}/private-registries/public-key": - get: - summary: Get private registries public key for an organization - description: |2- - - Gets the org public key, which is needed to encrypt private registry secrets. You need to encrypt a secret before you can create or update secrets. - - OAuth tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. - tags: - - private-registries - operationId: private-registries/get-org-public-key - externalDocs: - description: API method documentation - url: https://docs.github.com/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization - parameters: - - "$ref": "#/components/parameters/org" - responses: - '200': - description: Response - content: - application/json: - schema: - type: object - required: - - key_id - - key - properties: - key_id: - description: The identifier for the key. - example: '012345678912345678' - type: string - key: - description: The Base64 encoded public key. - example: 2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234 - type: string - examples: - default: - "$ref": "#/components/examples/private-registries-public-key" - headers: - Link: - "$ref": "#/components/headers/link" - '404': - "$ref": "#/components/responses/not_found" - x-github: - githubCloudOnly: false - enabledForGitHubApps: true - category: private-registries - subcategory: organization-configurations - "/orgs/{org}/private-registries/{secret_name}": - get: - summary: Get a private registry for an organization - description: |2- - - Get the configuration of a single private registry defined for an organization, omitting its encrypted value. - - OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. - tags: - - private-registries - operationId: private-registries/get-org-private-registry - externalDocs: - description: API method documentation - url: https://docs.github.com/rest/private-registries/organization-configurations#get-a-private-registry-for-an-organization - parameters: - - "$ref": "#/components/parameters/org" - - "$ref": "#/components/parameters/secret-name" - responses: - '200': - description: The specified private registry configuration for the organization - content: - application/json: - schema: - "$ref": "#/components/schemas/org-private-registry-configuration" - examples: - default: - "$ref": "#/components/examples/org-private-registry-configuration" - '404': - "$ref": "#/components/responses/not_found" - x-github: - githubCloudOnly: false - enabledForGitHubApps: true - category: private-registries - subcategory: organization-configurations - patch: - summary: Update a private registry for an organization - description: |2- - - Updates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see "[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api)." - For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted. - - OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. - tags: - - private-registries - operationId: private-registries/update-org-private-registry - externalDocs: - description: API method documentation - url: https://docs.github.com/rest/private-registries/organization-configurations#update-a-private-registry-for-an-organization - parameters: - - "$ref": "#/components/parameters/org" - - "$ref": "#/components/parameters/secret-name" - requestBody: - required: true - content: - application/json: - schema: - type: object - properties: - registry_type: - description: The registry type. - type: string - enum: - - maven_repository - - nuget_feed - - goproxy_server - - npm_registry - - rubygems_server - - cargo_registry - - composer_repository - - docker_registry - - git_source - - helm_registry - - hex_organization - - hex_repository - - pub_repository - - python_index - - terraform_registry - url: - description: The URL of the private registry. - type: string - format: uri - username: - description: The username to use when authenticating with the private - registry. This field should be omitted if the private registry - does not require a username for authentication. - type: string - nullable: true - replaces_base: - description: Whether this private registry should replace the base - registry (e.g., npmjs.org for npm, rubygems.org for rubygems). - When set to `true`, Dependabot will only use this registry and - will not fall back to the public registry. When set to `false` - (default), Dependabot will use this registry for scoped packages - but may fall back to the public registry for other packages. - type: boolean - default: false - encrypted_value: - description: The value for your secret, encrypted with [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages) - using the public key retrieved from the [Get private registries - public key for an organization](https://docs.github.com/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization) - endpoint. - type: string - pattern: "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{4})$" - key_id: - description: The ID of the key you used to encrypt the secret. - type: string - visibility: - description: Which type of organization repositories have access - to the private registry. `selected` means only the repositories - specified by `selected_repository_ids` can access the private - registry. - type: string - enum: - - all - - private - - selected - selected_repository_ids: - description: An array of repository IDs that can access the organization - private registry. You can only provide a list of repository IDs - when `visibility` is set to `selected`. This field should be omitted - if `visibility` is set to `all` or `private`. - type: array - items: - type: integer - auth_type: - description: The authentication type for the private registry. This - field cannot be changed after creation. If provided, it must match - the existing `auth_type` of the configuration. To change the authentication - type, delete and recreate the configuration. + workload_identity_provider: + description: The full resource name of the GCP Workload Identity + Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + Required when `auth_type` is `oidc_gcp`. type: string - enum: - - token - - username_password - - oidc_azure - - oidc_aws - - oidc_jfrog - - oidc_cloudsmith - tenant_id: - description: The tenant ID of the Azure AD application. Required - when `auth_type` is `oidc_azure`. - type: string - client_id: - description: The client ID of the Azure AD application. Required - when `auth_type` is `oidc_azure`. - type: string - aws_region: - description: The AWS region. Required when `auth_type` is `oidc_aws`. - type: string - account_id: - description: The AWS account ID. Required when `auth_type` is `oidc_aws`. - type: string - role_name: - description: The AWS IAM role name. Required when `auth_type` is - `oidc_aws`. - type: string - domain: - description: The CodeArtifact domain. Required when `auth_type` - is `oidc_aws`. - type: string - domain_owner: - description: The CodeArtifact domain owner (AWS account ID). Required - when `auth_type` is `oidc_aws`. - type: string - jfrog_oidc_provider_name: - description: The JFrog OIDC provider name. Required when `auth_type` - is `oidc_jfrog`. - type: string - audience: - description: The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, - and required for `oidc_cloudsmith` auth types. - type: string - identity_mapping_name: - description: The JFrog identity mapping name. Optional for `oidc_jfrog` - auth type. - type: string - namespace: - description: The Cloudsmith organization namespace. Required when - `auth_type` is `oidc_cloudsmith`. - type: string - service_slug: - description: The Cloudsmith service account slug. Required when - `auth_type` is `oidc_cloudsmith`. - type: string - api_host: - description: The Cloudsmith API host. Optional for `oidc_cloudsmith` - auth type. If omitted, `api.cloudsmith.io` is used by default. + service_account: + description: The GCP service account email to impersonate. Optional + for `oidc_gcp` auth type. If omitted, the federated token is used + directly (direct WIF). type: string examples: secret-based-update: @@ -25759,6 +28310,111 @@ paths: enabledForGitHubApps: true category: actions subcategory: cache + "/repos/{owner}/{repo}/actions/concurrency_groups": + get: + summary: List concurrency groups for a repository + description: |- + Lists the active concurrency groups for a repository. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository + parameters: + - "$ref": "#/components/parameters/owner" + - "$ref": "#/components/parameters/repo" + - "$ref": "#/components/parameters/per-page" + - "$ref": "#/components/parameters/pagination-after" + responses: + '200': + description: Response + content: + application/json: + schema: + "$ref": "#/components/schemas/concurrency-group-list" + examples: + default: + "$ref": "#/components/examples/concurrency-group-list" + headers: + Link: + "$ref": "#/components/headers/link" + '422': + "$ref": "#/components/responses/validation_failed" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": + get: + summary: Get a concurrency group for a repository + description: |- + Gets a specific concurrency group for a repository, including all instances in the group's queue. + Returns 404 if the group is inactive or does not exist. + + Optionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items + ahead of the specified workflow run or job in the queue, plus the specified item itself + (returned as the last element). This is useful for determining what is blocking a particular + run or job. Returns 422 if the specified run or job is not in this concurrency group. + + When using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow + leases held on behalf of that run. Job-level leases within the run are not considered to + block the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow + leases on the job's ancestor paths. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/get-concurrency-group-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository + parameters: + - "$ref": "#/components/parameters/owner" + - "$ref": "#/components/parameters/repo" + - "$ref": "#/components/parameters/concurrency-group-name" + - name: ahead_of_run + description: |- + Filter to items ahead of this workflow run ID in the queue, plus the run itself. + Matches workflow-level concurrency and reusable-workflow leases held on behalf of + the run. Mutually exclusive with `ahead_of_job`. + in: query + required: false + schema: + type: integer + minimum: 1 + - name: ahead_of_job + description: |- + Filter to items ahead of this job ID in the queue, plus the job itself. + Matches job-level concurrency and reusable-workflow leases on the job's + ancestor paths. Mutually exclusive with `ahead_of_run`. + in: query + required: false + schema: + type: integer + minimum: 1 + responses: + '200': + description: Response + content: + application/json: + schema: + "$ref": "#/components/schemas/concurrency-group" + examples: + default: + "$ref": "#/components/examples/concurrency-group" + '404': + "$ref": "#/components/responses/not_found" + '422': + "$ref": "#/components/responses/validation_failed" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/jobs/{job_id}": get: summary: Get a job for a workflow run @@ -27460,6 +30116,64 @@ paths: enabledForGitHubApps: true category: actions subcategory: workflow-runs + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": + get: + summary: List concurrency groups for a workflow run + description: |- + Lists all concurrency groups associated with a workflow run or its jobs. + + The set of groups is derived from the run's configuration, so a group is + included even when the run no longer has any items currently holding or + waiting in it. In that case the `group_members` array will be empty. + `total_count` reflects the number of groups the run participates in by + configuration, not the number with active items. + + This differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`, + which returns 404 when a group has no active items. That endpoint reports + the live state of a group repo-wide, while this endpoint reports the + groups associated with a specific run by configuration. + + Results are sorted by group name and support cursor-based pagination via + `before` and `after`. The `after` cursor paginates forward only and does + not emit a `rel="prev"` Link; use `before` to page backward from a + forward page's `next` cursor. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-workflow-run + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run + parameters: + - "$ref": "#/components/parameters/owner" + - "$ref": "#/components/parameters/repo" + - "$ref": "#/components/parameters/run-id" + - "$ref": "#/components/parameters/per-page" + - "$ref": "#/components/parameters/pagination-before" + - "$ref": "#/components/parameters/pagination-after" + responses: + '200': + description: Response + content: + application/json: + schema: + "$ref": "#/components/schemas/concurrency-group-run-list" + examples: + default: + "$ref": "#/components/examples/concurrency-group-run-list" + headers: + Link: + "$ref": "#/components/headers/link" + '404': + "$ref": "#/components/responses/not_found" + '422': + "$ref": "#/components/responses/validation_failed" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": post: summary: Review custom deployment protection rules for a workflow run @@ -89941,6 +92655,7 @@ components: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp type: string url: description: The URL of the private registry. @@ -90006,6 +92721,14 @@ components: api_host: description: The Cloudsmith API host. type: string + workload_identity_provider: + description: The full resource name of the GCP Workload Identity Provider + (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + type: string + service_account: + description: The GCP service account email to impersonate. If omitted, the + federated token is used directly (direct WIF). + type: string created_at: type: string format: date-time @@ -90055,6 +92778,7 @@ components: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp type: string url: description: The URL of the private registry. @@ -90126,6 +92850,14 @@ components: api_host: description: The Cloudsmith API host. type: string + workload_identity_provider: + description: The full resource name of the GCP Workload Identity Provider + (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + type: string + service_account: + description: The GCP service account email to impersonate. If omitted, the + federated token is used directly (direct WIF). + type: string created_at: type: string format: date-time @@ -95637,6 +98369,107 @@ components: required: - total_count - actions_caches + concurrency-group-list: + title: Concurrency Group List + description: A list of active concurrency groups for a repository. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - last_acquired_at + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + last_acquired_at: + type: string + format: date-time + nullable: true + concurrency-group: + title: Concurrency Group + description: |- + A concurrency group with the workflow runs and jobs that are either currently holding + or waiting for the concurrency group lease. + type: object + required: + - group_name + - group_url + - total_count + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + total_count: + type: integer + group_members: + type: array + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: string + format: uri + description: API URL for the workflow run. + nullable: true + run_html_url: + type: string + format: uri + description: Web URL for the workflow run. + nullable: true + job_id: + type: integer + description: The ID of the job, when the item represents a job-level + or reusable-workflow-level lease. + job_name: + type: string + description: The display name of the job, when the item represents + a job-level or reusable-workflow-level lease. + job_url: + type: string + format: uri + description: API URL for the job. + nullable: true + job_html_url: + type: string + format: uri + description: Web URL for the job. + nullable: true + status: + type: string + enum: + - in_progress + - pending job: title: Job description: Information of a job execution in a workflow run @@ -96243,6 +99076,110 @@ components: - state - user - comment + concurrency-group-run-list: + title: Concurrency Group Run List + description: A list of concurrency groups associated with a workflow run. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + description: |- + The total number of concurrency groups this workflow run participates in, + derived from the run's configuration. This count is not filtered by + whether the run currently holds or is waiting in each group, so it can + include groups whose `group_members` array is empty (for example, when + the run has already released its lease in that group). + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: |- + API URL for this concurrency group. May return 404 if the group + has no active items at the time it is requested, since the + get-by-name endpoint reports the live repo-wide state of a group + while this endpoint lists groups associated with a run by + configuration. + group_members: + type: array + description: |- + Items belonging to this workflow run that are either currently holding or + waiting for the concurrency group lease. May be empty if the run no + longer has any active or queued items in this group. + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + - position + - position_url + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: string + format: uri + description: API URL for the workflow run. + nullable: true + run_html_url: + type: string + format: uri + description: Web URL for the workflow run. + nullable: true + position: + type: integer + description: Queue position. 0 means the item holds the concurrency + lease (in_progress), 1 or higher means queued (pending). + position_url: + type: string + format: uri + description: API URL to get items ahead of this item in the + concurrency group. + job_id: + type: integer + description: The ID of the job, when the item represents a job-level + or reusable-workflow-level lease. + nullable: true + job_name: + type: string + description: The display name of the job, when the item represents + a job-level or reusable-workflow-level lease. + nullable: true + job_url: + type: string + format: uri + description: API URL for the job. + nullable: true + job_html_url: + type: string + format: uri + description: Web URL for the job. + nullable: true + status: + type: string + enum: + - in_progress + - pending review-custom-gates-comment-required: type: object properties: @@ -229517,6 +232454,41 @@ components: last_accessed_at: '2019-01-24T22:45:36.000Z' created_at: '2019-01-24T22:45:36.000Z' size_in_bytes: 1024 + concurrency-group-list: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + last_acquired_at: '2026-01-15T16:14:23Z' + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + last_acquired_at: '2026-01-15T16:13:55Z' + concurrency-group: + value: + group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + total_count: 3 + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + - run_id: 30433643 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433643 + status: pending + - run_id: 30433644 + run_name: Deploy hotfix + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644 + job_id: 798245260 + job_name: deploy + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260 + status: pending job: value: id: 399444496 @@ -230193,6 +233165,34 @@ components: runner_group_name: my runner group workflow_name: CI head_branch: main + concurrency-group-run-list: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + position: 0 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642 + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: pending + position: 2 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260 + job_id: 798245260 + job_name: build + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260 pending-deployment-items: value: - environment: @@ -247676,6 +250676,13 @@ components: required: true schema: type: integer + concurrency-group-name: + name: concurrency_group_name + description: The name of the concurrency group. + in: path + required: true + schema: + type: string job-id: name: job_id description: The unique identifier of the job. diff --git a/descriptions/api.github.com/dereferenced/api.github.com.2022-11-28.deref.json b/descriptions/api.github.com/dereferenced/api.github.com.2022-11-28.deref.json index ac2c32de8..5fd9ae61a 100644 --- a/descriptions/api.github.com/dereferenced/api.github.com.2022-11-28.deref.json +++ b/descriptions/api.github.com/dereferenced/api.github.com.2022-11-28.deref.json @@ -2028,6 +2028,3164 @@ } } }, + "/agents/repos/{owner}/{repo}/tasks": { + "get": { + "summary": "List tasks for repository", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for a specific repository\n\n**Fine-grained access tokens for \"List tasks for repository\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks-for-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks-for-repository" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "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`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + }, + { + "name": "creator_id", + "in": "query", + "schema": { + "type": "integer" + }, + "description": "Filter tasks by creator user ID" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"prev\" (when current page > 1),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + }, + "post": { + "summary": "Start a task", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nStarts a new Copilot cloud agent task for a repository.\n\nThis endpoint is only available to users with a Copilot Business or Copilot Enterprise subscription.\n\n**Fine-grained access tokens for \"Start a task\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read and write)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/create-task-in-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#start-a-task" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + } + ], + "requestBody": { + "required": true, + "description": "The task creation parameters, including the user's prompt and optional agent settings.", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "prompt" + ], + "properties": { + "prompt": { + "type": "string", + "description": "The user's prompt for the agent" + }, + "model": { + "type": "string", + "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`" + }, + "create_pull_request": { + "type": "boolean", + "description": "Whether to create a PR.", + "default": false + }, + "base_ref": { + "type": "string", + "description": "Base ref for new branch/PR" + } + } + }, + "examples": { + "default": { + "value": { + "prompt": "Fix the login button on the homepage", + "base_ref": "main" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Task created successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "examples": { + "default": { + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "queued", + "session_count": 1, + "artifacts": [], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T00:00:00Z" + } + } + } + } + } + }, + "400": { + "description": "Problems parsing JSON", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/repos/{owner}/{repo}/tasks/{task_id}": { + "get": { + "summary": "Get a task by repo", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID scoped to an owner/repo path\n\n**Fine-grained access tokens for \"Get a task by repo\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-repo-and-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-repo" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks": { + "get": { + "summary": "List tasks", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for the authenticated user\n\n**Fine-grained access tokens for \"List tasks\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "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`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks/{task_id}": { + "get": { + "summary": "Get a task by ID", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID with its associated sessions\n\n**Fine-grained access tokens for \"Get a task by ID\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-id" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Problems parsing request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, "/app": { "get": { "summary": "Get the authenticated app", @@ -169523,7 +172681,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ], "type": "string" }, @@ -169604,6 +172763,14 @@ "description": "The Cloudsmith API host.", "type": "string" }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`).", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. If omitted, the federated token is used directly (direct WIF).", + "type": "string" + }, "created_at": { "type": "string", "format": "date-time" @@ -169748,7 +172915,7 @@ }, "post": { "summary": "Create a private registry for an organization", - "description": "\nCreates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", + "description": "\nCreates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", "tags": [ "private-registries" ], @@ -169837,7 +173004,7 @@ } }, "auth_type": { - "description": "The authentication type for the private registry. Defaults to `token` if not specified. Use `oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith` for OIDC authentication.", + "description": "The authentication type for the private registry. Defaults to `token` if not specified. Use `oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp` for OIDC authentication.", "type": "string", "enum": [ "token", @@ -169845,7 +173012,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ] }, "tenant_id": { @@ -169881,7 +173049,7 @@ "type": "string" }, "audience": { - "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and required for `oidc_cloudsmith` auth types.", + "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and `oidc_gcp`, and required for `oidc_cloudsmith` auth types.", "type": "string" }, "identity_mapping_name": { @@ -169899,6 +173067,14 @@ "api_host": { "description": "The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default.", "type": "string" + }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). Required when `auth_type` is `oidc_gcp`.", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. Optional for `oidc_gcp` auth type. If omitted, the federated token is used directly (direct WIF).", + "type": "string" } }, "required": [ @@ -169957,6 +173133,17 @@ "service_slug": "my-service-account", "audience": "https://github.com/my-org" } + }, + "org-private-registry-with-oidc-gcp": { + "summary": "Example of an OIDC private registry configuration using Google Cloud Artifact Registry", + "value": { + "registry_type": "docker_registry", + "url": "https://us-docker.pkg.dev/my-project/my-repo", + "auth_type": "oidc_gcp", + "visibility": "all", + "workload_identity_provider": "projects/123456789/locations/global/workloadIdentityPools/github-pool/providers/github-provider", + "service_account": "dependabot@my-project.iam.gserviceaccount.com" + } } } } @@ -170006,7 +173193,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ], "type": "string" }, @@ -170093,6 +173281,14 @@ "description": "The Cloudsmith API host.", "type": "string" }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`).", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. If omitted, the federated token is used directly (direct WIF).", + "type": "string" + }, "created_at": { "type": "string", "format": "date-time" @@ -170420,7 +173616,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ], "type": "string" }, @@ -170501,6 +173698,14 @@ "description": "The Cloudsmith API host.", "type": "string" }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`).", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. If omitted, the federated token is used directly (direct WIF).", + "type": "string" + }, "created_at": { "type": "string", "format": "date-time" @@ -170569,7 +173774,7 @@ }, "patch": { "summary": "Update a private registry for an organization", - "description": "\nUpdates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", + "description": "\nUpdates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", "tags": [ "private-registries" ], @@ -170675,7 +173880,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ] }, "tenant_id": { @@ -170711,7 +173917,7 @@ "type": "string" }, "audience": { - "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and required for `oidc_cloudsmith` auth types.", + "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and `oidc_gcp`, and required for `oidc_cloudsmith` auth types.", "type": "string" }, "identity_mapping_name": { @@ -170729,6 +173935,14 @@ "api_host": { "description": "The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default.", "type": "string" + }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). Required when `auth_type` is `oidc_gcp`.", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. Optional for `oidc_gcp` auth type. If omitted, the federated token is used directly (direct WIF).", + "type": "string" } } }, @@ -237628,6 +240842,506 @@ } } }, + "/repos/{owner}/{repo}/actions/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a repository", + "description": "Lists the active concurrency groups for a repository.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository" + }, + "parameters": [ + { + "name": "owner", + "description": "The account owner of the repository. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "repo", + "description": "The name of the repository without the `.git` extension. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "per_page", + "description": "The number of results per page (max 100). For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "schema": { + "type": "integer", + "default": 30 + } + }, + { + "name": "after", + "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/guides/using-pagination-in-the-rest-api#using-link-headers). If specified, the query only searches for results after this cursor. For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "title": "Concurrency Group List", + "description": "A list of active concurrency groups for a repository.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer" + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "last_acquired_at" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "last_acquired_at": { + "type": "string", + "format": "date-time", + "nullable": true + } + } + } + } + } + }, + "examples": { + "default": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "last_acquired_at": "2026-01-15T16:14:23Z" + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "last_acquired_at": "2026-01-15T16:13:55Z" + } + ] + } + } + } + } + }, + "headers": { + "Link": { + "example": "; rel=\"next\", ; rel=\"last\"", + "schema": { + "type": "string" + } + } + } + }, + "422": { + "description": "Validation failed, or the endpoint has been spammed.", + "content": { + "application/json": { + "schema": { + "title": "Validation Error", + "description": "Validation Error", + "type": "object", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "resource": { + "type": "string" + }, + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "code": { + "type": "string" + }, + "index": { + "type": "integer" + }, + "value": { + "oneOf": [ + { + "type": "string", + "nullable": true + }, + { + "type": "integer", + "nullable": true + }, + { + "type": "array", + "nullable": true, + "items": { + "type": "string" + } + } + ] + } + } + } + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": { + "get": { + "summary": "Get a concurrency group for a repository", + "description": "Gets a specific concurrency group for a repository, including all instances in the group's queue.\nReturns 404 if the group is inactive or does not exist.\n\nOptionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items\nahead of the specified workflow run or job in the queue, plus the specified item itself\n(returned as the last element). This is useful for determining what is blocking a particular\nrun or job. Returns 422 if the specified run or job is not in this concurrency group.\n\nWhen using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow\nleases held on behalf of that run. Job-level leases within the run are not considered to\nblock the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow\nleases on the job's ancestor paths.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/get-concurrency-group-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository" + }, + "parameters": [ + { + "name": "owner", + "description": "The account owner of the repository. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "repo", + "description": "The name of the repository without the `.git` extension. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "concurrency_group_name", + "description": "The name of the concurrency group.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "ahead_of_run", + "description": "Filter to items ahead of this workflow run ID in the queue, plus the run itself.\nMatches workflow-level concurrency and reusable-workflow leases held on behalf of\nthe run. Mutually exclusive with `ahead_of_job`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + }, + { + "name": "ahead_of_job", + "description": "Filter to items ahead of this job ID in the queue, plus the job itself.\nMatches job-level concurrency and reusable-workflow leases on the job's\nancestor paths. Mutually exclusive with `ahead_of_run`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "title": "Concurrency Group", + "description": "A concurrency group with the workflow runs and jobs that are either currently holding\nor waiting for the concurrency group lease.", + "type": "object", + "required": [ + "group_name", + "group_url", + "total_count", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "total_count": { + "type": "integer" + }, + "group_members": { + "type": "array", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": "string", + "format": "uri", + "description": "API URL for the workflow run.", + "nullable": true + }, + "run_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the workflow run.", + "nullable": true + }, + "job_id": { + "type": "integer", + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_name": { + "type": "string", + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_url": { + "type": "string", + "format": "uri", + "description": "API URL for the job.", + "nullable": true + }, + "job_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the job.", + "nullable": true + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + }, + "examples": { + "default": { + "value": { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "total_count": 3, + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress" + }, + { + "run_id": 30433643, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433643", + "status": "pending" + }, + { + "run_id": 30433644, + "run_name": "Deploy hotfix", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644", + "job_id": 798245260, + "job_name": "deploy", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260", + "status": "pending" + } + ] + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "422": { + "description": "Validation failed, or the endpoint has been spammed.", + "content": { + "application/json": { + "schema": { + "title": "Validation Error", + "description": "Validation Error", + "type": "object", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "resource": { + "type": "string" + }, + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "code": { + "type": "string" + }, + "index": { + "type": "integer" + }, + "value": { + "oneOf": [ + { + "type": "string", + "nullable": true + }, + { + "type": "integer", + "nullable": true + }, + { + "type": "array", + "nullable": true, + "items": { + "type": "string" + } + } + ] + } + } + } + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/jobs/{job_id}": { "get": { "summary": "Get a job for a workflow run", @@ -252728,6 +256442,350 @@ } } }, + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a workflow run", + "description": "Lists all concurrency groups associated with a workflow run or its jobs.\n\nThe set of groups is derived from the run's configuration, so a group is\nincluded even when the run no longer has any items currently holding or\nwaiting in it. In that case the `group_members` array will be empty.\n`total_count` reflects the number of groups the run participates in by\nconfiguration, not the number with active items.\n\nThis differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`,\nwhich returns 404 when a group has no active items. That endpoint reports\nthe live state of a group repo-wide, while this endpoint reports the\ngroups associated with a specific run by configuration.\n\nResults are sorted by group name and support cursor-based pagination via\n`before` and `after`. The `after` cursor paginates forward only and does\nnot emit a `rel=\"prev\"` Link; use `before` to page backward from a\nforward page's `next` cursor.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-workflow-run", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run" + }, + "parameters": [ + { + "name": "owner", + "description": "The account owner of the repository. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "repo", + "description": "The name of the repository without the `.git` extension. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "run_id", + "description": "The unique identifier of the workflow run.", + "in": "path", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "per_page", + "description": "The number of results per page (max 100). For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "schema": { + "type": "integer", + "default": 30 + } + }, + { + "name": "before", + "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/guides/using-pagination-in-the-rest-api#using-link-headers). If specified, the query only searches for results before this cursor. For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "after", + "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/guides/using-pagination-in-the-rest-api#using-link-headers). If specified, the query only searches for results after this cursor. For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "title": "Concurrency Group Run List", + "description": "A list of concurrency groups associated with a workflow run.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer", + "description": "The total number of concurrency groups this workflow run participates in,\nderived from the run's configuration. This count is not filtered by\nwhether the run currently holds or is waiting in each group, so it can\ninclude groups whose `group_members` array is empty (for example, when\nthe run has already released its lease in that group)." + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group. May return 404 if the group\nhas no active items at the time it is requested, since the\nget-by-name endpoint reports the live repo-wide state of a group\nwhile this endpoint lists groups associated with a run by\nconfiguration." + }, + "group_members": { + "type": "array", + "description": "Items belonging to this workflow run that are either currently holding or\nwaiting for the concurrency group lease. May be empty if the run no\nlonger has any active or queued items in this group.", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status", + "position", + "position_url" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": "string", + "format": "uri", + "description": "API URL for the workflow run.", + "nullable": true + }, + "run_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the workflow run.", + "nullable": true + }, + "position": { + "type": "integer", + "description": "Queue position. 0 means the item holds the concurrency lease (in_progress), 1 or higher means queued (pending)." + }, + "position_url": { + "type": "string", + "format": "uri", + "description": "API URL to get items ahead of this item in the concurrency group." + }, + "job_id": { + "type": "integer", + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease.", + "nullable": true + }, + "job_name": { + "type": "string", + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease.", + "nullable": true + }, + "job_url": { + "type": "string", + "format": "uri", + "description": "API URL for the job.", + "nullable": true + }, + "job_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the job.", + "nullable": true + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + } + } + } + }, + "examples": { + "default": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress", + "position": 0, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642" + } + ] + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "pending", + "position": 2, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260", + "job_id": 798245260, + "job_name": "build", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260" + } + ] + } + ] + } + } + } + } + }, + "headers": { + "Link": { + "example": "; rel=\"next\", ; rel=\"last\"", + "schema": { + "type": "string" + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "422": { + "description": "Validation failed, or the endpoint has been spammed.", + "content": { + "application/json": { + "schema": { + "title": "Validation Error", + "description": "Validation Error", + "type": "object", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "resource": { + "type": "string" + }, + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "code": { + "type": "string" + }, + "index": { + "type": "integer" + }, + "value": { + "oneOf": [ + { + "type": "string", + "nullable": true + }, + { + "type": "integer", + "nullable": true + }, + { + "type": "array", + "nullable": true, + "items": { + "type": "string" + } + } + ] + } + } + } + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": { "post": { "summary": "Review custom deployment protection rules for a workflow run", diff --git a/descriptions/api.github.com/dereferenced/api.github.com.2022-11-28.deref.yaml b/descriptions/api.github.com/dereferenced/api.github.com.2022-11-28.deref.yaml index ec9996952..4faeb0818 100644 --- a/descriptions/api.github.com/dereferenced/api.github.com.2022-11-28.deref.yaml +++ b/descriptions/api.github.com/dereferenced/api.github.com.2022-11-28.deref.yaml @@ -1118,6 +1118,2525 @@ paths: enabledForGitHubApps: true category: security-advisories subcategory: global-advisories + "/agents/repos/{owner}/{repo}/tasks": + get: + summary: List tasks for repository + description: | + > [!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](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks-for-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks-for-repository + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: '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`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + - name: creator_id + in: query + schema: + type: integer + description: Filter tasks by creator user ID + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="prev" (when current page > 1), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; + rel="next", ; + rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + post: + summary: Start a task + description: | + > [!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](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/create-task-in-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#start-a-task + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + requestBody: + required: true + description: The task creation parameters, including the user's prompt and + optional agent settings. + content: + application/json: + schema: + type: object + required: + - prompt + properties: + prompt: + type: string + description: The user's prompt for the agent + model: + type: string + 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`' + create_pull_request: + type: boolean + description: Whether to create a PR. + default: false + base_ref: + type: string + description: Base ref for new branch/PR + examples: + default: + value: + prompt: Fix the login button on the homepage + base_ref: main + responses: + '201': + description: Task created successfully + content: + application/json: + schema: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + examples: + default: + value: + id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: queued + session_count: 1 + artifacts: [] + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T00:00:00Z' + '400': + description: Problems parsing JSON + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/repos/{owner}/{repo}/tasks/{task_id}": + get: + summary: Get a task by repo + description: | + > [!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](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-repo-and-id + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-repo + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks": + get: + summary: List tasks + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a list of tasks for the authenticated user + + **Fine-grained access tokens for "List tasks"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: '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`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; rel="next", + ; rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks/{task_id}": + get: + summary: Get a task by ID + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a task by ID with its associated sessions + + **Fine-grained access tokens for "Get a task by ID"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-id + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-id + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Problems parsing request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation "/app": get: summary: Get the authenticated app @@ -40759,6 +43278,7 @@ paths: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp type: string url: description: The URL of the private registry. @@ -40827,6 +43347,15 @@ paths: api_host: description: The Cloudsmith API host. type: string + workload_identity_provider: + description: The full resource name of the GCP Workload + Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + type: string + service_account: + description: The GCP service account email to impersonate. + If omitted, the federated token is used directly (direct + WIF). + type: string created_at: type: string format: date-time @@ -40864,7 +43393,7 @@ paths: description: |2- Creates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see "[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api)." - For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted. + For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted. OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. tags: @@ -40957,7 +43486,7 @@ paths: auth_type: description: The authentication type for the private registry. Defaults to `token` if not specified. Use `oidc_azure`, `oidc_aws`, `oidc_jfrog`, - or `oidc_cloudsmith` for OIDC authentication. + `oidc_cloudsmith`, or `oidc_gcp` for OIDC authentication. type: string enum: - token @@ -40966,6 +43495,7 @@ paths: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp tenant_id: description: The tenant ID of the Azure AD application. Required when `auth_type` is `oidc_azure`. @@ -40998,7 +43528,7 @@ paths: type: string audience: description: The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, - and required for `oidc_cloudsmith` auth types. + and `oidc_gcp`, and required for `oidc_cloudsmith` auth types. type: string identity_mapping_name: description: The JFrog identity mapping name. Optional for `oidc_jfrog` @@ -41016,6 +43546,16 @@ paths: description: The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default. type: string + workload_identity_provider: + description: The full resource name of the GCP Workload Identity + Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + Required when `auth_type` is `oidc_gcp`. + type: string + service_account: + description: The GCP service account email to impersonate. Optional + for `oidc_gcp` auth type. If omitted, the federated token is used + directly (direct WIF). + type: string required: - registry_type - url @@ -41064,6 +43604,16 @@ paths: namespace: my-org service_slug: my-service-account audience: https://github.com/my-org + org-private-registry-with-oidc-gcp: + summary: Example of an OIDC private registry configuration using Google + Cloud Artifact Registry + value: + registry_type: docker_registry + url: https://us-docker.pkg.dev/my-project/my-repo + auth_type: oidc_gcp + visibility: all + workload_identity_provider: projects/123456789/locations/global/workloadIdentityPools/github-pool/providers/github-provider + service_account: dependabot@my-project.iam.gserviceaccount.com responses: '201': description: The organization private registry configuration @@ -41106,6 +43656,7 @@ paths: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp type: string url: description: The URL of the private registry. @@ -41180,6 +43731,14 @@ paths: api_host: description: The Cloudsmith API host. type: string + workload_identity_provider: + description: The full resource name of the GCP Workload Identity + Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + type: string + service_account: + description: The GCP service account email to impersonate. If + omitted, the federated token is used directly (direct WIF). + type: string created_at: type: string format: date-time @@ -41303,7 +43862,7 @@ paths: description: |2- Updates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see "[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api)." - For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted. + For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted. OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. tags: @@ -41401,6 +43960,7 @@ paths: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp tenant_id: description: The tenant ID of the Azure AD application. Required when `auth_type` is `oidc_azure`. @@ -41433,7 +43993,7 @@ paths: type: string audience: description: The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, - and required for `oidc_cloudsmith` auth types. + and `oidc_gcp`, and required for `oidc_cloudsmith` auth types. type: string identity_mapping_name: description: The JFrog identity mapping name. Optional for `oidc_jfrog` @@ -41451,6 +44011,16 @@ paths: description: The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default. type: string + workload_identity_provider: + description: The full resource name of the GCP Workload Identity + Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + Required when `auth_type` is `oidc_gcp`. + type: string + service_account: + description: The GCP service account email to impersonate. Optional + for `oidc_gcp` auth type. If omitted, the federated token is used + directly (direct WIF). + type: string examples: secret-based-update: summary: Update a secret-based private registry @@ -54200,6 +56770,240 @@ paths: enabledForGitHubApps: true category: actions subcategory: cache + "/repos/{owner}/{repo}/actions/concurrency_groups": + get: + summary: List concurrency groups for a repository + description: |- + Lists the active concurrency groups for a repository. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository + parameters: + - *348 + - *349 + - *17 + - *48 + responses: + '200': + description: Response + content: + application/json: + schema: + title: Concurrency Group List + description: A list of active concurrency groups for a repository. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - last_acquired_at + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + last_acquired_at: + type: string + format: date-time + nullable: true + examples: + default: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + last_acquired_at: '2026-01-15T16:14:23Z' + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + last_acquired_at: '2026-01-15T16:13:55Z' + headers: + Link: *70 + '422': *15 + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": + get: + summary: Get a concurrency group for a repository + description: |- + Gets a specific concurrency group for a repository, including all instances in the group's queue. + Returns 404 if the group is inactive or does not exist. + + Optionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items + ahead of the specified workflow run or job in the queue, plus the specified item itself + (returned as the last element). This is useful for determining what is blocking a particular + run or job. Returns 422 if the specified run or job is not in this concurrency group. + + When using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow + leases held on behalf of that run. Job-level leases within the run are not considered to + block the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow + leases on the job's ancestor paths. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/get-concurrency-group-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository + parameters: + - *348 + - *349 + - name: concurrency_group_name + description: The name of the concurrency group. + in: path + required: true + schema: + type: string + - name: ahead_of_run + description: |- + Filter to items ahead of this workflow run ID in the queue, plus the run itself. + Matches workflow-level concurrency and reusable-workflow leases held on behalf of + the run. Mutually exclusive with `ahead_of_job`. + in: query + required: false + schema: + type: integer + minimum: 1 + - name: ahead_of_job + description: |- + Filter to items ahead of this job ID in the queue, plus the job itself. + Matches job-level concurrency and reusable-workflow leases on the job's + ancestor paths. Mutually exclusive with `ahead_of_run`. + in: query + required: false + schema: + type: integer + minimum: 1 + responses: + '200': + description: Response + content: + application/json: + schema: + title: Concurrency Group + description: |- + A concurrency group with the workflow runs and jobs that are either currently holding + or waiting for the concurrency group lease. + type: object + required: + - group_name + - group_url + - total_count + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + total_count: + type: integer + group_members: + type: array + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: string + format: uri + description: API URL for the workflow run. + nullable: true + run_html_url: + type: string + format: uri + description: Web URL for the workflow run. + nullable: true + job_id: + type: integer + description: The ID of the job, when the item represents + a job-level or reusable-workflow-level lease. + job_name: + type: string + description: The display name of the job, when the item + represents a job-level or reusable-workflow-level lease. + job_url: + type: string + format: uri + description: API URL for the job. + nullable: true + job_html_url: + type: string + format: uri + description: Web URL for the job. + nullable: true + status: + type: string + enum: + - in_progress + - pending + examples: + default: + value: + group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + total_count: 3 + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + - run_id: 30433643 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433643 + status: pending + - run_id: 30433644 + run_name: Deploy hotfix + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644 + job_id: 798245260 + job_name: deploy + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260 + status: pending + '404': *6 + '422': *15 + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/jobs/{job_id}": get: summary: Get a job for a workflow run @@ -57151,6 +59955,192 @@ paths: enabledForGitHubApps: true category: actions subcategory: workflow-runs + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": + get: + summary: List concurrency groups for a workflow run + description: |- + Lists all concurrency groups associated with a workflow run or its jobs. + + The set of groups is derived from the run's configuration, so a group is + included even when the run no longer has any items currently holding or + waiting in it. In that case the `group_members` array will be empty. + `total_count` reflects the number of groups the run participates in by + configuration, not the number with active items. + + This differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`, + which returns 404 when a group has no active items. That endpoint reports + the live state of a group repo-wide, while this endpoint reports the + groups associated with a specific run by configuration. + + Results are sorted by group name and support cursor-based pagination via + `before` and `after`. The `after` cursor paginates forward only and does + not emit a `rel="prev"` Link; use `before` to page backward from a + forward page's `next` cursor. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-workflow-run + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run + parameters: + - *348 + - *349 + - *386 + - *17 + - *47 + - *48 + responses: + '200': + description: Response + content: + application/json: + schema: + title: Concurrency Group Run List + description: A list of concurrency groups associated with a workflow + run. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + description: |- + The total number of concurrency groups this workflow run participates in, + derived from the run's configuration. This count is not filtered by + whether the run currently holds or is waiting in each group, so it can + include groups whose `group_members` array is empty (for example, when + the run has already released its lease in that group). + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: |- + API URL for this concurrency group. May return 404 if the group + has no active items at the time it is requested, since the + get-by-name endpoint reports the live repo-wide state of a group + while this endpoint lists groups associated with a run by + configuration. + group_members: + type: array + description: |- + Items belonging to this workflow run that are either currently holding or + waiting for the concurrency group lease. May be empty if the run no + longer has any active or queued items in this group. + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + - position + - position_url + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: string + format: uri + description: API URL for the workflow run. + nullable: true + run_html_url: + type: string + format: uri + description: Web URL for the workflow run. + nullable: true + position: + type: integer + description: Queue position. 0 means the item holds + the concurrency lease (in_progress), 1 or higher + means queued (pending). + position_url: + type: string + format: uri + description: API URL to get items ahead of this item + in the concurrency group. + job_id: + type: integer + description: The ID of the job, when the item represents + a job-level or reusable-workflow-level lease. + nullable: true + job_name: + type: string + description: The display name of the job, when the + item represents a job-level or reusable-workflow-level + lease. + nullable: true + job_url: + type: string + format: uri + description: API URL for the job. + nullable: true + job_html_url: + type: string + format: uri + description: Web URL for the job. + nullable: true + status: + type: string + enum: + - in_progress + - pending + examples: + default: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + position: 0 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642 + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: pending + position: 2 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260 + job_id: 798245260 + job_name: build + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260 + headers: + Link: *70 + '404': *6 + '422': *15 + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": post: summary: Review custom deployment protection rules for a workflow run diff --git a/descriptions/api.github.com/dereferenced/api.github.com.2026-03-10.deref.json b/descriptions/api.github.com/dereferenced/api.github.com.2026-03-10.deref.json index 1442e11df..339de0f4b 100644 --- a/descriptions/api.github.com/dereferenced/api.github.com.2026-03-10.deref.json +++ b/descriptions/api.github.com/dereferenced/api.github.com.2026-03-10.deref.json @@ -1964,6 +1964,3164 @@ } } }, + "/agents/repos/{owner}/{repo}/tasks": { + "get": { + "summary": "List tasks for repository", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for a specific repository\n\n**Fine-grained access tokens for \"List tasks for repository\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks-for-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks-for-repository" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "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`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + }, + { + "name": "creator_id", + "in": "query", + "schema": { + "type": "integer" + }, + "description": "Filter tasks by creator user ID" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"prev\" (when current page > 1),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + }, + "post": { + "summary": "Start a task", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nStarts a new Copilot cloud agent task for a repository.\n\nThis endpoint is only available to users with a Copilot Business or Copilot Enterprise subscription.\n\n**Fine-grained access tokens for \"Start a task\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read and write)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/create-task-in-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#start-a-task" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + } + ], + "requestBody": { + "required": true, + "description": "The task creation parameters, including the user's prompt and optional agent settings.", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "prompt" + ], + "properties": { + "prompt": { + "type": "string", + "description": "The user's prompt for the agent" + }, + "model": { + "type": "string", + "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`" + }, + "create_pull_request": { + "type": "boolean", + "description": "Whether to create a PR.", + "default": false + }, + "base_ref": { + "type": "string", + "description": "Base ref for new branch/PR" + } + } + }, + "examples": { + "default": { + "value": { + "prompt": "Fix the login button on the homepage", + "base_ref": "main" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Task created successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "examples": { + "default": { + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "queued", + "session_count": 1, + "artifacts": [], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T00:00:00Z" + } + } + } + } + } + }, + "400": { + "description": "Problems parsing JSON", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/repos/{owner}/{repo}/tasks/{task_id}": { + "get": { + "summary": "Get a task by repo", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID scoped to an owner/repo path\n\n**Fine-grained access tokens for \"Get a task by repo\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-repo-and-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-repo" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks": { + "get": { + "summary": "List tasks", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for the authenticated user\n\n**Fine-grained access tokens for \"List tasks\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "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`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks/{task_id}": { + "get": { + "summary": "Get a task by ID", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID with its associated sessions\n\n**Fine-grained access tokens for \"Get a task by ID\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-id" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Problems parsing request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, "/app": { "get": { "summary": "Get the authenticated app", @@ -164303,7 +167461,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ], "type": "string" }, @@ -164384,6 +167543,14 @@ "description": "The Cloudsmith API host.", "type": "string" }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`).", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. If omitted, the federated token is used directly (direct WIF).", + "type": "string" + }, "created_at": { "type": "string", "format": "date-time" @@ -164528,7 +167695,7 @@ }, "post": { "summary": "Create a private registry for an organization", - "description": "\nCreates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", + "description": "\nCreates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", "tags": [ "private-registries" ], @@ -164617,7 +167784,7 @@ } }, "auth_type": { - "description": "The authentication type for the private registry. Defaults to `token` if not specified. Use `oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith` for OIDC authentication.", + "description": "The authentication type for the private registry. Defaults to `token` if not specified. Use `oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp` for OIDC authentication.", "type": "string", "enum": [ "token", @@ -164625,7 +167792,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ] }, "tenant_id": { @@ -164661,7 +167829,7 @@ "type": "string" }, "audience": { - "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and required for `oidc_cloudsmith` auth types.", + "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and `oidc_gcp`, and required for `oidc_cloudsmith` auth types.", "type": "string" }, "identity_mapping_name": { @@ -164679,6 +167847,14 @@ "api_host": { "description": "The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default.", "type": "string" + }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). Required when `auth_type` is `oidc_gcp`.", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. Optional for `oidc_gcp` auth type. If omitted, the federated token is used directly (direct WIF).", + "type": "string" } }, "required": [ @@ -164737,6 +167913,17 @@ "service_slug": "my-service-account", "audience": "https://github.com/my-org" } + }, + "org-private-registry-with-oidc-gcp": { + "summary": "Example of an OIDC private registry configuration using Google Cloud Artifact Registry", + "value": { + "registry_type": "docker_registry", + "url": "https://us-docker.pkg.dev/my-project/my-repo", + "auth_type": "oidc_gcp", + "visibility": "all", + "workload_identity_provider": "projects/123456789/locations/global/workloadIdentityPools/github-pool/providers/github-provider", + "service_account": "dependabot@my-project.iam.gserviceaccount.com" + } } } } @@ -164786,7 +167973,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ], "type": "string" }, @@ -164873,6 +168061,14 @@ "description": "The Cloudsmith API host.", "type": "string" }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`).", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. If omitted, the federated token is used directly (direct WIF).", + "type": "string" + }, "created_at": { "type": "string", "format": "date-time" @@ -165200,7 +168396,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ], "type": "string" }, @@ -165281,6 +168478,14 @@ "description": "The Cloudsmith API host.", "type": "string" }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`).", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. If omitted, the federated token is used directly (direct WIF).", + "type": "string" + }, "created_at": { "type": "string", "format": "date-time" @@ -165349,7 +168554,7 @@ }, "patch": { "summary": "Update a private registry for an organization", - "description": "\nUpdates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", + "description": "\nUpdates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", "tags": [ "private-registries" ], @@ -165455,7 +168660,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ] }, "tenant_id": { @@ -165491,7 +168697,7 @@ "type": "string" }, "audience": { - "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and required for `oidc_cloudsmith` auth types.", + "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and `oidc_gcp`, and required for `oidc_cloudsmith` auth types.", "type": "string" }, "identity_mapping_name": { @@ -165509,6 +168715,14 @@ "api_host": { "description": "The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default.", "type": "string" + }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). Required when `auth_type` is `oidc_gcp`.", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. Optional for `oidc_gcp` auth type. If omitted, the federated token is used directly (direct WIF).", + "type": "string" } } }, @@ -231598,6 +234812,506 @@ } } }, + "/repos/{owner}/{repo}/actions/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a repository", + "description": "Lists the active concurrency groups for a repository.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository" + }, + "parameters": [ + { + "name": "owner", + "description": "The account owner of the repository. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "repo", + "description": "The name of the repository without the `.git` extension. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "per_page", + "description": "The number of results per page (max 100). For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "schema": { + "type": "integer", + "default": 30 + } + }, + { + "name": "after", + "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/guides/using-pagination-in-the-rest-api#using-link-headers). If specified, the query only searches for results after this cursor. For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "title": "Concurrency Group List", + "description": "A list of active concurrency groups for a repository.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer" + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "last_acquired_at" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "last_acquired_at": { + "type": "string", + "format": "date-time", + "nullable": true + } + } + } + } + } + }, + "examples": { + "default": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "last_acquired_at": "2026-01-15T16:14:23Z" + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "last_acquired_at": "2026-01-15T16:13:55Z" + } + ] + } + } + } + } + }, + "headers": { + "Link": { + "example": "; rel=\"next\", ; rel=\"last\"", + "schema": { + "type": "string" + } + } + } + }, + "422": { + "description": "Validation failed, or the endpoint has been spammed.", + "content": { + "application/json": { + "schema": { + "title": "Validation Error", + "description": "Validation Error", + "type": "object", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "resource": { + "type": "string" + }, + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "code": { + "type": "string" + }, + "index": { + "type": "integer" + }, + "value": { + "oneOf": [ + { + "type": "string", + "nullable": true + }, + { + "type": "integer", + "nullable": true + }, + { + "type": "array", + "nullable": true, + "items": { + "type": "string" + } + } + ] + } + } + } + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": { + "get": { + "summary": "Get a concurrency group for a repository", + "description": "Gets a specific concurrency group for a repository, including all instances in the group's queue.\nReturns 404 if the group is inactive or does not exist.\n\nOptionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items\nahead of the specified workflow run or job in the queue, plus the specified item itself\n(returned as the last element). This is useful for determining what is blocking a particular\nrun or job. Returns 422 if the specified run or job is not in this concurrency group.\n\nWhen using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow\nleases held on behalf of that run. Job-level leases within the run are not considered to\nblock the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow\nleases on the job's ancestor paths.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/get-concurrency-group-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository" + }, + "parameters": [ + { + "name": "owner", + "description": "The account owner of the repository. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "repo", + "description": "The name of the repository without the `.git` extension. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "concurrency_group_name", + "description": "The name of the concurrency group.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "ahead_of_run", + "description": "Filter to items ahead of this workflow run ID in the queue, plus the run itself.\nMatches workflow-level concurrency and reusable-workflow leases held on behalf of\nthe run. Mutually exclusive with `ahead_of_job`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + }, + { + "name": "ahead_of_job", + "description": "Filter to items ahead of this job ID in the queue, plus the job itself.\nMatches job-level concurrency and reusable-workflow leases on the job's\nancestor paths. Mutually exclusive with `ahead_of_run`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "title": "Concurrency Group", + "description": "A concurrency group with the workflow runs and jobs that are either currently holding\nor waiting for the concurrency group lease.", + "type": "object", + "required": [ + "group_name", + "group_url", + "total_count", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "total_count": { + "type": "integer" + }, + "group_members": { + "type": "array", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": "string", + "format": "uri", + "description": "API URL for the workflow run.", + "nullable": true + }, + "run_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the workflow run.", + "nullable": true + }, + "job_id": { + "type": "integer", + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_name": { + "type": "string", + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_url": { + "type": "string", + "format": "uri", + "description": "API URL for the job.", + "nullable": true + }, + "job_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the job.", + "nullable": true + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + }, + "examples": { + "default": { + "value": { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "total_count": 3, + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress" + }, + { + "run_id": 30433643, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433643", + "status": "pending" + }, + { + "run_id": 30433644, + "run_name": "Deploy hotfix", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644", + "job_id": 798245260, + "job_name": "deploy", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260", + "status": "pending" + } + ] + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "422": { + "description": "Validation failed, or the endpoint has been spammed.", + "content": { + "application/json": { + "schema": { + "title": "Validation Error", + "description": "Validation Error", + "type": "object", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "resource": { + "type": "string" + }, + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "code": { + "type": "string" + }, + "index": { + "type": "integer" + }, + "value": { + "oneOf": [ + { + "type": "string", + "nullable": true + }, + { + "type": "integer", + "nullable": true + }, + { + "type": "array", + "nullable": true, + "items": { + "type": "string" + } + } + ] + } + } + } + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/jobs/{job_id}": { "get": { "summary": "Get a job for a workflow run", @@ -246646,6 +250360,350 @@ } } }, + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a workflow run", + "description": "Lists all concurrency groups associated with a workflow run or its jobs.\n\nThe set of groups is derived from the run's configuration, so a group is\nincluded even when the run no longer has any items currently holding or\nwaiting in it. In that case the `group_members` array will be empty.\n`total_count` reflects the number of groups the run participates in by\nconfiguration, not the number with active items.\n\nThis differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`,\nwhich returns 404 when a group has no active items. That endpoint reports\nthe live state of a group repo-wide, while this endpoint reports the\ngroups associated with a specific run by configuration.\n\nResults are sorted by group name and support cursor-based pagination via\n`before` and `after`. The `after` cursor paginates forward only and does\nnot emit a `rel=\"prev\"` Link; use `before` to page backward from a\nforward page's `next` cursor.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-workflow-run", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run" + }, + "parameters": [ + { + "name": "owner", + "description": "The account owner of the repository. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "repo", + "description": "The name of the repository without the `.git` extension. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "run_id", + "description": "The unique identifier of the workflow run.", + "in": "path", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "per_page", + "description": "The number of results per page (max 100). For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "schema": { + "type": "integer", + "default": 30 + } + }, + { + "name": "before", + "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/guides/using-pagination-in-the-rest-api#using-link-headers). If specified, the query only searches for results before this cursor. For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "after", + "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/guides/using-pagination-in-the-rest-api#using-link-headers). If specified, the query only searches for results after this cursor. For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "title": "Concurrency Group Run List", + "description": "A list of concurrency groups associated with a workflow run.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer", + "description": "The total number of concurrency groups this workflow run participates in,\nderived from the run's configuration. This count is not filtered by\nwhether the run currently holds or is waiting in each group, so it can\ninclude groups whose `group_members` array is empty (for example, when\nthe run has already released its lease in that group)." + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group. May return 404 if the group\nhas no active items at the time it is requested, since the\nget-by-name endpoint reports the live repo-wide state of a group\nwhile this endpoint lists groups associated with a run by\nconfiguration." + }, + "group_members": { + "type": "array", + "description": "Items belonging to this workflow run that are either currently holding or\nwaiting for the concurrency group lease. May be empty if the run no\nlonger has any active or queued items in this group.", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status", + "position", + "position_url" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": "string", + "format": "uri", + "description": "API URL for the workflow run.", + "nullable": true + }, + "run_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the workflow run.", + "nullable": true + }, + "position": { + "type": "integer", + "description": "Queue position. 0 means the item holds the concurrency lease (in_progress), 1 or higher means queued (pending)." + }, + "position_url": { + "type": "string", + "format": "uri", + "description": "API URL to get items ahead of this item in the concurrency group." + }, + "job_id": { + "type": "integer", + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease.", + "nullable": true + }, + "job_name": { + "type": "string", + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease.", + "nullable": true + }, + "job_url": { + "type": "string", + "format": "uri", + "description": "API URL for the job.", + "nullable": true + }, + "job_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the job.", + "nullable": true + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + } + } + } + }, + "examples": { + "default": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress", + "position": 0, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642" + } + ] + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "pending", + "position": 2, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260", + "job_id": 798245260, + "job_name": "build", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260" + } + ] + } + ] + } + } + } + } + }, + "headers": { + "Link": { + "example": "; rel=\"next\", ; rel=\"last\"", + "schema": { + "type": "string" + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "422": { + "description": "Validation failed, or the endpoint has been spammed.", + "content": { + "application/json": { + "schema": { + "title": "Validation Error", + "description": "Validation Error", + "type": "object", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "resource": { + "type": "string" + }, + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "code": { + "type": "string" + }, + "index": { + "type": "integer" + }, + "value": { + "oneOf": [ + { + "type": "string", + "nullable": true + }, + { + "type": "integer", + "nullable": true + }, + { + "type": "array", + "nullable": true, + "items": { + "type": "string" + } + } + ] + } + } + } + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": { "post": { "summary": "Review custom deployment protection rules for a workflow run", diff --git a/descriptions/api.github.com/dereferenced/api.github.com.2026-03-10.deref.yaml b/descriptions/api.github.com/dereferenced/api.github.com.2026-03-10.deref.yaml index ef0e28ddf..76cff2fa8 100644 --- a/descriptions/api.github.com/dereferenced/api.github.com.2026-03-10.deref.yaml +++ b/descriptions/api.github.com/dereferenced/api.github.com.2026-03-10.deref.yaml @@ -1086,6 +1086,2525 @@ paths: enabledForGitHubApps: true category: security-advisories subcategory: global-advisories + "/agents/repos/{owner}/{repo}/tasks": + get: + summary: List tasks for repository + description: | + > [!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](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks-for-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks-for-repository + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: '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`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + - name: creator_id + in: query + schema: + type: integer + description: Filter tasks by creator user ID + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="prev" (when current page > 1), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; + rel="next", ; + rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + post: + summary: Start a task + description: | + > [!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](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/create-task-in-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#start-a-task + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + requestBody: + required: true + description: The task creation parameters, including the user's prompt and + optional agent settings. + content: + application/json: + schema: + type: object + required: + - prompt + properties: + prompt: + type: string + description: The user's prompt for the agent + model: + type: string + 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`' + create_pull_request: + type: boolean + description: Whether to create a PR. + default: false + base_ref: + type: string + description: Base ref for new branch/PR + examples: + default: + value: + prompt: Fix the login button on the homepage + base_ref: main + responses: + '201': + description: Task created successfully + content: + application/json: + schema: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + examples: + default: + value: + id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: queued + session_count: 1 + artifacts: [] + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T00:00:00Z' + '400': + description: Problems parsing JSON + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/repos/{owner}/{repo}/tasks/{task_id}": + get: + summary: Get a task by repo + description: | + > [!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](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-repo-and-id + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-repo + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks": + get: + summary: List tasks + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a list of tasks for the authenticated user + + **Fine-grained access tokens for "List tasks"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: '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`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; rel="next", + ; rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks/{task_id}": + get: + summary: Get a task by ID + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a task by ID with its associated sessions + + **Fine-grained access tokens for "Get a task by ID"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-id + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-id + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Problems parsing request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation "/app": get: summary: Get the authenticated app @@ -40411,6 +42930,7 @@ paths: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp type: string url: description: The URL of the private registry. @@ -40479,6 +42999,15 @@ paths: api_host: description: The Cloudsmith API host. type: string + workload_identity_provider: + description: The full resource name of the GCP Workload + Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + type: string + service_account: + description: The GCP service account email to impersonate. + If omitted, the federated token is used directly (direct + WIF). + type: string created_at: type: string format: date-time @@ -40516,7 +43045,7 @@ paths: description: |2- Creates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see "[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api)." - For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted. + For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted. OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. tags: @@ -40609,7 +43138,7 @@ paths: auth_type: description: The authentication type for the private registry. Defaults to `token` if not specified. Use `oidc_azure`, `oidc_aws`, `oidc_jfrog`, - or `oidc_cloudsmith` for OIDC authentication. + `oidc_cloudsmith`, or `oidc_gcp` for OIDC authentication. type: string enum: - token @@ -40618,6 +43147,7 @@ paths: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp tenant_id: description: The tenant ID of the Azure AD application. Required when `auth_type` is `oidc_azure`. @@ -40650,7 +43180,7 @@ paths: type: string audience: description: The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, - and required for `oidc_cloudsmith` auth types. + and `oidc_gcp`, and required for `oidc_cloudsmith` auth types. type: string identity_mapping_name: description: The JFrog identity mapping name. Optional for `oidc_jfrog` @@ -40668,6 +43198,16 @@ paths: description: The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default. type: string + workload_identity_provider: + description: The full resource name of the GCP Workload Identity + Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + Required when `auth_type` is `oidc_gcp`. + type: string + service_account: + description: The GCP service account email to impersonate. Optional + for `oidc_gcp` auth type. If omitted, the federated token is used + directly (direct WIF). + type: string required: - registry_type - url @@ -40716,6 +43256,16 @@ paths: namespace: my-org service_slug: my-service-account audience: https://github.com/my-org + org-private-registry-with-oidc-gcp: + summary: Example of an OIDC private registry configuration using Google + Cloud Artifact Registry + value: + registry_type: docker_registry + url: https://us-docker.pkg.dev/my-project/my-repo + auth_type: oidc_gcp + visibility: all + workload_identity_provider: projects/123456789/locations/global/workloadIdentityPools/github-pool/providers/github-provider + service_account: dependabot@my-project.iam.gserviceaccount.com responses: '201': description: The organization private registry configuration @@ -40758,6 +43308,7 @@ paths: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp type: string url: description: The URL of the private registry. @@ -40832,6 +43383,14 @@ paths: api_host: description: The Cloudsmith API host. type: string + workload_identity_provider: + description: The full resource name of the GCP Workload Identity + Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + type: string + service_account: + description: The GCP service account email to impersonate. If + omitted, the federated token is used directly (direct WIF). + type: string created_at: type: string format: date-time @@ -40955,7 +43514,7 @@ paths: description: |2- Updates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see "[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api)." - For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted. + For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted. OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. tags: @@ -41053,6 +43612,7 @@ paths: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp tenant_id: description: The tenant ID of the Azure AD application. Required when `auth_type` is `oidc_azure`. @@ -41085,7 +43645,7 @@ paths: type: string audience: description: The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, - and required for `oidc_cloudsmith` auth types. + and `oidc_gcp`, and required for `oidc_cloudsmith` auth types. type: string identity_mapping_name: description: The JFrog identity mapping name. Optional for `oidc_jfrog` @@ -41103,6 +43663,16 @@ paths: description: The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default. type: string + workload_identity_provider: + description: The full resource name of the GCP Workload Identity + Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + Required when `auth_type` is `oidc_gcp`. + type: string + service_account: + description: The GCP service account email to impersonate. Optional + for `oidc_gcp` auth type. If omitted, the federated token is used + directly (direct WIF). + type: string examples: secret-based-update: summary: Update a secret-based private registry @@ -53791,6 +56361,240 @@ paths: enabledForGitHubApps: true category: actions subcategory: cache + "/repos/{owner}/{repo}/actions/concurrency_groups": + get: + summary: List concurrency groups for a repository + description: |- + Lists the active concurrency groups for a repository. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository + parameters: + - *348 + - *349 + - *17 + - *48 + responses: + '200': + description: Response + content: + application/json: + schema: + title: Concurrency Group List + description: A list of active concurrency groups for a repository. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - last_acquired_at + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + last_acquired_at: + type: string + format: date-time + nullable: true + examples: + default: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + last_acquired_at: '2026-01-15T16:14:23Z' + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + last_acquired_at: '2026-01-15T16:13:55Z' + headers: + Link: *70 + '422': *15 + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": + get: + summary: Get a concurrency group for a repository + description: |- + Gets a specific concurrency group for a repository, including all instances in the group's queue. + Returns 404 if the group is inactive or does not exist. + + Optionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items + ahead of the specified workflow run or job in the queue, plus the specified item itself + (returned as the last element). This is useful for determining what is blocking a particular + run or job. Returns 422 if the specified run or job is not in this concurrency group. + + When using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow + leases held on behalf of that run. Job-level leases within the run are not considered to + block the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow + leases on the job's ancestor paths. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/get-concurrency-group-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository + parameters: + - *348 + - *349 + - name: concurrency_group_name + description: The name of the concurrency group. + in: path + required: true + schema: + type: string + - name: ahead_of_run + description: |- + Filter to items ahead of this workflow run ID in the queue, plus the run itself. + Matches workflow-level concurrency and reusable-workflow leases held on behalf of + the run. Mutually exclusive with `ahead_of_job`. + in: query + required: false + schema: + type: integer + minimum: 1 + - name: ahead_of_job + description: |- + Filter to items ahead of this job ID in the queue, plus the job itself. + Matches job-level concurrency and reusable-workflow leases on the job's + ancestor paths. Mutually exclusive with `ahead_of_run`. + in: query + required: false + schema: + type: integer + minimum: 1 + responses: + '200': + description: Response + content: + application/json: + schema: + title: Concurrency Group + description: |- + A concurrency group with the workflow runs and jobs that are either currently holding + or waiting for the concurrency group lease. + type: object + required: + - group_name + - group_url + - total_count + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + total_count: + type: integer + group_members: + type: array + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: string + format: uri + description: API URL for the workflow run. + nullable: true + run_html_url: + type: string + format: uri + description: Web URL for the workflow run. + nullable: true + job_id: + type: integer + description: The ID of the job, when the item represents + a job-level or reusable-workflow-level lease. + job_name: + type: string + description: The display name of the job, when the item + represents a job-level or reusable-workflow-level lease. + job_url: + type: string + format: uri + description: API URL for the job. + nullable: true + job_html_url: + type: string + format: uri + description: Web URL for the job. + nullable: true + status: + type: string + enum: + - in_progress + - pending + examples: + default: + value: + group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + total_count: 3 + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + - run_id: 30433643 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433643 + status: pending + - run_id: 30433644 + run_name: Deploy hotfix + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644 + job_id: 798245260 + job_name: deploy + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260 + status: pending + '404': *6 + '422': *15 + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/jobs/{job_id}": get: summary: Get a job for a workflow run @@ -56742,6 +59546,192 @@ paths: enabledForGitHubApps: true category: actions subcategory: workflow-runs + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": + get: + summary: List concurrency groups for a workflow run + description: |- + Lists all concurrency groups associated with a workflow run or its jobs. + + The set of groups is derived from the run's configuration, so a group is + included even when the run no longer has any items currently holding or + waiting in it. In that case the `group_members` array will be empty. + `total_count` reflects the number of groups the run participates in by + configuration, not the number with active items. + + This differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`, + which returns 404 when a group has no active items. That endpoint reports + the live state of a group repo-wide, while this endpoint reports the + groups associated with a specific run by configuration. + + Results are sorted by group name and support cursor-based pagination via + `before` and `after`. The `after` cursor paginates forward only and does + not emit a `rel="prev"` Link; use `before` to page backward from a + forward page's `next` cursor. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-workflow-run + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run + parameters: + - *348 + - *349 + - *386 + - *17 + - *47 + - *48 + responses: + '200': + description: Response + content: + application/json: + schema: + title: Concurrency Group Run List + description: A list of concurrency groups associated with a workflow + run. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + description: |- + The total number of concurrency groups this workflow run participates in, + derived from the run's configuration. This count is not filtered by + whether the run currently holds or is waiting in each group, so it can + include groups whose `group_members` array is empty (for example, when + the run has already released its lease in that group). + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: |- + API URL for this concurrency group. May return 404 if the group + has no active items at the time it is requested, since the + get-by-name endpoint reports the live repo-wide state of a group + while this endpoint lists groups associated with a run by + configuration. + group_members: + type: array + description: |- + Items belonging to this workflow run that are either currently holding or + waiting for the concurrency group lease. May be empty if the run no + longer has any active or queued items in this group. + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + - position + - position_url + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: string + format: uri + description: API URL for the workflow run. + nullable: true + run_html_url: + type: string + format: uri + description: Web URL for the workflow run. + nullable: true + position: + type: integer + description: Queue position. 0 means the item holds + the concurrency lease (in_progress), 1 or higher + means queued (pending). + position_url: + type: string + format: uri + description: API URL to get items ahead of this item + in the concurrency group. + job_id: + type: integer + description: The ID of the job, when the item represents + a job-level or reusable-workflow-level lease. + nullable: true + job_name: + type: string + description: The display name of the job, when the + item represents a job-level or reusable-workflow-level + lease. + nullable: true + job_url: + type: string + format: uri + description: API URL for the job. + nullable: true + job_html_url: + type: string + format: uri + description: Web URL for the job. + nullable: true + status: + type: string + enum: + - in_progress + - pending + examples: + default: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + position: 0 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642 + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: pending + position: 2 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260 + job_id: 798245260 + job_name: build + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260 + headers: + Link: *70 + '404': *6 + '422': *15 + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": post: summary: Review custom deployment protection rules for a workflow run diff --git a/descriptions/api.github.com/dereferenced/api.github.com.deref.json b/descriptions/api.github.com/dereferenced/api.github.com.deref.json index 5119ba920..476dad5f4 100644 --- a/descriptions/api.github.com/dereferenced/api.github.com.deref.json +++ b/descriptions/api.github.com/dereferenced/api.github.com.deref.json @@ -2152,6 +2152,3164 @@ } } }, + "/agents/repos/{owner}/{repo}/tasks": { + "get": { + "summary": "List tasks for repository", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for a specific repository\n\n**Fine-grained access tokens for \"List tasks for repository\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks-for-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks-for-repository" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "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`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + }, + { + "name": "creator_id", + "in": "query", + "schema": { + "type": "integer" + }, + "description": "Filter tasks by creator user ID" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"prev\" (when current page > 1),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + }, + "post": { + "summary": "Start a task", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nStarts a new Copilot cloud agent task for a repository.\n\nThis endpoint is only available to users with a Copilot Business or Copilot Enterprise subscription.\n\n**Fine-grained access tokens for \"Start a task\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read and write)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/create-task-in-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#start-a-task" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + } + ], + "requestBody": { + "required": true, + "description": "The task creation parameters, including the user's prompt and optional agent settings.", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "prompt" + ], + "properties": { + "prompt": { + "type": "string", + "description": "The user's prompt for the agent" + }, + "model": { + "type": "string", + "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`" + }, + "create_pull_request": { + "type": "boolean", + "description": "Whether to create a PR.", + "default": false + }, + "base_ref": { + "type": "string", + "description": "Base ref for new branch/PR" + } + } + }, + "examples": { + "default": { + "value": { + "prompt": "Fix the login button on the homepage", + "base_ref": "main" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Task created successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "examples": { + "default": { + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "queued", + "session_count": 1, + "artifacts": [], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T00:00:00Z" + } + } + } + } + } + }, + "400": { + "description": "Problems parsing JSON", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/repos/{owner}/{repo}/tasks/{task_id}": { + "get": { + "summary": "Get a task by repo", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID scoped to an owner/repo path\n\n**Fine-grained access tokens for \"Get a task by repo\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-repo-and-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-repo" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks": { + "get": { + "summary": "List tasks", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for the authenticated user\n\n**Fine-grained access tokens for \"List tasks\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "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`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks/{task_id}": { + "get": { + "summary": "Get a task by ID", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID with its associated sessions\n\n**Fine-grained access tokens for \"Get a task by ID\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-id" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Problems parsing request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, "/app": { "get": { "summary": "Get the authenticated app", @@ -174520,7 +177678,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ], "type": "string" }, @@ -174601,6 +177760,14 @@ "description": "The Cloudsmith API host.", "type": "string" }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`).", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. If omitted, the federated token is used directly (direct WIF).", + "type": "string" + }, "created_at": { "type": "string", "format": "date-time" @@ -174745,7 +177912,7 @@ }, "post": { "summary": "Create a private registry for an organization", - "description": "\nCreates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", + "description": "\nCreates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", "tags": [ "private-registries" ], @@ -174834,7 +178001,7 @@ } }, "auth_type": { - "description": "The authentication type for the private registry. Defaults to `token` if not specified. Use `oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith` for OIDC authentication.", + "description": "The authentication type for the private registry. Defaults to `token` if not specified. Use `oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp` for OIDC authentication.", "type": "string", "enum": [ "token", @@ -174842,7 +178009,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ] }, "tenant_id": { @@ -174878,7 +178046,7 @@ "type": "string" }, "audience": { - "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and required for `oidc_cloudsmith` auth types.", + "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and `oidc_gcp`, and required for `oidc_cloudsmith` auth types.", "type": "string" }, "identity_mapping_name": { @@ -174896,6 +178064,14 @@ "api_host": { "description": "The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default.", "type": "string" + }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). Required when `auth_type` is `oidc_gcp`.", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. Optional for `oidc_gcp` auth type. If omitted, the federated token is used directly (direct WIF).", + "type": "string" } }, "required": [ @@ -174954,6 +178130,17 @@ "service_slug": "my-service-account", "audience": "https://github.com/my-org" } + }, + "org-private-registry-with-oidc-gcp": { + "summary": "Example of an OIDC private registry configuration using Google Cloud Artifact Registry", + "value": { + "registry_type": "docker_registry", + "url": "https://us-docker.pkg.dev/my-project/my-repo", + "auth_type": "oidc_gcp", + "visibility": "all", + "workload_identity_provider": "projects/123456789/locations/global/workloadIdentityPools/github-pool/providers/github-provider", + "service_account": "dependabot@my-project.iam.gserviceaccount.com" + } } } } @@ -175003,7 +178190,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ], "type": "string" }, @@ -175090,6 +178278,14 @@ "description": "The Cloudsmith API host.", "type": "string" }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`).", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. If omitted, the federated token is used directly (direct WIF).", + "type": "string" + }, "created_at": { "type": "string", "format": "date-time" @@ -175417,7 +178613,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ], "type": "string" }, @@ -175498,6 +178695,14 @@ "description": "The Cloudsmith API host.", "type": "string" }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`).", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. If omitted, the federated token is used directly (direct WIF).", + "type": "string" + }, "created_at": { "type": "string", "format": "date-time" @@ -175566,7 +178771,7 @@ }, "patch": { "summary": "Update a private registry for an organization", - "description": "\nUpdates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", + "description": "\nUpdates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", "tags": [ "private-registries" ], @@ -175672,7 +178877,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ] }, "tenant_id": { @@ -175708,7 +178914,7 @@ "type": "string" }, "audience": { - "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and required for `oidc_cloudsmith` auth types.", + "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and `oidc_gcp`, and required for `oidc_cloudsmith` auth types.", "type": "string" }, "identity_mapping_name": { @@ -175726,6 +178932,14 @@ "api_host": { "description": "The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default.", "type": "string" + }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). Required when `auth_type` is `oidc_gcp`.", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. Optional for `oidc_gcp` auth type. If omitted, the federated token is used directly (direct WIF).", + "type": "string" } } }, @@ -244845,6 +248059,506 @@ } } }, + "/repos/{owner}/{repo}/actions/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a repository", + "description": "Lists the active concurrency groups for a repository.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository" + }, + "parameters": [ + { + "name": "owner", + "description": "The account owner of the repository. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "repo", + "description": "The name of the repository without the `.git` extension. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "per_page", + "description": "The number of results per page (max 100). For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "schema": { + "type": "integer", + "default": 30 + } + }, + { + "name": "after", + "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/guides/using-pagination-in-the-rest-api#using-link-headers). If specified, the query only searches for results after this cursor. For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "title": "Concurrency Group List", + "description": "A list of active concurrency groups for a repository.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer" + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "last_acquired_at" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "last_acquired_at": { + "type": "string", + "format": "date-time", + "nullable": true + } + } + } + } + } + }, + "examples": { + "default": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "last_acquired_at": "2026-01-15T16:14:23Z" + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "last_acquired_at": "2026-01-15T16:13:55Z" + } + ] + } + } + } + } + }, + "headers": { + "Link": { + "example": "; rel=\"next\", ; rel=\"last\"", + "schema": { + "type": "string" + } + } + } + }, + "422": { + "description": "Validation failed, or the endpoint has been spammed.", + "content": { + "application/json": { + "schema": { + "title": "Validation Error", + "description": "Validation Error", + "type": "object", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "resource": { + "type": "string" + }, + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "code": { + "type": "string" + }, + "index": { + "type": "integer" + }, + "value": { + "oneOf": [ + { + "type": "string", + "nullable": true + }, + { + "type": "integer", + "nullable": true + }, + { + "type": "array", + "nullable": true, + "items": { + "type": "string" + } + } + ] + } + } + } + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": { + "get": { + "summary": "Get a concurrency group for a repository", + "description": "Gets a specific concurrency group for a repository, including all instances in the group's queue.\nReturns 404 if the group is inactive or does not exist.\n\nOptionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items\nahead of the specified workflow run or job in the queue, plus the specified item itself\n(returned as the last element). This is useful for determining what is blocking a particular\nrun or job. Returns 422 if the specified run or job is not in this concurrency group.\n\nWhen using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow\nleases held on behalf of that run. Job-level leases within the run are not considered to\nblock the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow\nleases on the job's ancestor paths.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/get-concurrency-group-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository" + }, + "parameters": [ + { + "name": "owner", + "description": "The account owner of the repository. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "repo", + "description": "The name of the repository without the `.git` extension. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "concurrency_group_name", + "description": "The name of the concurrency group.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "ahead_of_run", + "description": "Filter to items ahead of this workflow run ID in the queue, plus the run itself.\nMatches workflow-level concurrency and reusable-workflow leases held on behalf of\nthe run. Mutually exclusive with `ahead_of_job`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + }, + { + "name": "ahead_of_job", + "description": "Filter to items ahead of this job ID in the queue, plus the job itself.\nMatches job-level concurrency and reusable-workflow leases on the job's\nancestor paths. Mutually exclusive with `ahead_of_run`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "title": "Concurrency Group", + "description": "A concurrency group with the workflow runs and jobs that are either currently holding\nor waiting for the concurrency group lease.", + "type": "object", + "required": [ + "group_name", + "group_url", + "total_count", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "total_count": { + "type": "integer" + }, + "group_members": { + "type": "array", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": "string", + "format": "uri", + "description": "API URL for the workflow run.", + "nullable": true + }, + "run_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the workflow run.", + "nullable": true + }, + "job_id": { + "type": "integer", + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_name": { + "type": "string", + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_url": { + "type": "string", + "format": "uri", + "description": "API URL for the job.", + "nullable": true + }, + "job_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the job.", + "nullable": true + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + }, + "examples": { + "default": { + "value": { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "total_count": 3, + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress" + }, + { + "run_id": 30433643, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433643", + "status": "pending" + }, + { + "run_id": 30433644, + "run_name": "Deploy hotfix", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644", + "job_id": 798245260, + "job_name": "deploy", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260", + "status": "pending" + } + ] + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "422": { + "description": "Validation failed, or the endpoint has been spammed.", + "content": { + "application/json": { + "schema": { + "title": "Validation Error", + "description": "Validation Error", + "type": "object", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "resource": { + "type": "string" + }, + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "code": { + "type": "string" + }, + "index": { + "type": "integer" + }, + "value": { + "oneOf": [ + { + "type": "string", + "nullable": true + }, + { + "type": "integer", + "nullable": true + }, + { + "type": "array", + "nullable": true, + "items": { + "type": "string" + } + } + ] + } + } + } + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/jobs/{job_id}": { "get": { "summary": "Get a job for a workflow run", @@ -260217,6 +263931,350 @@ } } }, + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a workflow run", + "description": "Lists all concurrency groups associated with a workflow run or its jobs.\n\nThe set of groups is derived from the run's configuration, so a group is\nincluded even when the run no longer has any items currently holding or\nwaiting in it. In that case the `group_members` array will be empty.\n`total_count` reflects the number of groups the run participates in by\nconfiguration, not the number with active items.\n\nThis differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`,\nwhich returns 404 when a group has no active items. That endpoint reports\nthe live state of a group repo-wide, while this endpoint reports the\ngroups associated with a specific run by configuration.\n\nResults are sorted by group name and support cursor-based pagination via\n`before` and `after`. The `after` cursor paginates forward only and does\nnot emit a `rel=\"prev\"` Link; use `before` to page backward from a\nforward page's `next` cursor.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-workflow-run", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run" + }, + "parameters": [ + { + "name": "owner", + "description": "The account owner of the repository. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "repo", + "description": "The name of the repository without the `.git` extension. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "run_id", + "description": "The unique identifier of the workflow run.", + "in": "path", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "per_page", + "description": "The number of results per page (max 100). For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "schema": { + "type": "integer", + "default": 30 + } + }, + { + "name": "before", + "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/guides/using-pagination-in-the-rest-api#using-link-headers). If specified, the query only searches for results before this cursor. For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "after", + "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/guides/using-pagination-in-the-rest-api#using-link-headers). If specified, the query only searches for results after this cursor. For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "title": "Concurrency Group Run List", + "description": "A list of concurrency groups associated with a workflow run.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer", + "description": "The total number of concurrency groups this workflow run participates in,\nderived from the run's configuration. This count is not filtered by\nwhether the run currently holds or is waiting in each group, so it can\ninclude groups whose `group_members` array is empty (for example, when\nthe run has already released its lease in that group)." + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group. May return 404 if the group\nhas no active items at the time it is requested, since the\nget-by-name endpoint reports the live repo-wide state of a group\nwhile this endpoint lists groups associated with a run by\nconfiguration." + }, + "group_members": { + "type": "array", + "description": "Items belonging to this workflow run that are either currently holding or\nwaiting for the concurrency group lease. May be empty if the run no\nlonger has any active or queued items in this group.", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status", + "position", + "position_url" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": "string", + "format": "uri", + "description": "API URL for the workflow run.", + "nullable": true + }, + "run_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the workflow run.", + "nullable": true + }, + "position": { + "type": "integer", + "description": "Queue position. 0 means the item holds the concurrency lease (in_progress), 1 or higher means queued (pending)." + }, + "position_url": { + "type": "string", + "format": "uri", + "description": "API URL to get items ahead of this item in the concurrency group." + }, + "job_id": { + "type": "integer", + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease.", + "nullable": true + }, + "job_name": { + "type": "string", + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease.", + "nullable": true + }, + "job_url": { + "type": "string", + "format": "uri", + "description": "API URL for the job.", + "nullable": true + }, + "job_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the job.", + "nullable": true + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + } + } + } + }, + "examples": { + "default": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress", + "position": 0, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642" + } + ] + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "pending", + "position": 2, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260", + "job_id": 798245260, + "job_name": "build", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260" + } + ] + } + ] + } + } + } + } + }, + "headers": { + "Link": { + "example": "; rel=\"next\", ; rel=\"last\"", + "schema": { + "type": "string" + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "422": { + "description": "Validation failed, or the endpoint has been spammed.", + "content": { + "application/json": { + "schema": { + "title": "Validation Error", + "description": "Validation Error", + "type": "object", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "resource": { + "type": "string" + }, + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "code": { + "type": "string" + }, + "index": { + "type": "integer" + }, + "value": { + "oneOf": [ + { + "type": "string", + "nullable": true + }, + { + "type": "integer", + "nullable": true + }, + { + "type": "array", + "nullable": true, + "items": { + "type": "string" + } + } + ] + } + } + } + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": { "post": { "summary": "Review custom deployment protection rules for a workflow run", diff --git a/descriptions/api.github.com/dereferenced/api.github.com.deref.yaml b/descriptions/api.github.com/dereferenced/api.github.com.deref.yaml index c5b6a3f96..6a69fa697 100644 --- a/descriptions/api.github.com/dereferenced/api.github.com.deref.yaml +++ b/descriptions/api.github.com/dereferenced/api.github.com.deref.yaml @@ -1175,6 +1175,2525 @@ paths: enabledForGitHubApps: true category: security-advisories subcategory: global-advisories + "/agents/repos/{owner}/{repo}/tasks": + get: + summary: List tasks for repository + description: | + > [!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](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks-for-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks-for-repository + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: '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`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + - name: creator_id + in: query + schema: + type: integer + description: Filter tasks by creator user ID + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="prev" (when current page > 1), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; + rel="next", ; + rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + post: + summary: Start a task + description: | + > [!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](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/create-task-in-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#start-a-task + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + requestBody: + required: true + description: The task creation parameters, including the user's prompt and + optional agent settings. + content: + application/json: + schema: + type: object + required: + - prompt + properties: + prompt: + type: string + description: The user's prompt for the agent + model: + type: string + 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`' + create_pull_request: + type: boolean + description: Whether to create a PR. + default: false + base_ref: + type: string + description: Base ref for new branch/PR + examples: + default: + value: + prompt: Fix the login button on the homepage + base_ref: main + responses: + '201': + description: Task created successfully + content: + application/json: + schema: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + examples: + default: + value: + id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: queued + session_count: 1 + artifacts: [] + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T00:00:00Z' + '400': + description: Problems parsing JSON + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/repos/{owner}/{repo}/tasks/{task_id}": + get: + summary: Get a task by repo + description: | + > [!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](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-repo-and-id + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-repo + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks": + get: + summary: List tasks + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a list of tasks for the authenticated user + + **Fine-grained access tokens for "List tasks"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: '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`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; rel="next", + ; rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks/{task_id}": + get: + summary: Get a task by ID + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a task by ID with its associated sessions + + **Fine-grained access tokens for "Get a task by ID"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-id + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-id + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Problems parsing request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation "/app": get: summary: Get the authenticated app @@ -41131,6 +43650,7 @@ paths: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp type: string url: description: The URL of the private registry. @@ -41199,6 +43719,15 @@ paths: api_host: description: The Cloudsmith API host. type: string + workload_identity_provider: + description: The full resource name of the GCP Workload + Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + type: string + service_account: + description: The GCP service account email to impersonate. + If omitted, the federated token is used directly (direct + WIF). + type: string created_at: type: string format: date-time @@ -41236,7 +43765,7 @@ paths: description: |2- Creates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see "[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api)." - For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted. + For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted. OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. tags: @@ -41329,7 +43858,7 @@ paths: auth_type: description: The authentication type for the private registry. Defaults to `token` if not specified. Use `oidc_azure`, `oidc_aws`, `oidc_jfrog`, - or `oidc_cloudsmith` for OIDC authentication. + `oidc_cloudsmith`, or `oidc_gcp` for OIDC authentication. type: string enum: - token @@ -41338,6 +43867,7 @@ paths: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp tenant_id: description: The tenant ID of the Azure AD application. Required when `auth_type` is `oidc_azure`. @@ -41370,7 +43900,7 @@ paths: type: string audience: description: The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, - and required for `oidc_cloudsmith` auth types. + and `oidc_gcp`, and required for `oidc_cloudsmith` auth types. type: string identity_mapping_name: description: The JFrog identity mapping name. Optional for `oidc_jfrog` @@ -41388,6 +43918,16 @@ paths: description: The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default. type: string + workload_identity_provider: + description: The full resource name of the GCP Workload Identity + Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + Required when `auth_type` is `oidc_gcp`. + type: string + service_account: + description: The GCP service account email to impersonate. Optional + for `oidc_gcp` auth type. If omitted, the federated token is used + directly (direct WIF). + type: string required: - registry_type - url @@ -41436,6 +43976,16 @@ paths: namespace: my-org service_slug: my-service-account audience: https://github.com/my-org + org-private-registry-with-oidc-gcp: + summary: Example of an OIDC private registry configuration using Google + Cloud Artifact Registry + value: + registry_type: docker_registry + url: https://us-docker.pkg.dev/my-project/my-repo + auth_type: oidc_gcp + visibility: all + workload_identity_provider: projects/123456789/locations/global/workloadIdentityPools/github-pool/providers/github-provider + service_account: dependabot@my-project.iam.gserviceaccount.com responses: '201': description: The organization private registry configuration @@ -41478,6 +44028,7 @@ paths: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp type: string url: description: The URL of the private registry. @@ -41552,6 +44103,14 @@ paths: api_host: description: The Cloudsmith API host. type: string + workload_identity_provider: + description: The full resource name of the GCP Workload Identity + Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + type: string + service_account: + description: The GCP service account email to impersonate. If + omitted, the federated token is used directly (direct WIF). + type: string created_at: type: string format: date-time @@ -41675,7 +44234,7 @@ paths: description: |2- Updates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see "[Encrypting secrets for the REST API](https://docs.github.com/rest/guides/encrypting-secrets-for-the-rest-api)." - For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted. + For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted. OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. tags: @@ -41773,6 +44332,7 @@ paths: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp tenant_id: description: The tenant ID of the Azure AD application. Required when `auth_type` is `oidc_azure`. @@ -41805,7 +44365,7 @@ paths: type: string audience: description: The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, - and required for `oidc_cloudsmith` auth types. + and `oidc_gcp`, and required for `oidc_cloudsmith` auth types. type: string identity_mapping_name: description: The JFrog identity mapping name. Optional for `oidc_jfrog` @@ -41823,6 +44383,16 @@ paths: description: The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default. type: string + workload_identity_provider: + description: The full resource name of the GCP Workload Identity + Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + Required when `auth_type` is `oidc_gcp`. + type: string + service_account: + description: The GCP service account email to impersonate. Optional + for `oidc_gcp` auth type. If omitted, the federated token is used + directly (direct WIF). + type: string examples: secret-based-update: summary: Update a secret-based private registry @@ -54816,6 +57386,240 @@ paths: enabledForGitHubApps: true category: actions subcategory: cache + "/repos/{owner}/{repo}/actions/concurrency_groups": + get: + summary: List concurrency groups for a repository + description: |- + Lists the active concurrency groups for a repository. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository + parameters: + - *350 + - *351 + - *17 + - *48 + responses: + '200': + description: Response + content: + application/json: + schema: + title: Concurrency Group List + description: A list of active concurrency groups for a repository. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - last_acquired_at + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + last_acquired_at: + type: string + format: date-time + nullable: true + examples: + default: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + last_acquired_at: '2026-01-15T16:14:23Z' + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + last_acquired_at: '2026-01-15T16:13:55Z' + headers: + Link: *70 + '422': *15 + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": + get: + summary: Get a concurrency group for a repository + description: |- + Gets a specific concurrency group for a repository, including all instances in the group's queue. + Returns 404 if the group is inactive or does not exist. + + Optionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items + ahead of the specified workflow run or job in the queue, plus the specified item itself + (returned as the last element). This is useful for determining what is blocking a particular + run or job. Returns 422 if the specified run or job is not in this concurrency group. + + When using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow + leases held on behalf of that run. Job-level leases within the run are not considered to + block the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow + leases on the job's ancestor paths. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/get-concurrency-group-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository + parameters: + - *350 + - *351 + - name: concurrency_group_name + description: The name of the concurrency group. + in: path + required: true + schema: + type: string + - name: ahead_of_run + description: |- + Filter to items ahead of this workflow run ID in the queue, plus the run itself. + Matches workflow-level concurrency and reusable-workflow leases held on behalf of + the run. Mutually exclusive with `ahead_of_job`. + in: query + required: false + schema: + type: integer + minimum: 1 + - name: ahead_of_job + description: |- + Filter to items ahead of this job ID in the queue, plus the job itself. + Matches job-level concurrency and reusable-workflow leases on the job's + ancestor paths. Mutually exclusive with `ahead_of_run`. + in: query + required: false + schema: + type: integer + minimum: 1 + responses: + '200': + description: Response + content: + application/json: + schema: + title: Concurrency Group + description: |- + A concurrency group with the workflow runs and jobs that are either currently holding + or waiting for the concurrency group lease. + type: object + required: + - group_name + - group_url + - total_count + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + total_count: + type: integer + group_members: + type: array + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: string + format: uri + description: API URL for the workflow run. + nullable: true + run_html_url: + type: string + format: uri + description: Web URL for the workflow run. + nullable: true + job_id: + type: integer + description: The ID of the job, when the item represents + a job-level or reusable-workflow-level lease. + job_name: + type: string + description: The display name of the job, when the item + represents a job-level or reusable-workflow-level lease. + job_url: + type: string + format: uri + description: API URL for the job. + nullable: true + job_html_url: + type: string + format: uri + description: Web URL for the job. + nullable: true + status: + type: string + enum: + - in_progress + - pending + examples: + default: + value: + group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + total_count: 3 + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + - run_id: 30433643 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433643 + status: pending + - run_id: 30433644 + run_name: Deploy hotfix + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644 + job_id: 798245260 + job_name: deploy + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260 + status: pending + '404': *6 + '422': *15 + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/jobs/{job_id}": get: summary: Get a job for a workflow run @@ -57767,6 +60571,192 @@ paths: enabledForGitHubApps: true category: actions subcategory: workflow-runs + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": + get: + summary: List concurrency groups for a workflow run + description: |- + Lists all concurrency groups associated with a workflow run or its jobs. + + The set of groups is derived from the run's configuration, so a group is + included even when the run no longer has any items currently holding or + waiting in it. In that case the `group_members` array will be empty. + `total_count` reflects the number of groups the run participates in by + configuration, not the number with active items. + + This differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`, + which returns 404 when a group has no active items. That endpoint reports + the live state of a group repo-wide, while this endpoint reports the + groups associated with a specific run by configuration. + + Results are sorted by group name and support cursor-based pagination via + `before` and `after`. The `after` cursor paginates forward only and does + not emit a `rel="prev"` Link; use `before` to page backward from a + forward page's `next` cursor. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-workflow-run + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run + parameters: + - *350 + - *351 + - *388 + - *17 + - *47 + - *48 + responses: + '200': + description: Response + content: + application/json: + schema: + title: Concurrency Group Run List + description: A list of concurrency groups associated with a workflow + run. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + description: |- + The total number of concurrency groups this workflow run participates in, + derived from the run's configuration. This count is not filtered by + whether the run currently holds or is waiting in each group, so it can + include groups whose `group_members` array is empty (for example, when + the run has already released its lease in that group). + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: |- + API URL for this concurrency group. May return 404 if the group + has no active items at the time it is requested, since the + get-by-name endpoint reports the live repo-wide state of a group + while this endpoint lists groups associated with a run by + configuration. + group_members: + type: array + description: |- + Items belonging to this workflow run that are either currently holding or + waiting for the concurrency group lease. May be empty if the run no + longer has any active or queued items in this group. + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + - position + - position_url + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: string + format: uri + description: API URL for the workflow run. + nullable: true + run_html_url: + type: string + format: uri + description: Web URL for the workflow run. + nullable: true + position: + type: integer + description: Queue position. 0 means the item holds + the concurrency lease (in_progress), 1 or higher + means queued (pending). + position_url: + type: string + format: uri + description: API URL to get items ahead of this item + in the concurrency group. + job_id: + type: integer + description: The ID of the job, when the item represents + a job-level or reusable-workflow-level lease. + nullable: true + job_name: + type: string + description: The display name of the job, when the + item represents a job-level or reusable-workflow-level + lease. + nullable: true + job_url: + type: string + format: uri + description: API URL for the job. + nullable: true + job_html_url: + type: string + format: uri + description: Web URL for the job. + nullable: true + status: + type: string + enum: + - in_progress + - pending + examples: + default: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + position: 0 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642 + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: pending + position: 2 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260 + job_id: 798245260 + job_name: build + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260 + headers: + Link: *70 + '404': *6 + '422': *15 + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": post: summary: Review custom deployment protection rules for a workflow run diff --git a/descriptions/ghec/dereferenced/ghec.2022-11-28.deref.json b/descriptions/ghec/dereferenced/ghec.2022-11-28.deref.json index 6123a941d..e02e0f1a0 100644 --- a/descriptions/ghec/dereferenced/ghec.2022-11-28.deref.json +++ b/descriptions/ghec/dereferenced/ghec.2022-11-28.deref.json @@ -2044,6 +2044,3164 @@ } } }, + "/agents/repos/{owner}/{repo}/tasks": { + "get": { + "summary": "List tasks for repository", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for a specific repository\n\n**Fine-grained access tokens for \"List tasks for repository\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks-for-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#list-tasks-for-repository" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "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`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + }, + { + "name": "creator_id", + "in": "query", + "schema": { + "type": "integer" + }, + "description": "Filter tasks by creator user ID" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"prev\" (when current page > 1),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + }, + "post": { + "summary": "Start a task", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nStarts a new Copilot cloud agent task for a repository.\n\nThis endpoint is only available to users with a Copilot Business or Copilot Enterprise subscription.\n\n**Fine-grained access tokens for \"Start a task\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read and write)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/create-task-in-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#start-a-task" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + } + ], + "requestBody": { + "required": true, + "description": "The task creation parameters, including the user's prompt and optional agent settings.", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "prompt" + ], + "properties": { + "prompt": { + "type": "string", + "description": "The user's prompt for the agent" + }, + "model": { + "type": "string", + "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`" + }, + "create_pull_request": { + "type": "boolean", + "description": "Whether to create a PR.", + "default": false + }, + "base_ref": { + "type": "string", + "description": "Base ref for new branch/PR" + } + } + }, + "examples": { + "default": { + "value": { + "prompt": "Fix the login button on the homepage", + "base_ref": "main" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Task created successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "examples": { + "default": { + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "queued", + "session_count": 1, + "artifacts": [], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T00:00:00Z" + } + } + } + } + } + }, + "400": { + "description": "Problems parsing JSON", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/repos/{owner}/{repo}/tasks/{task_id}": { + "get": { + "summary": "Get a task by repo", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID scoped to an owner/repo path\n\n**Fine-grained access tokens for \"Get a task by repo\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-repo-and-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#get-a-task-by-repo" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks": { + "get": { + "summary": "List tasks", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for the authenticated user\n\n**Fine-grained access tokens for \"List tasks\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#list-tasks" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "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`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks/{task_id}": { + "get": { + "summary": "Get a task by ID", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID with its associated sessions\n\n**Fine-grained access tokens for \"Get a task by ID\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#get-a-task-by-id" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Problems parsing request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, "/app": { "get": { "summary": "Get the authenticated app", @@ -223761,7 +226919,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ], "type": "string" }, @@ -223842,6 +227001,14 @@ "description": "The Cloudsmith API host.", "type": "string" }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`).", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. If omitted, the federated token is used directly (direct WIF).", + "type": "string" + }, "created_at": { "type": "string", "format": "date-time" @@ -223986,7 +227153,7 @@ }, "post": { "summary": "Create a private registry for an organization", - "description": "\nCreates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", + "description": "\nCreates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", "tags": [ "private-registries" ], @@ -224075,7 +227242,7 @@ } }, "auth_type": { - "description": "The authentication type for the private registry. Defaults to `token` if not specified. Use `oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith` for OIDC authentication.", + "description": "The authentication type for the private registry. Defaults to `token` if not specified. Use `oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp` for OIDC authentication.", "type": "string", "enum": [ "token", @@ -224083,7 +227250,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ] }, "tenant_id": { @@ -224119,7 +227287,7 @@ "type": "string" }, "audience": { - "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and required for `oidc_cloudsmith` auth types.", + "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and `oidc_gcp`, and required for `oidc_cloudsmith` auth types.", "type": "string" }, "identity_mapping_name": { @@ -224137,6 +227305,14 @@ "api_host": { "description": "The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default.", "type": "string" + }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). Required when `auth_type` is `oidc_gcp`.", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. Optional for `oidc_gcp` auth type. If omitted, the federated token is used directly (direct WIF).", + "type": "string" } }, "required": [ @@ -224195,6 +227371,17 @@ "service_slug": "my-service-account", "audience": "https://github.com/my-org" } + }, + "org-private-registry-with-oidc-gcp": { + "summary": "Example of an OIDC private registry configuration using Google Cloud Artifact Registry", + "value": { + "registry_type": "docker_registry", + "url": "https://us-docker.pkg.dev/my-project/my-repo", + "auth_type": "oidc_gcp", + "visibility": "all", + "workload_identity_provider": "projects/123456789/locations/global/workloadIdentityPools/github-pool/providers/github-provider", + "service_account": "dependabot@my-project.iam.gserviceaccount.com" + } } } } @@ -224244,7 +227431,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ], "type": "string" }, @@ -224331,6 +227519,14 @@ "description": "The Cloudsmith API host.", "type": "string" }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`).", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. If omitted, the federated token is used directly (direct WIF).", + "type": "string" + }, "created_at": { "type": "string", "format": "date-time" @@ -224658,7 +227854,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ], "type": "string" }, @@ -224739,6 +227936,14 @@ "description": "The Cloudsmith API host.", "type": "string" }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`).", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. If omitted, the federated token is used directly (direct WIF).", + "type": "string" + }, "created_at": { "type": "string", "format": "date-time" @@ -224807,7 +228012,7 @@ }, "patch": { "summary": "Update a private registry for an organization", - "description": "\nUpdates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", + "description": "\nUpdates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", "tags": [ "private-registries" ], @@ -224913,7 +228118,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ] }, "tenant_id": { @@ -224949,7 +228155,7 @@ "type": "string" }, "audience": { - "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and required for `oidc_cloudsmith` auth types.", + "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and `oidc_gcp`, and required for `oidc_cloudsmith` auth types.", "type": "string" }, "identity_mapping_name": { @@ -224967,6 +228173,14 @@ "api_host": { "description": "The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default.", "type": "string" + }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). Required when `auth_type` is `oidc_gcp`.", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. Optional for `oidc_gcp` auth type. If omitted, the federated token is used directly (direct WIF).", + "type": "string" } } }, @@ -293067,6 +296281,506 @@ } } }, + "/repos/{owner}/{repo}/actions/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a repository", + "description": "Lists the active concurrency groups for a repository.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository" + }, + "parameters": [ + { + "name": "owner", + "description": "The account owner of the repository. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "repo", + "description": "The name of the repository without the `.git` extension. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "per_page", + "description": "The number of results per page (max 100). For more information, see \"[Using pagination in the REST API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "schema": { + "type": "integer", + "default": 30 + } + }, + { + "name": "after", + "description": "A cursor, as given in the [Link header](https://docs.github.com/enterprise-cloud@latest/rest/guides/using-pagination-in-the-rest-api#using-link-headers). If specified, the query only searches for results after this cursor. For more information, see \"[Using pagination in the REST API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "title": "Concurrency Group List", + "description": "A list of active concurrency groups for a repository.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer" + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "last_acquired_at" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "last_acquired_at": { + "type": "string", + "format": "date-time", + "nullable": true + } + } + } + } + } + }, + "examples": { + "default": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "last_acquired_at": "2026-01-15T16:14:23Z" + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "last_acquired_at": "2026-01-15T16:13:55Z" + } + ] + } + } + } + } + }, + "headers": { + "Link": { + "example": "; rel=\"next\", ; rel=\"last\"", + "schema": { + "type": "string" + } + } + } + }, + "422": { + "description": "Validation failed, or the endpoint has been spammed.", + "content": { + "application/json": { + "schema": { + "title": "Validation Error", + "description": "Validation Error", + "type": "object", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "resource": { + "type": "string" + }, + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "code": { + "type": "string" + }, + "index": { + "type": "integer" + }, + "value": { + "oneOf": [ + { + "type": "string", + "nullable": true + }, + { + "type": "integer", + "nullable": true + }, + { + "type": "array", + "nullable": true, + "items": { + "type": "string" + } + } + ] + } + } + } + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": { + "get": { + "summary": "Get a concurrency group for a repository", + "description": "Gets a specific concurrency group for a repository, including all instances in the group's queue.\nReturns 404 if the group is inactive or does not exist.\n\nOptionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items\nahead of the specified workflow run or job in the queue, plus the specified item itself\n(returned as the last element). This is useful for determining what is blocking a particular\nrun or job. Returns 422 if the specified run or job is not in this concurrency group.\n\nWhen using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow\nleases held on behalf of that run. Job-level leases within the run are not considered to\nblock the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow\nleases on the job's ancestor paths.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/get-concurrency-group-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository" + }, + "parameters": [ + { + "name": "owner", + "description": "The account owner of the repository. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "repo", + "description": "The name of the repository without the `.git` extension. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "concurrency_group_name", + "description": "The name of the concurrency group.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "ahead_of_run", + "description": "Filter to items ahead of this workflow run ID in the queue, plus the run itself.\nMatches workflow-level concurrency and reusable-workflow leases held on behalf of\nthe run. Mutually exclusive with `ahead_of_job`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + }, + { + "name": "ahead_of_job", + "description": "Filter to items ahead of this job ID in the queue, plus the job itself.\nMatches job-level concurrency and reusable-workflow leases on the job's\nancestor paths. Mutually exclusive with `ahead_of_run`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "title": "Concurrency Group", + "description": "A concurrency group with the workflow runs and jobs that are either currently holding\nor waiting for the concurrency group lease.", + "type": "object", + "required": [ + "group_name", + "group_url", + "total_count", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "total_count": { + "type": "integer" + }, + "group_members": { + "type": "array", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": "string", + "format": "uri", + "description": "API URL for the workflow run.", + "nullable": true + }, + "run_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the workflow run.", + "nullable": true + }, + "job_id": { + "type": "integer", + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_name": { + "type": "string", + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_url": { + "type": "string", + "format": "uri", + "description": "API URL for the job.", + "nullable": true + }, + "job_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the job.", + "nullable": true + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + }, + "examples": { + "default": { + "value": { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "total_count": 3, + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress" + }, + { + "run_id": 30433643, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433643", + "status": "pending" + }, + { + "run_id": 30433644, + "run_name": "Deploy hotfix", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644", + "job_id": 798245260, + "job_name": "deploy", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260", + "status": "pending" + } + ] + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "422": { + "description": "Validation failed, or the endpoint has been spammed.", + "content": { + "application/json": { + "schema": { + "title": "Validation Error", + "description": "Validation Error", + "type": "object", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "resource": { + "type": "string" + }, + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "code": { + "type": "string" + }, + "index": { + "type": "integer" + }, + "value": { + "oneOf": [ + { + "type": "string", + "nullable": true + }, + { + "type": "integer", + "nullable": true + }, + { + "type": "array", + "nullable": true, + "items": { + "type": "string" + } + } + ] + } + } + } + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/jobs/{job_id}": { "get": { "summary": "Get a job for a workflow run", @@ -308241,6 +311955,350 @@ } } }, + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a workflow run", + "description": "Lists all concurrency groups associated with a workflow run or its jobs.\n\nThe set of groups is derived from the run's configuration, so a group is\nincluded even when the run no longer has any items currently holding or\nwaiting in it. In that case the `group_members` array will be empty.\n`total_count` reflects the number of groups the run participates in by\nconfiguration, not the number with active items.\n\nThis differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`,\nwhich returns 404 when a group has no active items. That endpoint reports\nthe live state of a group repo-wide, while this endpoint reports the\ngroups associated with a specific run by configuration.\n\nResults are sorted by group name and support cursor-based pagination via\n`before` and `after`. The `after` cursor paginates forward only and does\nnot emit a `rel=\"prev\"` Link; use `before` to page backward from a\nforward page's `next` cursor.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-workflow-run", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run" + }, + "parameters": [ + { + "name": "owner", + "description": "The account owner of the repository. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "repo", + "description": "The name of the repository without the `.git` extension. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "run_id", + "description": "The unique identifier of the workflow run.", + "in": "path", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "per_page", + "description": "The number of results per page (max 100). For more information, see \"[Using pagination in the REST API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "schema": { + "type": "integer", + "default": 30 + } + }, + { + "name": "before", + "description": "A cursor, as given in the [Link header](https://docs.github.com/enterprise-cloud@latest/rest/guides/using-pagination-in-the-rest-api#using-link-headers). If specified, the query only searches for results before this cursor. For more information, see \"[Using pagination in the REST API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "after", + "description": "A cursor, as given in the [Link header](https://docs.github.com/enterprise-cloud@latest/rest/guides/using-pagination-in-the-rest-api#using-link-headers). If specified, the query only searches for results after this cursor. For more information, see \"[Using pagination in the REST API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "title": "Concurrency Group Run List", + "description": "A list of concurrency groups associated with a workflow run.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer", + "description": "The total number of concurrency groups this workflow run participates in,\nderived from the run's configuration. This count is not filtered by\nwhether the run currently holds or is waiting in each group, so it can\ninclude groups whose `group_members` array is empty (for example, when\nthe run has already released its lease in that group)." + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group. May return 404 if the group\nhas no active items at the time it is requested, since the\nget-by-name endpoint reports the live repo-wide state of a group\nwhile this endpoint lists groups associated with a run by\nconfiguration." + }, + "group_members": { + "type": "array", + "description": "Items belonging to this workflow run that are either currently holding or\nwaiting for the concurrency group lease. May be empty if the run no\nlonger has any active or queued items in this group.", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status", + "position", + "position_url" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": "string", + "format": "uri", + "description": "API URL for the workflow run.", + "nullable": true + }, + "run_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the workflow run.", + "nullable": true + }, + "position": { + "type": "integer", + "description": "Queue position. 0 means the item holds the concurrency lease (in_progress), 1 or higher means queued (pending)." + }, + "position_url": { + "type": "string", + "format": "uri", + "description": "API URL to get items ahead of this item in the concurrency group." + }, + "job_id": { + "type": "integer", + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease.", + "nullable": true + }, + "job_name": { + "type": "string", + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease.", + "nullable": true + }, + "job_url": { + "type": "string", + "format": "uri", + "description": "API URL for the job.", + "nullable": true + }, + "job_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the job.", + "nullable": true + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + } + } + } + }, + "examples": { + "default": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress", + "position": 0, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642" + } + ] + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "pending", + "position": 2, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260", + "job_id": 798245260, + "job_name": "build", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260" + } + ] + } + ] + } + } + } + } + }, + "headers": { + "Link": { + "example": "; rel=\"next\", ; rel=\"last\"", + "schema": { + "type": "string" + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "422": { + "description": "Validation failed, or the endpoint has been spammed.", + "content": { + "application/json": { + "schema": { + "title": "Validation Error", + "description": "Validation Error", + "type": "object", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "resource": { + "type": "string" + }, + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "code": { + "type": "string" + }, + "index": { + "type": "integer" + }, + "value": { + "oneOf": [ + { + "type": "string", + "nullable": true + }, + { + "type": "integer", + "nullable": true + }, + { + "type": "array", + "nullable": true, + "items": { + "type": "string" + } + } + ] + } + } + } + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": { "post": { "summary": "Review custom deployment protection rules for a workflow run", diff --git a/descriptions/ghec/dereferenced/ghec.2022-11-28.deref.yaml b/descriptions/ghec/dereferenced/ghec.2022-11-28.deref.yaml index d3dbf4d4a..55b97fcf7 100644 --- a/descriptions/ghec/dereferenced/ghec.2022-11-28.deref.yaml +++ b/descriptions/ghec/dereferenced/ghec.2022-11-28.deref.yaml @@ -1126,6 +1126,2525 @@ paths: enabledForGitHubApps: true category: security-advisories subcategory: global-advisories + "/agents/repos/{owner}/{repo}/tasks": + get: + summary: List tasks for repository + description: | + > [!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](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks-for-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#list-tasks-for-repository + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: '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`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + - name: creator_id + in: query + schema: + type: integer + description: Filter tasks by creator user ID + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="prev" (when current page > 1), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; + rel="next", ; + rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + post: + summary: Start a task + description: | + > [!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](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/create-task-in-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#start-a-task + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + requestBody: + required: true + description: The task creation parameters, including the user's prompt and + optional agent settings. + content: + application/json: + schema: + type: object + required: + - prompt + properties: + prompt: + type: string + description: The user's prompt for the agent + model: + type: string + 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`' + create_pull_request: + type: boolean + description: Whether to create a PR. + default: false + base_ref: + type: string + description: Base ref for new branch/PR + examples: + default: + value: + prompt: Fix the login button on the homepage + base_ref: main + responses: + '201': + description: Task created successfully + content: + application/json: + schema: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + examples: + default: + value: + id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: queued + session_count: 1 + artifacts: [] + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T00:00:00Z' + '400': + description: Problems parsing JSON + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/repos/{owner}/{repo}/tasks/{task_id}": + get: + summary: Get a task by repo + description: | + > [!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](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-repo-and-id + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#get-a-task-by-repo + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks": + get: + summary: List tasks + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a list of tasks for the authenticated user + + **Fine-grained access tokens for "List tasks"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#list-tasks + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: '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`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; rel="next", + ; rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks/{task_id}": + get: + summary: Get a task by ID + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a task by ID with its associated sessions + + **Fine-grained access tokens for "Get a task by ID"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-id + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#get-a-task-by-id + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Problems parsing request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation "/app": get: summary: Get the authenticated app @@ -55526,6 +58045,7 @@ paths: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp type: string url: description: The URL of the private registry. @@ -55594,6 +58114,15 @@ paths: api_host: description: The Cloudsmith API host. type: string + workload_identity_provider: + description: The full resource name of the GCP Workload + Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + type: string + service_account: + description: The GCP service account email to impersonate. + If omitted, the federated token is used directly (direct + WIF). + type: string created_at: type: string format: date-time @@ -55631,7 +58160,7 @@ paths: description: |2- Creates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see "[Encrypting secrets for the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/encrypting-secrets-for-the-rest-api)." - For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted. + For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted. OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. tags: @@ -55724,7 +58253,7 @@ paths: auth_type: description: The authentication type for the private registry. Defaults to `token` if not specified. Use `oidc_azure`, `oidc_aws`, `oidc_jfrog`, - or `oidc_cloudsmith` for OIDC authentication. + `oidc_cloudsmith`, or `oidc_gcp` for OIDC authentication. type: string enum: - token @@ -55733,6 +58262,7 @@ paths: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp tenant_id: description: The tenant ID of the Azure AD application. Required when `auth_type` is `oidc_azure`. @@ -55765,7 +58295,7 @@ paths: type: string audience: description: The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, - and required for `oidc_cloudsmith` auth types. + and `oidc_gcp`, and required for `oidc_cloudsmith` auth types. type: string identity_mapping_name: description: The JFrog identity mapping name. Optional for `oidc_jfrog` @@ -55783,6 +58313,16 @@ paths: description: The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default. type: string + workload_identity_provider: + description: The full resource name of the GCP Workload Identity + Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + Required when `auth_type` is `oidc_gcp`. + type: string + service_account: + description: The GCP service account email to impersonate. Optional + for `oidc_gcp` auth type. If omitted, the federated token is used + directly (direct WIF). + type: string required: - registry_type - url @@ -55831,6 +58371,16 @@ paths: namespace: my-org service_slug: my-service-account audience: https://github.com/my-org + org-private-registry-with-oidc-gcp: + summary: Example of an OIDC private registry configuration using Google + Cloud Artifact Registry + value: + registry_type: docker_registry + url: https://us-docker.pkg.dev/my-project/my-repo + auth_type: oidc_gcp + visibility: all + workload_identity_provider: projects/123456789/locations/global/workloadIdentityPools/github-pool/providers/github-provider + service_account: dependabot@my-project.iam.gserviceaccount.com responses: '201': description: The organization private registry configuration @@ -55873,6 +58423,7 @@ paths: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp type: string url: description: The URL of the private registry. @@ -55947,6 +58498,14 @@ paths: api_host: description: The Cloudsmith API host. type: string + workload_identity_provider: + description: The full resource name of the GCP Workload Identity + Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + type: string + service_account: + description: The GCP service account email to impersonate. If + omitted, the federated token is used directly (direct WIF). + type: string created_at: type: string format: date-time @@ -56070,7 +58629,7 @@ paths: description: |2- Updates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see "[Encrypting secrets for the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/encrypting-secrets-for-the-rest-api)." - For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted. + For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted. OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. tags: @@ -56168,6 +58727,7 @@ paths: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp tenant_id: description: The tenant ID of the Azure AD application. Required when `auth_type` is `oidc_azure`. @@ -56200,7 +58760,7 @@ paths: type: string audience: description: The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, - and required for `oidc_cloudsmith` auth types. + and `oidc_gcp`, and required for `oidc_cloudsmith` auth types. type: string identity_mapping_name: description: The JFrog identity mapping name. Optional for `oidc_jfrog` @@ -56218,6 +58778,16 @@ paths: description: The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default. type: string + workload_identity_provider: + description: The full resource name of the GCP Workload Identity + Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + Required when `auth_type` is `oidc_gcp`. + type: string + service_account: + description: The GCP service account email to impersonate. Optional + for `oidc_gcp` auth type. If omitted, the federated token is used + directly (direct WIF). + type: string examples: secret-based-update: summary: Update a secret-based private registry @@ -67082,6 +69652,240 @@ paths: enabledForGitHubApps: true category: actions subcategory: cache + "/repos/{owner}/{repo}/actions/concurrency_groups": + get: + summary: List concurrency groups for a repository + description: |- + Lists the active concurrency groups for a repository. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository + parameters: + - *484 + - *485 + - *17 + - *111 + responses: + '200': + description: Response + content: + application/json: + schema: + title: Concurrency Group List + description: A list of active concurrency groups for a repository. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - last_acquired_at + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + last_acquired_at: + type: string + format: date-time + nullable: true + examples: + default: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + last_acquired_at: '2026-01-15T16:14:23Z' + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + last_acquired_at: '2026-01-15T16:13:55Z' + headers: + Link: *47 + '422': *15 + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": + get: + summary: Get a concurrency group for a repository + description: |- + Gets a specific concurrency group for a repository, including all instances in the group's queue. + Returns 404 if the group is inactive or does not exist. + + Optionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items + ahead of the specified workflow run or job in the queue, plus the specified item itself + (returned as the last element). This is useful for determining what is blocking a particular + run or job. Returns 422 if the specified run or job is not in this concurrency group. + + When using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow + leases held on behalf of that run. Job-level leases within the run are not considered to + block the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow + leases on the job's ancestor paths. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/get-concurrency-group-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository + parameters: + - *484 + - *485 + - name: concurrency_group_name + description: The name of the concurrency group. + in: path + required: true + schema: + type: string + - name: ahead_of_run + description: |- + Filter to items ahead of this workflow run ID in the queue, plus the run itself. + Matches workflow-level concurrency and reusable-workflow leases held on behalf of + the run. Mutually exclusive with `ahead_of_job`. + in: query + required: false + schema: + type: integer + minimum: 1 + - name: ahead_of_job + description: |- + Filter to items ahead of this job ID in the queue, plus the job itself. + Matches job-level concurrency and reusable-workflow leases on the job's + ancestor paths. Mutually exclusive with `ahead_of_run`. + in: query + required: false + schema: + type: integer + minimum: 1 + responses: + '200': + description: Response + content: + application/json: + schema: + title: Concurrency Group + description: |- + A concurrency group with the workflow runs and jobs that are either currently holding + or waiting for the concurrency group lease. + type: object + required: + - group_name + - group_url + - total_count + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + total_count: + type: integer + group_members: + type: array + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: string + format: uri + description: API URL for the workflow run. + nullable: true + run_html_url: + type: string + format: uri + description: Web URL for the workflow run. + nullable: true + job_id: + type: integer + description: The ID of the job, when the item represents + a job-level or reusable-workflow-level lease. + job_name: + type: string + description: The display name of the job, when the item + represents a job-level or reusable-workflow-level lease. + job_url: + type: string + format: uri + description: API URL for the job. + nullable: true + job_html_url: + type: string + format: uri + description: Web URL for the job. + nullable: true + status: + type: string + enum: + - in_progress + - pending + examples: + default: + value: + group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + total_count: 3 + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + - run_id: 30433643 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433643 + status: pending + - run_id: 30433644 + run_name: Deploy hotfix + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644 + job_id: 798245260 + job_name: deploy + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260 + status: pending + '404': *6 + '422': *15 + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/jobs/{job_id}": get: summary: Get a job for a workflow run @@ -70042,6 +72846,192 @@ paths: enabledForGitHubApps: true category: actions subcategory: workflow-runs + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": + get: + summary: List concurrency groups for a workflow run + description: |- + Lists all concurrency groups associated with a workflow run or its jobs. + + The set of groups is derived from the run's configuration, so a group is + included even when the run no longer has any items currently holding or + waiting in it. In that case the `group_members` array will be empty. + `total_count` reflects the number of groups the run participates in by + configuration, not the number with active items. + + This differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`, + which returns 404 when a group has no active items. That endpoint reports + the live state of a group repo-wide, while this endpoint reports the + groups associated with a specific run by configuration. + + Results are sorted by group name and support cursor-based pagination via + `before` and `after`. The `after` cursor paginates forward only and does + not emit a `rel="prev"` Link; use `before` to page backward from a + forward page's `next` cursor. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-workflow-run + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run + parameters: + - *484 + - *485 + - *508 + - *17 + - *110 + - *111 + responses: + '200': + description: Response + content: + application/json: + schema: + title: Concurrency Group Run List + description: A list of concurrency groups associated with a workflow + run. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + description: |- + The total number of concurrency groups this workflow run participates in, + derived from the run's configuration. This count is not filtered by + whether the run currently holds or is waiting in each group, so it can + include groups whose `group_members` array is empty (for example, when + the run has already released its lease in that group). + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: |- + API URL for this concurrency group. May return 404 if the group + has no active items at the time it is requested, since the + get-by-name endpoint reports the live repo-wide state of a group + while this endpoint lists groups associated with a run by + configuration. + group_members: + type: array + description: |- + Items belonging to this workflow run that are either currently holding or + waiting for the concurrency group lease. May be empty if the run no + longer has any active or queued items in this group. + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + - position + - position_url + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: string + format: uri + description: API URL for the workflow run. + nullable: true + run_html_url: + type: string + format: uri + description: Web URL for the workflow run. + nullable: true + position: + type: integer + description: Queue position. 0 means the item holds + the concurrency lease (in_progress), 1 or higher + means queued (pending). + position_url: + type: string + format: uri + description: API URL to get items ahead of this item + in the concurrency group. + job_id: + type: integer + description: The ID of the job, when the item represents + a job-level or reusable-workflow-level lease. + nullable: true + job_name: + type: string + description: The display name of the job, when the + item represents a job-level or reusable-workflow-level + lease. + nullable: true + job_url: + type: string + format: uri + description: API URL for the job. + nullable: true + job_html_url: + type: string + format: uri + description: Web URL for the job. + nullable: true + status: + type: string + enum: + - in_progress + - pending + examples: + default: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + position: 0 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642 + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: pending + position: 2 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260 + job_id: 798245260 + job_name: build + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260 + headers: + Link: *47 + '404': *6 + '422': *15 + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": post: summary: Review custom deployment protection rules for a workflow run diff --git a/descriptions/ghec/dereferenced/ghec.2026-03-10.deref.json b/descriptions/ghec/dereferenced/ghec.2026-03-10.deref.json index 5c6ef7444..268045169 100644 --- a/descriptions/ghec/dereferenced/ghec.2026-03-10.deref.json +++ b/descriptions/ghec/dereferenced/ghec.2026-03-10.deref.json @@ -1980,6 +1980,3164 @@ } } }, + "/agents/repos/{owner}/{repo}/tasks": { + "get": { + "summary": "List tasks for repository", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for a specific repository\n\n**Fine-grained access tokens for \"List tasks for repository\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks-for-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#list-tasks-for-repository" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "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`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + }, + { + "name": "creator_id", + "in": "query", + "schema": { + "type": "integer" + }, + "description": "Filter tasks by creator user ID" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"prev\" (when current page > 1),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + }, + "post": { + "summary": "Start a task", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nStarts a new Copilot cloud agent task for a repository.\n\nThis endpoint is only available to users with a Copilot Business or Copilot Enterprise subscription.\n\n**Fine-grained access tokens for \"Start a task\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read and write)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/create-task-in-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#start-a-task" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + } + ], + "requestBody": { + "required": true, + "description": "The task creation parameters, including the user's prompt and optional agent settings.", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "prompt" + ], + "properties": { + "prompt": { + "type": "string", + "description": "The user's prompt for the agent" + }, + "model": { + "type": "string", + "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`" + }, + "create_pull_request": { + "type": "boolean", + "description": "Whether to create a PR.", + "default": false + }, + "base_ref": { + "type": "string", + "description": "Base ref for new branch/PR" + } + } + }, + "examples": { + "default": { + "value": { + "prompt": "Fix the login button on the homepage", + "base_ref": "main" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Task created successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "examples": { + "default": { + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "queued", + "session_count": 1, + "artifacts": [], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T00:00:00Z" + } + } + } + } + } + }, + "400": { + "description": "Problems parsing JSON", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/repos/{owner}/{repo}/tasks/{task_id}": { + "get": { + "summary": "Get a task by repo", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID scoped to an owner/repo path\n\n**Fine-grained access tokens for \"Get a task by repo\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-repo-and-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#get-a-task-by-repo" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks": { + "get": { + "summary": "List tasks", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for the authenticated user\n\n**Fine-grained access tokens for \"List tasks\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#list-tasks" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "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`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks/{task_id}": { + "get": { + "summary": "Get a task by ID", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID with its associated sessions\n\n**Fine-grained access tokens for \"Get a task by ID\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#get-a-task-by-id" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Problems parsing request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, "/app": { "get": { "summary": "Get the authenticated app", @@ -218294,7 +221452,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ], "type": "string" }, @@ -218375,6 +221534,14 @@ "description": "The Cloudsmith API host.", "type": "string" }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`).", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. If omitted, the federated token is used directly (direct WIF).", + "type": "string" + }, "created_at": { "type": "string", "format": "date-time" @@ -218519,7 +221686,7 @@ }, "post": { "summary": "Create a private registry for an organization", - "description": "\nCreates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", + "description": "\nCreates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", "tags": [ "private-registries" ], @@ -218608,7 +221775,7 @@ } }, "auth_type": { - "description": "The authentication type for the private registry. Defaults to `token` if not specified. Use `oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith` for OIDC authentication.", + "description": "The authentication type for the private registry. Defaults to `token` if not specified. Use `oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp` for OIDC authentication.", "type": "string", "enum": [ "token", @@ -218616,7 +221783,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ] }, "tenant_id": { @@ -218652,7 +221820,7 @@ "type": "string" }, "audience": { - "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and required for `oidc_cloudsmith` auth types.", + "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and `oidc_gcp`, and required for `oidc_cloudsmith` auth types.", "type": "string" }, "identity_mapping_name": { @@ -218670,6 +221838,14 @@ "api_host": { "description": "The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default.", "type": "string" + }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). Required when `auth_type` is `oidc_gcp`.", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. Optional for `oidc_gcp` auth type. If omitted, the federated token is used directly (direct WIF).", + "type": "string" } }, "required": [ @@ -218728,6 +221904,17 @@ "service_slug": "my-service-account", "audience": "https://github.com/my-org" } + }, + "org-private-registry-with-oidc-gcp": { + "summary": "Example of an OIDC private registry configuration using Google Cloud Artifact Registry", + "value": { + "registry_type": "docker_registry", + "url": "https://us-docker.pkg.dev/my-project/my-repo", + "auth_type": "oidc_gcp", + "visibility": "all", + "workload_identity_provider": "projects/123456789/locations/global/workloadIdentityPools/github-pool/providers/github-provider", + "service_account": "dependabot@my-project.iam.gserviceaccount.com" + } } } } @@ -218777,7 +221964,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ], "type": "string" }, @@ -218864,6 +222052,14 @@ "description": "The Cloudsmith API host.", "type": "string" }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`).", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. If omitted, the federated token is used directly (direct WIF).", + "type": "string" + }, "created_at": { "type": "string", "format": "date-time" @@ -219191,7 +222387,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ], "type": "string" }, @@ -219272,6 +222469,14 @@ "description": "The Cloudsmith API host.", "type": "string" }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`).", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. If omitted, the federated token is used directly (direct WIF).", + "type": "string" + }, "created_at": { "type": "string", "format": "date-time" @@ -219340,7 +222545,7 @@ }, "patch": { "summary": "Update a private registry for an organization", - "description": "\nUpdates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", + "description": "\nUpdates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", "tags": [ "private-registries" ], @@ -219446,7 +222651,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ] }, "tenant_id": { @@ -219482,7 +222688,7 @@ "type": "string" }, "audience": { - "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and required for `oidc_cloudsmith` auth types.", + "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and `oidc_gcp`, and required for `oidc_cloudsmith` auth types.", "type": "string" }, "identity_mapping_name": { @@ -219500,6 +222706,14 @@ "api_host": { "description": "The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default.", "type": "string" + }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). Required when `auth_type` is `oidc_gcp`.", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. Optional for `oidc_gcp` auth type. If omitted, the federated token is used directly (direct WIF).", + "type": "string" } } }, @@ -286790,6 +290004,506 @@ } } }, + "/repos/{owner}/{repo}/actions/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a repository", + "description": "Lists the active concurrency groups for a repository.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository" + }, + "parameters": [ + { + "name": "owner", + "description": "The account owner of the repository. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "repo", + "description": "The name of the repository without the `.git` extension. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "per_page", + "description": "The number of results per page (max 100). For more information, see \"[Using pagination in the REST API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "schema": { + "type": "integer", + "default": 30 + } + }, + { + "name": "after", + "description": "A cursor, as given in the [Link header](https://docs.github.com/enterprise-cloud@latest/rest/guides/using-pagination-in-the-rest-api#using-link-headers). If specified, the query only searches for results after this cursor. For more information, see \"[Using pagination in the REST API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "title": "Concurrency Group List", + "description": "A list of active concurrency groups for a repository.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer" + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "last_acquired_at" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "last_acquired_at": { + "type": "string", + "format": "date-time", + "nullable": true + } + } + } + } + } + }, + "examples": { + "default": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "last_acquired_at": "2026-01-15T16:14:23Z" + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "last_acquired_at": "2026-01-15T16:13:55Z" + } + ] + } + } + } + } + }, + "headers": { + "Link": { + "example": "; rel=\"next\", ; rel=\"last\"", + "schema": { + "type": "string" + } + } + } + }, + "422": { + "description": "Validation failed, or the endpoint has been spammed.", + "content": { + "application/json": { + "schema": { + "title": "Validation Error", + "description": "Validation Error", + "type": "object", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "resource": { + "type": "string" + }, + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "code": { + "type": "string" + }, + "index": { + "type": "integer" + }, + "value": { + "oneOf": [ + { + "type": "string", + "nullable": true + }, + { + "type": "integer", + "nullable": true + }, + { + "type": "array", + "nullable": true, + "items": { + "type": "string" + } + } + ] + } + } + } + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": { + "get": { + "summary": "Get a concurrency group for a repository", + "description": "Gets a specific concurrency group for a repository, including all instances in the group's queue.\nReturns 404 if the group is inactive or does not exist.\n\nOptionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items\nahead of the specified workflow run or job in the queue, plus the specified item itself\n(returned as the last element). This is useful for determining what is blocking a particular\nrun or job. Returns 422 if the specified run or job is not in this concurrency group.\n\nWhen using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow\nleases held on behalf of that run. Job-level leases within the run are not considered to\nblock the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow\nleases on the job's ancestor paths.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/get-concurrency-group-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository" + }, + "parameters": [ + { + "name": "owner", + "description": "The account owner of the repository. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "repo", + "description": "The name of the repository without the `.git` extension. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "concurrency_group_name", + "description": "The name of the concurrency group.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "ahead_of_run", + "description": "Filter to items ahead of this workflow run ID in the queue, plus the run itself.\nMatches workflow-level concurrency and reusable-workflow leases held on behalf of\nthe run. Mutually exclusive with `ahead_of_job`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + }, + { + "name": "ahead_of_job", + "description": "Filter to items ahead of this job ID in the queue, plus the job itself.\nMatches job-level concurrency and reusable-workflow leases on the job's\nancestor paths. Mutually exclusive with `ahead_of_run`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "title": "Concurrency Group", + "description": "A concurrency group with the workflow runs and jobs that are either currently holding\nor waiting for the concurrency group lease.", + "type": "object", + "required": [ + "group_name", + "group_url", + "total_count", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "total_count": { + "type": "integer" + }, + "group_members": { + "type": "array", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": "string", + "format": "uri", + "description": "API URL for the workflow run.", + "nullable": true + }, + "run_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the workflow run.", + "nullable": true + }, + "job_id": { + "type": "integer", + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_name": { + "type": "string", + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_url": { + "type": "string", + "format": "uri", + "description": "API URL for the job.", + "nullable": true + }, + "job_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the job.", + "nullable": true + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + }, + "examples": { + "default": { + "value": { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "total_count": 3, + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress" + }, + { + "run_id": 30433643, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433643", + "status": "pending" + }, + { + "run_id": 30433644, + "run_name": "Deploy hotfix", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644", + "job_id": 798245260, + "job_name": "deploy", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260", + "status": "pending" + } + ] + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "422": { + "description": "Validation failed, or the endpoint has been spammed.", + "content": { + "application/json": { + "schema": { + "title": "Validation Error", + "description": "Validation Error", + "type": "object", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "resource": { + "type": "string" + }, + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "code": { + "type": "string" + }, + "index": { + "type": "integer" + }, + "value": { + "oneOf": [ + { + "type": "string", + "nullable": true + }, + { + "type": "integer", + "nullable": true + }, + { + "type": "array", + "nullable": true, + "items": { + "type": "string" + } + } + ] + } + } + } + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/jobs/{job_id}": { "get": { "summary": "Get a job for a workflow run", @@ -301912,6 +305626,350 @@ } } }, + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a workflow run", + "description": "Lists all concurrency groups associated with a workflow run or its jobs.\n\nThe set of groups is derived from the run's configuration, so a group is\nincluded even when the run no longer has any items currently holding or\nwaiting in it. In that case the `group_members` array will be empty.\n`total_count` reflects the number of groups the run participates in by\nconfiguration, not the number with active items.\n\nThis differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`,\nwhich returns 404 when a group has no active items. That endpoint reports\nthe live state of a group repo-wide, while this endpoint reports the\ngroups associated with a specific run by configuration.\n\nResults are sorted by group name and support cursor-based pagination via\n`before` and `after`. The `after` cursor paginates forward only and does\nnot emit a `rel=\"prev\"` Link; use `before` to page backward from a\nforward page's `next` cursor.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-workflow-run", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run" + }, + "parameters": [ + { + "name": "owner", + "description": "The account owner of the repository. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "repo", + "description": "The name of the repository without the `.git` extension. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "run_id", + "description": "The unique identifier of the workflow run.", + "in": "path", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "per_page", + "description": "The number of results per page (max 100). For more information, see \"[Using pagination in the REST API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "schema": { + "type": "integer", + "default": 30 + } + }, + { + "name": "before", + "description": "A cursor, as given in the [Link header](https://docs.github.com/enterprise-cloud@latest/rest/guides/using-pagination-in-the-rest-api#using-link-headers). If specified, the query only searches for results before this cursor. For more information, see \"[Using pagination in the REST API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "after", + "description": "A cursor, as given in the [Link header](https://docs.github.com/enterprise-cloud@latest/rest/guides/using-pagination-in-the-rest-api#using-link-headers). If specified, the query only searches for results after this cursor. For more information, see \"[Using pagination in the REST API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "title": "Concurrency Group Run List", + "description": "A list of concurrency groups associated with a workflow run.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer", + "description": "The total number of concurrency groups this workflow run participates in,\nderived from the run's configuration. This count is not filtered by\nwhether the run currently holds or is waiting in each group, so it can\ninclude groups whose `group_members` array is empty (for example, when\nthe run has already released its lease in that group)." + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group. May return 404 if the group\nhas no active items at the time it is requested, since the\nget-by-name endpoint reports the live repo-wide state of a group\nwhile this endpoint lists groups associated with a run by\nconfiguration." + }, + "group_members": { + "type": "array", + "description": "Items belonging to this workflow run that are either currently holding or\nwaiting for the concurrency group lease. May be empty if the run no\nlonger has any active or queued items in this group.", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status", + "position", + "position_url" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": "string", + "format": "uri", + "description": "API URL for the workflow run.", + "nullable": true + }, + "run_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the workflow run.", + "nullable": true + }, + "position": { + "type": "integer", + "description": "Queue position. 0 means the item holds the concurrency lease (in_progress), 1 or higher means queued (pending)." + }, + "position_url": { + "type": "string", + "format": "uri", + "description": "API URL to get items ahead of this item in the concurrency group." + }, + "job_id": { + "type": "integer", + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease.", + "nullable": true + }, + "job_name": { + "type": "string", + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease.", + "nullable": true + }, + "job_url": { + "type": "string", + "format": "uri", + "description": "API URL for the job.", + "nullable": true + }, + "job_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the job.", + "nullable": true + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + } + } + } + }, + "examples": { + "default": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress", + "position": 0, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642" + } + ] + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "pending", + "position": 2, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260", + "job_id": 798245260, + "job_name": "build", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260" + } + ] + } + ] + } + } + } + } + }, + "headers": { + "Link": { + "example": "; rel=\"next\", ; rel=\"last\"", + "schema": { + "type": "string" + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "422": { + "description": "Validation failed, or the endpoint has been spammed.", + "content": { + "application/json": { + "schema": { + "title": "Validation Error", + "description": "Validation Error", + "type": "object", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "resource": { + "type": "string" + }, + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "code": { + "type": "string" + }, + "index": { + "type": "integer" + }, + "value": { + "oneOf": [ + { + "type": "string", + "nullable": true + }, + { + "type": "integer", + "nullable": true + }, + { + "type": "array", + "nullable": true, + "items": { + "type": "string" + } + } + ] + } + } + } + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": { "post": { "summary": "Review custom deployment protection rules for a workflow run", diff --git a/descriptions/ghec/dereferenced/ghec.2026-03-10.deref.yaml b/descriptions/ghec/dereferenced/ghec.2026-03-10.deref.yaml index 31d527135..674d77d97 100644 --- a/descriptions/ghec/dereferenced/ghec.2026-03-10.deref.yaml +++ b/descriptions/ghec/dereferenced/ghec.2026-03-10.deref.yaml @@ -1094,6 +1094,2525 @@ paths: enabledForGitHubApps: true category: security-advisories subcategory: global-advisories + "/agents/repos/{owner}/{repo}/tasks": + get: + summary: List tasks for repository + description: | + > [!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](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks-for-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#list-tasks-for-repository + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: '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`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + - name: creator_id + in: query + schema: + type: integer + description: Filter tasks by creator user ID + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="prev" (when current page > 1), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; + rel="next", ; + rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + post: + summary: Start a task + description: | + > [!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](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/create-task-in-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#start-a-task + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + requestBody: + required: true + description: The task creation parameters, including the user's prompt and + optional agent settings. + content: + application/json: + schema: + type: object + required: + - prompt + properties: + prompt: + type: string + description: The user's prompt for the agent + model: + type: string + 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`' + create_pull_request: + type: boolean + description: Whether to create a PR. + default: false + base_ref: + type: string + description: Base ref for new branch/PR + examples: + default: + value: + prompt: Fix the login button on the homepage + base_ref: main + responses: + '201': + description: Task created successfully + content: + application/json: + schema: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + examples: + default: + value: + id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: queued + session_count: 1 + artifacts: [] + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T00:00:00Z' + '400': + description: Problems parsing JSON + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/repos/{owner}/{repo}/tasks/{task_id}": + get: + summary: Get a task by repo + description: | + > [!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](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-repo-and-id + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#get-a-task-by-repo + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks": + get: + summary: List tasks + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a list of tasks for the authenticated user + + **Fine-grained access tokens for "List tasks"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#list-tasks + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: '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`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; rel="next", + ; rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks/{task_id}": + get: + summary: Get a task by ID + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a task by ID with its associated sessions + + **Fine-grained access tokens for "Get a task by ID"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-id + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#get-a-task-by-id + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Problems parsing request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation "/app": get: summary: Get the authenticated app @@ -55167,6 +57686,7 @@ paths: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp type: string url: description: The URL of the private registry. @@ -55235,6 +57755,15 @@ paths: api_host: description: The Cloudsmith API host. type: string + workload_identity_provider: + description: The full resource name of the GCP Workload + Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + type: string + service_account: + description: The GCP service account email to impersonate. + If omitted, the federated token is used directly (direct + WIF). + type: string created_at: type: string format: date-time @@ -55272,7 +57801,7 @@ paths: description: |2- Creates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see "[Encrypting secrets for the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/encrypting-secrets-for-the-rest-api)." - For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted. + For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted. OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. tags: @@ -55365,7 +57894,7 @@ paths: auth_type: description: The authentication type for the private registry. Defaults to `token` if not specified. Use `oidc_azure`, `oidc_aws`, `oidc_jfrog`, - or `oidc_cloudsmith` for OIDC authentication. + `oidc_cloudsmith`, or `oidc_gcp` for OIDC authentication. type: string enum: - token @@ -55374,6 +57903,7 @@ paths: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp tenant_id: description: The tenant ID of the Azure AD application. Required when `auth_type` is `oidc_azure`. @@ -55406,7 +57936,7 @@ paths: type: string audience: description: The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, - and required for `oidc_cloudsmith` auth types. + and `oidc_gcp`, and required for `oidc_cloudsmith` auth types. type: string identity_mapping_name: description: The JFrog identity mapping name. Optional for `oidc_jfrog` @@ -55424,6 +57954,16 @@ paths: description: The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default. type: string + workload_identity_provider: + description: The full resource name of the GCP Workload Identity + Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + Required when `auth_type` is `oidc_gcp`. + type: string + service_account: + description: The GCP service account email to impersonate. Optional + for `oidc_gcp` auth type. If omitted, the federated token is used + directly (direct WIF). + type: string required: - registry_type - url @@ -55472,6 +58012,16 @@ paths: namespace: my-org service_slug: my-service-account audience: https://github.com/my-org + org-private-registry-with-oidc-gcp: + summary: Example of an OIDC private registry configuration using Google + Cloud Artifact Registry + value: + registry_type: docker_registry + url: https://us-docker.pkg.dev/my-project/my-repo + auth_type: oidc_gcp + visibility: all + workload_identity_provider: projects/123456789/locations/global/workloadIdentityPools/github-pool/providers/github-provider + service_account: dependabot@my-project.iam.gserviceaccount.com responses: '201': description: The organization private registry configuration @@ -55514,6 +58064,7 @@ paths: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp type: string url: description: The URL of the private registry. @@ -55588,6 +58139,14 @@ paths: api_host: description: The Cloudsmith API host. type: string + workload_identity_provider: + description: The full resource name of the GCP Workload Identity + Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + type: string + service_account: + description: The GCP service account email to impersonate. If + omitted, the federated token is used directly (direct WIF). + type: string created_at: type: string format: date-time @@ -55711,7 +58270,7 @@ paths: description: |2- Updates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see "[Encrypting secrets for the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/encrypting-secrets-for-the-rest-api)." - For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted. + For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted. OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. tags: @@ -55809,6 +58368,7 @@ paths: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp tenant_id: description: The tenant ID of the Azure AD application. Required when `auth_type` is `oidc_azure`. @@ -55841,7 +58401,7 @@ paths: type: string audience: description: The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, - and required for `oidc_cloudsmith` auth types. + and `oidc_gcp`, and required for `oidc_cloudsmith` auth types. type: string identity_mapping_name: description: The JFrog identity mapping name. Optional for `oidc_jfrog` @@ -55859,6 +58419,16 @@ paths: description: The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default. type: string + workload_identity_provider: + description: The full resource name of the GCP Workload Identity + Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + Required when `auth_type` is `oidc_gcp`. + type: string + service_account: + description: The GCP service account email to impersonate. Optional + for `oidc_gcp` auth type. If omitted, the federated token is used + directly (direct WIF). + type: string examples: secret-based-update: summary: Update a secret-based private registry @@ -66662,6 +69232,240 @@ paths: enabledForGitHubApps: true category: actions subcategory: cache + "/repos/{owner}/{repo}/actions/concurrency_groups": + get: + summary: List concurrency groups for a repository + description: |- + Lists the active concurrency groups for a repository. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository + parameters: + - *484 + - *485 + - *17 + - *111 + responses: + '200': + description: Response + content: + application/json: + schema: + title: Concurrency Group List + description: A list of active concurrency groups for a repository. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - last_acquired_at + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + last_acquired_at: + type: string + format: date-time + nullable: true + examples: + default: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + last_acquired_at: '2026-01-15T16:14:23Z' + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + last_acquired_at: '2026-01-15T16:13:55Z' + headers: + Link: *47 + '422': *15 + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": + get: + summary: Get a concurrency group for a repository + description: |- + Gets a specific concurrency group for a repository, including all instances in the group's queue. + Returns 404 if the group is inactive or does not exist. + + Optionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items + ahead of the specified workflow run or job in the queue, plus the specified item itself + (returned as the last element). This is useful for determining what is blocking a particular + run or job. Returns 422 if the specified run or job is not in this concurrency group. + + When using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow + leases held on behalf of that run. Job-level leases within the run are not considered to + block the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow + leases on the job's ancestor paths. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/get-concurrency-group-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository + parameters: + - *484 + - *485 + - name: concurrency_group_name + description: The name of the concurrency group. + in: path + required: true + schema: + type: string + - name: ahead_of_run + description: |- + Filter to items ahead of this workflow run ID in the queue, plus the run itself. + Matches workflow-level concurrency and reusable-workflow leases held on behalf of + the run. Mutually exclusive with `ahead_of_job`. + in: query + required: false + schema: + type: integer + minimum: 1 + - name: ahead_of_job + description: |- + Filter to items ahead of this job ID in the queue, plus the job itself. + Matches job-level concurrency and reusable-workflow leases on the job's + ancestor paths. Mutually exclusive with `ahead_of_run`. + in: query + required: false + schema: + type: integer + minimum: 1 + responses: + '200': + description: Response + content: + application/json: + schema: + title: Concurrency Group + description: |- + A concurrency group with the workflow runs and jobs that are either currently holding + or waiting for the concurrency group lease. + type: object + required: + - group_name + - group_url + - total_count + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + total_count: + type: integer + group_members: + type: array + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: string + format: uri + description: API URL for the workflow run. + nullable: true + run_html_url: + type: string + format: uri + description: Web URL for the workflow run. + nullable: true + job_id: + type: integer + description: The ID of the job, when the item represents + a job-level or reusable-workflow-level lease. + job_name: + type: string + description: The display name of the job, when the item + represents a job-level or reusable-workflow-level lease. + job_url: + type: string + format: uri + description: API URL for the job. + nullable: true + job_html_url: + type: string + format: uri + description: Web URL for the job. + nullable: true + status: + type: string + enum: + - in_progress + - pending + examples: + default: + value: + group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + total_count: 3 + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + - run_id: 30433643 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433643 + status: pending + - run_id: 30433644 + run_name: Deploy hotfix + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644 + job_id: 798245260 + job_name: deploy + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260 + status: pending + '404': *6 + '422': *15 + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/jobs/{job_id}": get: summary: Get a job for a workflow run @@ -69622,6 +72426,192 @@ paths: enabledForGitHubApps: true category: actions subcategory: workflow-runs + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": + get: + summary: List concurrency groups for a workflow run + description: |- + Lists all concurrency groups associated with a workflow run or its jobs. + + The set of groups is derived from the run's configuration, so a group is + included even when the run no longer has any items currently holding or + waiting in it. In that case the `group_members` array will be empty. + `total_count` reflects the number of groups the run participates in by + configuration, not the number with active items. + + This differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`, + which returns 404 when a group has no active items. That endpoint reports + the live state of a group repo-wide, while this endpoint reports the + groups associated with a specific run by configuration. + + Results are sorted by group name and support cursor-based pagination via + `before` and `after`. The `after` cursor paginates forward only and does + not emit a `rel="prev"` Link; use `before` to page backward from a + forward page's `next` cursor. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-workflow-run + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run + parameters: + - *484 + - *485 + - *508 + - *17 + - *110 + - *111 + responses: + '200': + description: Response + content: + application/json: + schema: + title: Concurrency Group Run List + description: A list of concurrency groups associated with a workflow + run. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + description: |- + The total number of concurrency groups this workflow run participates in, + derived from the run's configuration. This count is not filtered by + whether the run currently holds or is waiting in each group, so it can + include groups whose `group_members` array is empty (for example, when + the run has already released its lease in that group). + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: |- + API URL for this concurrency group. May return 404 if the group + has no active items at the time it is requested, since the + get-by-name endpoint reports the live repo-wide state of a group + while this endpoint lists groups associated with a run by + configuration. + group_members: + type: array + description: |- + Items belonging to this workflow run that are either currently holding or + waiting for the concurrency group lease. May be empty if the run no + longer has any active or queued items in this group. + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + - position + - position_url + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: string + format: uri + description: API URL for the workflow run. + nullable: true + run_html_url: + type: string + format: uri + description: Web URL for the workflow run. + nullable: true + position: + type: integer + description: Queue position. 0 means the item holds + the concurrency lease (in_progress), 1 or higher + means queued (pending). + position_url: + type: string + format: uri + description: API URL to get items ahead of this item + in the concurrency group. + job_id: + type: integer + description: The ID of the job, when the item represents + a job-level or reusable-workflow-level lease. + nullable: true + job_name: + type: string + description: The display name of the job, when the + item represents a job-level or reusable-workflow-level + lease. + nullable: true + job_url: + type: string + format: uri + description: API URL for the job. + nullable: true + job_html_url: + type: string + format: uri + description: Web URL for the job. + nullable: true + status: + type: string + enum: + - in_progress + - pending + examples: + default: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + position: 0 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642 + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: pending + position: 2 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260 + job_id: 798245260 + job_name: build + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260 + headers: + Link: *47 + '404': *6 + '422': *15 + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": post: summary: Review custom deployment protection rules for a workflow run diff --git a/descriptions/ghec/dereferenced/ghec.deref.json b/descriptions/ghec/dereferenced/ghec.deref.json index bf75dc684..8ddd753d6 100644 --- a/descriptions/ghec/dereferenced/ghec.deref.json +++ b/descriptions/ghec/dereferenced/ghec.deref.json @@ -2168,6 +2168,3164 @@ } } }, + "/agents/repos/{owner}/{repo}/tasks": { + "get": { + "summary": "List tasks for repository", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for a specific repository\n\n**Fine-grained access tokens for \"List tasks for repository\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks-for-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#list-tasks-for-repository" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "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`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + }, + { + "name": "creator_id", + "in": "query", + "schema": { + "type": "integer" + }, + "description": "Filter tasks by creator user ID" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"prev\" (when current page > 1),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + }, + "post": { + "summary": "Start a task", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nStarts a new Copilot cloud agent task for a repository.\n\nThis endpoint is only available to users with a Copilot Business or Copilot Enterprise subscription.\n\n**Fine-grained access tokens for \"Start a task\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read and write)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/create-task-in-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#start-a-task" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + } + ], + "requestBody": { + "required": true, + "description": "The task creation parameters, including the user's prompt and optional agent settings.", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "prompt" + ], + "properties": { + "prompt": { + "type": "string", + "description": "The user's prompt for the agent" + }, + "model": { + "type": "string", + "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`" + }, + "create_pull_request": { + "type": "boolean", + "description": "Whether to create a PR.", + "default": false + }, + "base_ref": { + "type": "string", + "description": "Base ref for new branch/PR" + } + } + }, + "examples": { + "default": { + "value": { + "prompt": "Fix the login button on the homepage", + "base_ref": "main" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Task created successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "examples": { + "default": { + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "queued", + "session_count": 1, + "artifacts": [], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T00:00:00Z" + } + } + } + } + } + }, + "400": { + "description": "Problems parsing JSON", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/repos/{owner}/{repo}/tasks/{task_id}": { + "get": { + "summary": "Get a task by repo", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID scoped to an owner/repo path\n\n**Fine-grained access tokens for \"Get a task by repo\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-repo-and-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#get-a-task-by-repo" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks": { + "get": { + "summary": "List tasks", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for the authenticated user\n\n**Fine-grained access tokens for \"List tasks\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#list-tasks" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "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`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks/{task_id}": { + "get": { + "summary": "Get a task by ID", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID with its associated sessions\n\n**Fine-grained access tokens for \"Get a task by ID\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#get-a-task-by-id" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Problems parsing request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, "/app": { "get": { "summary": "Get the authenticated app", @@ -229006,7 +232164,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ], "type": "string" }, @@ -229087,6 +232246,14 @@ "description": "The Cloudsmith API host.", "type": "string" }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`).", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. If omitted, the federated token is used directly (direct WIF).", + "type": "string" + }, "created_at": { "type": "string", "format": "date-time" @@ -229231,7 +232398,7 @@ }, "post": { "summary": "Create a private registry for an organization", - "description": "\nCreates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", + "description": "\nCreates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", "tags": [ "private-registries" ], @@ -229320,7 +232487,7 @@ } }, "auth_type": { - "description": "The authentication type for the private registry. Defaults to `token` if not specified. Use `oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith` for OIDC authentication.", + "description": "The authentication type for the private registry. Defaults to `token` if not specified. Use `oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp` for OIDC authentication.", "type": "string", "enum": [ "token", @@ -229328,7 +232495,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ] }, "tenant_id": { @@ -229364,7 +232532,7 @@ "type": "string" }, "audience": { - "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and required for `oidc_cloudsmith` auth types.", + "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and `oidc_gcp`, and required for `oidc_cloudsmith` auth types.", "type": "string" }, "identity_mapping_name": { @@ -229382,6 +232550,14 @@ "api_host": { "description": "The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default.", "type": "string" + }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). Required when `auth_type` is `oidc_gcp`.", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. Optional for `oidc_gcp` auth type. If omitted, the federated token is used directly (direct WIF).", + "type": "string" } }, "required": [ @@ -229440,6 +232616,17 @@ "service_slug": "my-service-account", "audience": "https://github.com/my-org" } + }, + "org-private-registry-with-oidc-gcp": { + "summary": "Example of an OIDC private registry configuration using Google Cloud Artifact Registry", + "value": { + "registry_type": "docker_registry", + "url": "https://us-docker.pkg.dev/my-project/my-repo", + "auth_type": "oidc_gcp", + "visibility": "all", + "workload_identity_provider": "projects/123456789/locations/global/workloadIdentityPools/github-pool/providers/github-provider", + "service_account": "dependabot@my-project.iam.gserviceaccount.com" + } } } } @@ -229489,7 +232676,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ], "type": "string" }, @@ -229576,6 +232764,14 @@ "description": "The Cloudsmith API host.", "type": "string" }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`).", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. If omitted, the federated token is used directly (direct WIF).", + "type": "string" + }, "created_at": { "type": "string", "format": "date-time" @@ -229903,7 +233099,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ], "type": "string" }, @@ -229984,6 +233181,14 @@ "description": "The Cloudsmith API host.", "type": "string" }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`).", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. If omitted, the federated token is used directly (direct WIF).", + "type": "string" + }, "created_at": { "type": "string", "format": "date-time" @@ -230052,7 +233257,7 @@ }, "patch": { "summary": "Update a private registry for an organization", - "description": "\nUpdates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", + "description": "\nUpdates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", "tags": [ "private-registries" ], @@ -230158,7 +233363,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ] }, "tenant_id": { @@ -230194,7 +233400,7 @@ "type": "string" }, "audience": { - "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and required for `oidc_cloudsmith` auth types.", + "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and `oidc_gcp`, and required for `oidc_cloudsmith` auth types.", "type": "string" }, "identity_mapping_name": { @@ -230212,6 +233418,14 @@ "api_host": { "description": "The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default.", "type": "string" + }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). Required when `auth_type` is `oidc_gcp`.", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. Optional for `oidc_gcp` auth type. If omitted, the federated token is used directly (direct WIF).", + "type": "string" } } }, @@ -300532,6 +303746,506 @@ } } }, + "/repos/{owner}/{repo}/actions/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a repository", + "description": "Lists the active concurrency groups for a repository.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository" + }, + "parameters": [ + { + "name": "owner", + "description": "The account owner of the repository. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "repo", + "description": "The name of the repository without the `.git` extension. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "per_page", + "description": "The number of results per page (max 100). For more information, see \"[Using pagination in the REST API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "schema": { + "type": "integer", + "default": 30 + } + }, + { + "name": "after", + "description": "A cursor, as given in the [Link header](https://docs.github.com/enterprise-cloud@latest/rest/guides/using-pagination-in-the-rest-api#using-link-headers). If specified, the query only searches for results after this cursor. For more information, see \"[Using pagination in the REST API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "title": "Concurrency Group List", + "description": "A list of active concurrency groups for a repository.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer" + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "last_acquired_at" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "last_acquired_at": { + "type": "string", + "format": "date-time", + "nullable": true + } + } + } + } + } + }, + "examples": { + "default": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "last_acquired_at": "2026-01-15T16:14:23Z" + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "last_acquired_at": "2026-01-15T16:13:55Z" + } + ] + } + } + } + } + }, + "headers": { + "Link": { + "example": "; rel=\"next\", ; rel=\"last\"", + "schema": { + "type": "string" + } + } + } + }, + "422": { + "description": "Validation failed, or the endpoint has been spammed.", + "content": { + "application/json": { + "schema": { + "title": "Validation Error", + "description": "Validation Error", + "type": "object", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "resource": { + "type": "string" + }, + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "code": { + "type": "string" + }, + "index": { + "type": "integer" + }, + "value": { + "oneOf": [ + { + "type": "string", + "nullable": true + }, + { + "type": "integer", + "nullable": true + }, + { + "type": "array", + "nullable": true, + "items": { + "type": "string" + } + } + ] + } + } + } + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": { + "get": { + "summary": "Get a concurrency group for a repository", + "description": "Gets a specific concurrency group for a repository, including all instances in the group's queue.\nReturns 404 if the group is inactive or does not exist.\n\nOptionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items\nahead of the specified workflow run or job in the queue, plus the specified item itself\n(returned as the last element). This is useful for determining what is blocking a particular\nrun or job. Returns 422 if the specified run or job is not in this concurrency group.\n\nWhen using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow\nleases held on behalf of that run. Job-level leases within the run are not considered to\nblock the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow\nleases on the job's ancestor paths.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/get-concurrency-group-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository" + }, + "parameters": [ + { + "name": "owner", + "description": "The account owner of the repository. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "repo", + "description": "The name of the repository without the `.git` extension. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "concurrency_group_name", + "description": "The name of the concurrency group.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "ahead_of_run", + "description": "Filter to items ahead of this workflow run ID in the queue, plus the run itself.\nMatches workflow-level concurrency and reusable-workflow leases held on behalf of\nthe run. Mutually exclusive with `ahead_of_job`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + }, + { + "name": "ahead_of_job", + "description": "Filter to items ahead of this job ID in the queue, plus the job itself.\nMatches job-level concurrency and reusable-workflow leases on the job's\nancestor paths. Mutually exclusive with `ahead_of_run`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "title": "Concurrency Group", + "description": "A concurrency group with the workflow runs and jobs that are either currently holding\nor waiting for the concurrency group lease.", + "type": "object", + "required": [ + "group_name", + "group_url", + "total_count", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "total_count": { + "type": "integer" + }, + "group_members": { + "type": "array", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": "string", + "format": "uri", + "description": "API URL for the workflow run.", + "nullable": true + }, + "run_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the workflow run.", + "nullable": true + }, + "job_id": { + "type": "integer", + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_name": { + "type": "string", + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_url": { + "type": "string", + "format": "uri", + "description": "API URL for the job.", + "nullable": true + }, + "job_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the job.", + "nullable": true + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + }, + "examples": { + "default": { + "value": { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "total_count": 3, + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress" + }, + { + "run_id": 30433643, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433643", + "status": "pending" + }, + { + "run_id": 30433644, + "run_name": "Deploy hotfix", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644", + "job_id": 798245260, + "job_name": "deploy", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260", + "status": "pending" + } + ] + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "422": { + "description": "Validation failed, or the endpoint has been spammed.", + "content": { + "application/json": { + "schema": { + "title": "Validation Error", + "description": "Validation Error", + "type": "object", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "resource": { + "type": "string" + }, + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "code": { + "type": "string" + }, + "index": { + "type": "integer" + }, + "value": { + "oneOf": [ + { + "type": "string", + "nullable": true + }, + { + "type": "integer", + "nullable": true + }, + { + "type": "array", + "nullable": true, + "items": { + "type": "string" + } + } + ] + } + } + } + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/jobs/{job_id}": { "get": { "summary": "Get a job for a workflow run", @@ -315978,6 +319692,350 @@ } } }, + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a workflow run", + "description": "Lists all concurrency groups associated with a workflow run or its jobs.\n\nThe set of groups is derived from the run's configuration, so a group is\nincluded even when the run no longer has any items currently holding or\nwaiting in it. In that case the `group_members` array will be empty.\n`total_count` reflects the number of groups the run participates in by\nconfiguration, not the number with active items.\n\nThis differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`,\nwhich returns 404 when a group has no active items. That endpoint reports\nthe live state of a group repo-wide, while this endpoint reports the\ngroups associated with a specific run by configuration.\n\nResults are sorted by group name and support cursor-based pagination via\n`before` and `after`. The `after` cursor paginates forward only and does\nnot emit a `rel=\"prev\"` Link; use `before` to page backward from a\nforward page's `next` cursor.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-workflow-run", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run" + }, + "parameters": [ + { + "name": "owner", + "description": "The account owner of the repository. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "repo", + "description": "The name of the repository without the `.git` extension. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "run_id", + "description": "The unique identifier of the workflow run.", + "in": "path", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "per_page", + "description": "The number of results per page (max 100). For more information, see \"[Using pagination in the REST API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "schema": { + "type": "integer", + "default": 30 + } + }, + { + "name": "before", + "description": "A cursor, as given in the [Link header](https://docs.github.com/enterprise-cloud@latest/rest/guides/using-pagination-in-the-rest-api#using-link-headers). If specified, the query only searches for results before this cursor. For more information, see \"[Using pagination in the REST API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "after", + "description": "A cursor, as given in the [Link header](https://docs.github.com/enterprise-cloud@latest/rest/guides/using-pagination-in-the-rest-api#using-link-headers). If specified, the query only searches for results after this cursor. For more information, see \"[Using pagination in the REST API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "title": "Concurrency Group Run List", + "description": "A list of concurrency groups associated with a workflow run.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer", + "description": "The total number of concurrency groups this workflow run participates in,\nderived from the run's configuration. This count is not filtered by\nwhether the run currently holds or is waiting in each group, so it can\ninclude groups whose `group_members` array is empty (for example, when\nthe run has already released its lease in that group)." + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group. May return 404 if the group\nhas no active items at the time it is requested, since the\nget-by-name endpoint reports the live repo-wide state of a group\nwhile this endpoint lists groups associated with a run by\nconfiguration." + }, + "group_members": { + "type": "array", + "description": "Items belonging to this workflow run that are either currently holding or\nwaiting for the concurrency group lease. May be empty if the run no\nlonger has any active or queued items in this group.", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status", + "position", + "position_url" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": "string", + "format": "uri", + "description": "API URL for the workflow run.", + "nullable": true + }, + "run_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the workflow run.", + "nullable": true + }, + "position": { + "type": "integer", + "description": "Queue position. 0 means the item holds the concurrency lease (in_progress), 1 or higher means queued (pending)." + }, + "position_url": { + "type": "string", + "format": "uri", + "description": "API URL to get items ahead of this item in the concurrency group." + }, + "job_id": { + "type": "integer", + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease.", + "nullable": true + }, + "job_name": { + "type": "string", + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease.", + "nullable": true + }, + "job_url": { + "type": "string", + "format": "uri", + "description": "API URL for the job.", + "nullable": true + }, + "job_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the job.", + "nullable": true + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + } + } + } + }, + "examples": { + "default": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress", + "position": 0, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642" + } + ] + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "pending", + "position": 2, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260", + "job_id": 798245260, + "job_name": "build", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260" + } + ] + } + ] + } + } + } + } + }, + "headers": { + "Link": { + "example": "; rel=\"next\", ; rel=\"last\"", + "schema": { + "type": "string" + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "422": { + "description": "Validation failed, or the endpoint has been spammed.", + "content": { + "application/json": { + "schema": { + "title": "Validation Error", + "description": "Validation Error", + "type": "object", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "resource": { + "type": "string" + }, + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "code": { + "type": "string" + }, + "index": { + "type": "integer" + }, + "value": { + "oneOf": [ + { + "type": "string", + "nullable": true + }, + { + "type": "integer", + "nullable": true + }, + { + "type": "array", + "nullable": true, + "items": { + "type": "string" + } + } + ] + } + } + } + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": { "post": { "summary": "Review custom deployment protection rules for a workflow run", diff --git a/descriptions/ghec/dereferenced/ghec.deref.yaml b/descriptions/ghec/dereferenced/ghec.deref.yaml index 5fb054a8b..619811f30 100644 --- a/descriptions/ghec/dereferenced/ghec.deref.yaml +++ b/descriptions/ghec/dereferenced/ghec.deref.yaml @@ -1183,6 +1183,2525 @@ paths: enabledForGitHubApps: true category: security-advisories subcategory: global-advisories + "/agents/repos/{owner}/{repo}/tasks": + get: + summary: List tasks for repository + description: | + > [!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](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks-for-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#list-tasks-for-repository + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: '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`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + - name: creator_id + in: query + schema: + type: integer + description: Filter tasks by creator user ID + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="prev" (when current page > 1), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; + rel="next", ; + rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + post: + summary: Start a task + description: | + > [!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](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/create-task-in-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#start-a-task + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + requestBody: + required: true + description: The task creation parameters, including the user's prompt and + optional agent settings. + content: + application/json: + schema: + type: object + required: + - prompt + properties: + prompt: + type: string + description: The user's prompt for the agent + model: + type: string + 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`' + create_pull_request: + type: boolean + description: Whether to create a PR. + default: false + base_ref: + type: string + description: Base ref for new branch/PR + examples: + default: + value: + prompt: Fix the login button on the homepage + base_ref: main + responses: + '201': + description: Task created successfully + content: + application/json: + schema: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + examples: + default: + value: + id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: queued + session_count: 1 + artifacts: [] + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T00:00:00Z' + '400': + description: Problems parsing JSON + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/repos/{owner}/{repo}/tasks/{task_id}": + get: + summary: Get a task by repo + description: | + > [!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](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-repo-and-id + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#get-a-task-by-repo + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks": + get: + summary: List tasks + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a list of tasks for the authenticated user + + **Fine-grained access tokens for "List tasks"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#list-tasks + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: '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`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; rel="next", + ; rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks/{task_id}": + get: + summary: Get a task by ID + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a task by ID with its associated sessions + + **Fine-grained access tokens for "Get a task by ID"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-id + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#get-a-task-by-id + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Problems parsing request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation "/app": get: summary: Get the authenticated app @@ -55911,6 +58430,7 @@ paths: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp type: string url: description: The URL of the private registry. @@ -55979,6 +58499,15 @@ paths: api_host: description: The Cloudsmith API host. type: string + workload_identity_provider: + description: The full resource name of the GCP Workload + Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + type: string + service_account: + description: The GCP service account email to impersonate. + If omitted, the federated token is used directly (direct + WIF). + type: string created_at: type: string format: date-time @@ -56016,7 +58545,7 @@ paths: description: |2- Creates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see "[Encrypting secrets for the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/encrypting-secrets-for-the-rest-api)." - For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted. + For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted. OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. tags: @@ -56109,7 +58638,7 @@ paths: auth_type: description: The authentication type for the private registry. Defaults to `token` if not specified. Use `oidc_azure`, `oidc_aws`, `oidc_jfrog`, - or `oidc_cloudsmith` for OIDC authentication. + `oidc_cloudsmith`, or `oidc_gcp` for OIDC authentication. type: string enum: - token @@ -56118,6 +58647,7 @@ paths: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp tenant_id: description: The tenant ID of the Azure AD application. Required when `auth_type` is `oidc_azure`. @@ -56150,7 +58680,7 @@ paths: type: string audience: description: The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, - and required for `oidc_cloudsmith` auth types. + and `oidc_gcp`, and required for `oidc_cloudsmith` auth types. type: string identity_mapping_name: description: The JFrog identity mapping name. Optional for `oidc_jfrog` @@ -56168,6 +58698,16 @@ paths: description: The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default. type: string + workload_identity_provider: + description: The full resource name of the GCP Workload Identity + Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + Required when `auth_type` is `oidc_gcp`. + type: string + service_account: + description: The GCP service account email to impersonate. Optional + for `oidc_gcp` auth type. If omitted, the federated token is used + directly (direct WIF). + type: string required: - registry_type - url @@ -56216,6 +58756,16 @@ paths: namespace: my-org service_slug: my-service-account audience: https://github.com/my-org + org-private-registry-with-oidc-gcp: + summary: Example of an OIDC private registry configuration using Google + Cloud Artifact Registry + value: + registry_type: docker_registry + url: https://us-docker.pkg.dev/my-project/my-repo + auth_type: oidc_gcp + visibility: all + workload_identity_provider: projects/123456789/locations/global/workloadIdentityPools/github-pool/providers/github-provider + service_account: dependabot@my-project.iam.gserviceaccount.com responses: '201': description: The organization private registry configuration @@ -56258,6 +58808,7 @@ paths: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp type: string url: description: The URL of the private registry. @@ -56332,6 +58883,14 @@ paths: api_host: description: The Cloudsmith API host. type: string + workload_identity_provider: + description: The full resource name of the GCP Workload Identity + Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + type: string + service_account: + description: The GCP service account email to impersonate. If + omitted, the federated token is used directly (direct WIF). + type: string created_at: type: string format: date-time @@ -56455,7 +59014,7 @@ paths: description: |2- Updates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see "[Encrypting secrets for the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/encrypting-secrets-for-the-rest-api)." - For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted. + For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted. OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. tags: @@ -56553,6 +59112,7 @@ paths: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp tenant_id: description: The tenant ID of the Azure AD application. Required when `auth_type` is `oidc_azure`. @@ -56585,7 +59145,7 @@ paths: type: string audience: description: The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, - and required for `oidc_cloudsmith` auth types. + and `oidc_gcp`, and required for `oidc_cloudsmith` auth types. type: string identity_mapping_name: description: The JFrog identity mapping name. Optional for `oidc_jfrog` @@ -56603,6 +59163,16 @@ paths: description: The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default. type: string + workload_identity_provider: + description: The full resource name of the GCP Workload Identity + Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + Required when `auth_type` is `oidc_gcp`. + type: string + service_account: + description: The GCP service account email to impersonate. Optional + for `oidc_gcp` auth type. If omitted, the federated token is used + directly (direct WIF). + type: string examples: secret-based-update: summary: Update a secret-based private registry @@ -67711,6 +70281,240 @@ paths: enabledForGitHubApps: true category: actions subcategory: cache + "/repos/{owner}/{repo}/actions/concurrency_groups": + get: + summary: List concurrency groups for a repository + description: |- + Lists the active concurrency groups for a repository. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository + parameters: + - *486 + - *487 + - *17 + - *111 + responses: + '200': + description: Response + content: + application/json: + schema: + title: Concurrency Group List + description: A list of active concurrency groups for a repository. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - last_acquired_at + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + last_acquired_at: + type: string + format: date-time + nullable: true + examples: + default: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + last_acquired_at: '2026-01-15T16:14:23Z' + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + last_acquired_at: '2026-01-15T16:13:55Z' + headers: + Link: *47 + '422': *15 + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": + get: + summary: Get a concurrency group for a repository + description: |- + Gets a specific concurrency group for a repository, including all instances in the group's queue. + Returns 404 if the group is inactive or does not exist. + + Optionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items + ahead of the specified workflow run or job in the queue, plus the specified item itself + (returned as the last element). This is useful for determining what is blocking a particular + run or job. Returns 422 if the specified run or job is not in this concurrency group. + + When using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow + leases held on behalf of that run. Job-level leases within the run are not considered to + block the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow + leases on the job's ancestor paths. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/get-concurrency-group-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository + parameters: + - *486 + - *487 + - name: concurrency_group_name + description: The name of the concurrency group. + in: path + required: true + schema: + type: string + - name: ahead_of_run + description: |- + Filter to items ahead of this workflow run ID in the queue, plus the run itself. + Matches workflow-level concurrency and reusable-workflow leases held on behalf of + the run. Mutually exclusive with `ahead_of_job`. + in: query + required: false + schema: + type: integer + minimum: 1 + - name: ahead_of_job + description: |- + Filter to items ahead of this job ID in the queue, plus the job itself. + Matches job-level concurrency and reusable-workflow leases on the job's + ancestor paths. Mutually exclusive with `ahead_of_run`. + in: query + required: false + schema: + type: integer + minimum: 1 + responses: + '200': + description: Response + content: + application/json: + schema: + title: Concurrency Group + description: |- + A concurrency group with the workflow runs and jobs that are either currently holding + or waiting for the concurrency group lease. + type: object + required: + - group_name + - group_url + - total_count + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + total_count: + type: integer + group_members: + type: array + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: string + format: uri + description: API URL for the workflow run. + nullable: true + run_html_url: + type: string + format: uri + description: Web URL for the workflow run. + nullable: true + job_id: + type: integer + description: The ID of the job, when the item represents + a job-level or reusable-workflow-level lease. + job_name: + type: string + description: The display name of the job, when the item + represents a job-level or reusable-workflow-level lease. + job_url: + type: string + format: uri + description: API URL for the job. + nullable: true + job_html_url: + type: string + format: uri + description: Web URL for the job. + nullable: true + status: + type: string + enum: + - in_progress + - pending + examples: + default: + value: + group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + total_count: 3 + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + - run_id: 30433643 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433643 + status: pending + - run_id: 30433644 + run_name: Deploy hotfix + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644 + job_id: 798245260 + job_name: deploy + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260 + status: pending + '404': *6 + '422': *15 + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/jobs/{job_id}": get: summary: Get a job for a workflow run @@ -70671,6 +73475,192 @@ paths: enabledForGitHubApps: true category: actions subcategory: workflow-runs + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": + get: + summary: List concurrency groups for a workflow run + description: |- + Lists all concurrency groups associated with a workflow run or its jobs. + + The set of groups is derived from the run's configuration, so a group is + included even when the run no longer has any items currently holding or + waiting in it. In that case the `group_members` array will be empty. + `total_count` reflects the number of groups the run participates in by + configuration, not the number with active items. + + This differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`, + which returns 404 when a group has no active items. That endpoint reports + the live state of a group repo-wide, while this endpoint reports the + groups associated with a specific run by configuration. + + Results are sorted by group name and support cursor-based pagination via + `before` and `after`. The `after` cursor paginates forward only and does + not emit a `rel="prev"` Link; use `before` to page backward from a + forward page's `next` cursor. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-workflow-run + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run + parameters: + - *486 + - *487 + - *510 + - *17 + - *110 + - *111 + responses: + '200': + description: Response + content: + application/json: + schema: + title: Concurrency Group Run List + description: A list of concurrency groups associated with a workflow + run. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + description: |- + The total number of concurrency groups this workflow run participates in, + derived from the run's configuration. This count is not filtered by + whether the run currently holds or is waiting in each group, so it can + include groups whose `group_members` array is empty (for example, when + the run has already released its lease in that group). + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: |- + API URL for this concurrency group. May return 404 if the group + has no active items at the time it is requested, since the + get-by-name endpoint reports the live repo-wide state of a group + while this endpoint lists groups associated with a run by + configuration. + group_members: + type: array + description: |- + Items belonging to this workflow run that are either currently holding or + waiting for the concurrency group lease. May be empty if the run no + longer has any active or queued items in this group. + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + - position + - position_url + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: string + format: uri + description: API URL for the workflow run. + nullable: true + run_html_url: + type: string + format: uri + description: Web URL for the workflow run. + nullable: true + position: + type: integer + description: Queue position. 0 means the item holds + the concurrency lease (in_progress), 1 or higher + means queued (pending). + position_url: + type: string + format: uri + description: API URL to get items ahead of this item + in the concurrency group. + job_id: + type: integer + description: The ID of the job, when the item represents + a job-level or reusable-workflow-level lease. + nullable: true + job_name: + type: string + description: The display name of the job, when the + item represents a job-level or reusable-workflow-level + lease. + nullable: true + job_url: + type: string + format: uri + description: API URL for the job. + nullable: true + job_html_url: + type: string + format: uri + description: Web URL for the job. + nullable: true + status: + type: string + enum: + - in_progress + - pending + examples: + default: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + position: 0 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642 + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: pending + position: 2 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260 + job_id: 798245260 + job_name: build + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260 + headers: + Link: *47 + '404': *6 + '422': *15 + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": post: summary: Review custom deployment protection rules for a workflow run diff --git a/descriptions/ghec/ghec.2022-11-28.json b/descriptions/ghec/ghec.2022-11-28.json index c3f84d7e7..98a183742 100644 --- a/descriptions/ghec/ghec.2022-11-28.json +++ b/descriptions/ghec/ghec.2022-11-28.json @@ -546,6 +546,3164 @@ } } }, + "/agents/repos/{owner}/{repo}/tasks": { + "get": { + "summary": "List tasks for repository", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for a specific repository\n\n**Fine-grained access tokens for \"List tasks for repository\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks-for-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#list-tasks-for-repository" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "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`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + }, + { + "name": "creator_id", + "in": "query", + "schema": { + "type": "integer" + }, + "description": "Filter tasks by creator user ID" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"prev\" (when current page > 1),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + }, + "post": { + "summary": "Start a task", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nStarts a new Copilot cloud agent task for a repository.\n\nThis endpoint is only available to users with a Copilot Business or Copilot Enterprise subscription.\n\n**Fine-grained access tokens for \"Start a task\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read and write)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/create-task-in-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#start-a-task" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + } + ], + "requestBody": { + "required": true, + "description": "The task creation parameters, including the user's prompt and optional agent settings.", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "prompt" + ], + "properties": { + "prompt": { + "type": "string", + "description": "The user's prompt for the agent" + }, + "model": { + "type": "string", + "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`" + }, + "create_pull_request": { + "type": "boolean", + "description": "Whether to create a PR.", + "default": false + }, + "base_ref": { + "type": "string", + "description": "Base ref for new branch/PR" + } + } + }, + "examples": { + "default": { + "value": { + "prompt": "Fix the login button on the homepage", + "base_ref": "main" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Task created successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "examples": { + "default": { + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "queued", + "session_count": 1, + "artifacts": [], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T00:00:00Z" + } + } + } + } + } + }, + "400": { + "description": "Problems parsing JSON", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/repos/{owner}/{repo}/tasks/{task_id}": { + "get": { + "summary": "Get a task by repo", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID scoped to an owner/repo path\n\n**Fine-grained access tokens for \"Get a task by repo\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-repo-and-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#get-a-task-by-repo" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks": { + "get": { + "summary": "List tasks", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for the authenticated user\n\n**Fine-grained access tokens for \"List tasks\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#list-tasks" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "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`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks/{task_id}": { + "get": { + "summary": "Get a task by ID", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID with its associated sessions\n\n**Fine-grained access tokens for \"Get a task by ID\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#get-a-task-by-id" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Problems parsing request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, "/app": { "get": { "summary": "Get the authenticated app", @@ -40143,7 +43301,7 @@ }, "post": { "summary": "Create a private registry for an organization", - "description": "\nCreates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", + "description": "\nCreates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", "tags": [ "private-registries" ], @@ -40226,7 +43384,387 @@ } }, "auth_type": { - "description": "The authentication type for the private registry. Defaults to `token` if not specified. Use `oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith` for OIDC authentication.", + "description": "The authentication type for the private registry. Defaults to `token` if not specified. Use `oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp` for OIDC authentication.", + "type": "string", + "enum": [ + "token", + "username_password", + "oidc_azure", + "oidc_aws", + "oidc_jfrog", + "oidc_cloudsmith", + "oidc_gcp" + ] + }, + "tenant_id": { + "description": "The tenant ID of the Azure AD application. Required when `auth_type` is `oidc_azure`.", + "type": "string" + }, + "client_id": { + "description": "The client ID of the Azure AD application. Required when `auth_type` is `oidc_azure`.", + "type": "string" + }, + "aws_region": { + "description": "The AWS region. Required when `auth_type` is `oidc_aws`.", + "type": "string" + }, + "account_id": { + "description": "The AWS account ID. Required when `auth_type` is `oidc_aws`.", + "type": "string" + }, + "role_name": { + "description": "The AWS IAM role name. Required when `auth_type` is `oidc_aws`.", + "type": "string" + }, + "domain": { + "description": "The CodeArtifact domain. Required when `auth_type` is `oidc_aws`.", + "type": "string" + }, + "domain_owner": { + "description": "The CodeArtifact domain owner (AWS account ID). Required when `auth_type` is `oidc_aws`.", + "type": "string" + }, + "jfrog_oidc_provider_name": { + "description": "The JFrog OIDC provider name. Required when `auth_type` is `oidc_jfrog`.", + "type": "string" + }, + "audience": { + "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and `oidc_gcp`, and required for `oidc_cloudsmith` auth types.", + "type": "string" + }, + "identity_mapping_name": { + "description": "The JFrog identity mapping name. Optional for `oidc_jfrog` auth type.", + "type": "string" + }, + "namespace": { + "description": "The Cloudsmith organization namespace. Required when `auth_type` is `oidc_cloudsmith`.", + "type": "string" + }, + "service_slug": { + "description": "The Cloudsmith service account slug. Required when `auth_type` is `oidc_cloudsmith`.", + "type": "string" + }, + "api_host": { + "description": "The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default.", + "type": "string" + }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). Required when `auth_type` is `oidc_gcp`.", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. Optional for `oidc_gcp` auth type. If omitted, the federated token is used directly (direct WIF).", + "type": "string" + } + }, + "required": [ + "registry_type", + "url", + "visibility" + ] + }, + "examples": { + "org-private-registry-with-private-visibility": { + "summary": "Example of a private registry configuration with private visibility", + "value": { + "registry_type": "maven_repository", + "url": "https://maven.pkg.github.com/organization/", + "username": "monalisa", + "replaces_base": true, + "encrypted_value": "c2VjcmV0", + "key_id": "012345678912345678", + "visibility": "private" + } + }, + "org-private-registry-with-selected-visibility": { + "summary": "Example of a private registry configuration with selected visibility", + "value": { + "registry_type": "maven_repository", + "url": "https://maven.pkg.github.com/organization/", + "username": "monalisa", + "encrypted_value": "c2VjcmV0", + "key_id": "012345678912345678", + "visibility": "selected", + "selected_repository_ids": [ + 1296269, + 1296280 + ] + } + }, + "org-private-registry-with-oidc-azure": { + "summary": "Example of an OIDC private registry configuration using Azure", + "value": { + "registry_type": "docker_registry", + "url": "https://myregistry.azurecr.io", + "auth_type": "oidc_azure", + "visibility": "all", + "tenant_id": "12345678-1234-1234-1234-123456789012", + "client_id": "abcdef01-2345-6789-abcd-ef0123456789" + } + }, + "org-private-registry-with-oidc-cloudsmith": { + "summary": "Example of an OIDC private registry configuration using Cloudsmith", + "value": { + "registry_type": "npm_registry", + "url": "https://npm.cloudsmith.io/my-org/my-repo/", + "auth_type": "oidc_cloudsmith", + "visibility": "all", + "namespace": "my-org", + "service_slug": "my-service-account", + "audience": "https://github.com/my-org" + } + }, + "org-private-registry-with-oidc-gcp": { + "summary": "Example of an OIDC private registry configuration using Google Cloud Artifact Registry", + "value": { + "registry_type": "docker_registry", + "url": "https://us-docker.pkg.dev/my-project/my-repo", + "auth_type": "oidc_gcp", + "visibility": "all", + "workload_identity_provider": "projects/123456789/locations/global/workloadIdentityPools/github-pool/providers/github-provider", + "service_account": "dependabot@my-project.iam.gserviceaccount.com" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "The organization private registry configuration", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/org-private-registry-configuration-with-selected-repositories" + }, + "examples": { + "org-private-registry-with-selected-visibility": { + "$ref": "#/components/examples/org-private-registry-configuration" + }, + "org-private-registry-with-private-visibility": { + "$ref": "#/components/examples/org-private-registry-configuration-with-selected-repositories" + } + } + } + } + }, + "404": { + "$ref": "#/components/responses/not_found" + }, + "422": { + "$ref": "#/components/responses/validation_failed" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "private-registries", + "subcategory": "organization-configurations" + } + } + }, + "/orgs/{org}/private-registries/public-key": { + "get": { + "summary": "Get private registries public key for an organization", + "description": "\nGets the org public key, which is needed to encrypt private registry secrets. You need to encrypt a secret before you can create or update secrets.\n\nOAuth tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", + "tags": [ + "private-registries" + ], + "operationId": "private-registries/get-org-public-key", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization" + }, + "parameters": [ + { + "$ref": "#/components/parameters/org" + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "key_id", + "key" + ], + "properties": { + "key_id": { + "description": "The identifier for the key.", + "example": "012345678912345678", + "type": "string" + }, + "key": { + "description": "The Base64 encoded public key.", + "example": "2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234", + "type": "string" + } + } + }, + "examples": { + "default": { + "$ref": "#/components/examples/private-registries-public-key" + } + } + } + }, + "headers": { + "Link": { + "$ref": "#/components/headers/link" + } + } + }, + "404": { + "$ref": "#/components/responses/not_found" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "private-registries", + "subcategory": "organization-configurations" + } + } + }, + "/orgs/{org}/private-registries/{secret_name}": { + "get": { + "summary": "Get a private registry for an organization", + "description": "\nGet the configuration of a single private registry defined for an organization, omitting its encrypted value.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", + "tags": [ + "private-registries" + ], + "operationId": "private-registries/get-org-private-registry", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#get-a-private-registry-for-an-organization" + }, + "parameters": [ + { + "$ref": "#/components/parameters/org" + }, + { + "$ref": "#/components/parameters/secret-name" + } + ], + "responses": { + "200": { + "description": "The specified private registry configuration for the organization", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/org-private-registry-configuration" + }, + "examples": { + "default": { + "$ref": "#/components/examples/org-private-registry-configuration" + } + } + } + } + }, + "404": { + "$ref": "#/components/responses/not_found" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "private-registries", + "subcategory": "organization-configurations" + } + }, + "patch": { + "summary": "Update a private registry for an organization", + "description": "\nUpdates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", + "tags": [ + "private-registries" + ], + "operationId": "private-registries/update-org-private-registry", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#update-a-private-registry-for-an-organization" + }, + "parameters": [ + { + "$ref": "#/components/parameters/org" + }, + { + "$ref": "#/components/parameters/secret-name" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "registry_type": { + "description": "The registry type.", + "type": "string", + "enum": [ + "maven_repository", + "nuget_feed", + "goproxy_server", + "npm_registry", + "rubygems_server", + "cargo_registry", + "composer_repository", + "docker_registry", + "git_source", + "helm_registry", + "hex_organization", + "hex_repository", + "pub_repository", + "python_index", + "terraform_registry" + ] + }, + "url": { + "description": "The URL of the private registry.", + "type": "string", + "format": "uri" + }, + "username": { + "description": "The username to use when authenticating with the private registry. This field should be omitted if the private registry does not require a username for authentication.", + "type": "string", + "nullable": true + }, + "replaces_base": { + "description": "Whether this private registry should replace the base registry (e.g., npmjs.org for npm, rubygems.org for rubygems). When set to `true`, Dependabot will only use this registry and will not fall back to the public registry. When set to `false` (default), Dependabot will use this registry for scoped packages but may fall back to the public registry for other packages.", + "type": "boolean", + "default": false + }, + "encrypted_value": { + "description": "The value for your secret, encrypted with [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages) using the public key retrieved from the [Get private registries public key for an organization](https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization) endpoint.", + "type": "string", + "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{4})$" + }, + "key_id": { + "description": "The ID of the key you used to encrypt the secret.", + "type": "string" + }, + "visibility": { + "description": "Which type of organization repositories have access to the private registry. `selected` means only the repositories specified by `selected_repository_ids` can access the private registry.", + "type": "string", + "enum": [ + "all", + "private", + "selected" + ] + }, + "selected_repository_ids": { + "description": "An array of repository IDs that can access the organization private registry. You can only provide a list of repository IDs when `visibility` is set to `selected`. This field should be omitted if `visibility` is set to `all` or `private`.", + "type": "array", + "items": { + "type": "integer" + } + }, + "auth_type": { + "description": "The authentication type for the private registry. This field cannot be changed after creation. If provided, it must match the existing `auth_type` of the configuration. To change the authentication type, delete and recreate the configuration.", "type": "string", "enum": [ "token", @@ -40234,7 +43772,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ] }, "tenant_id": { @@ -40270,7 +43809,7 @@ "type": "string" }, "audience": { - "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and required for `oidc_cloudsmith` auth types.", + "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and `oidc_gcp`, and required for `oidc_cloudsmith` auth types.", "type": "string" }, "identity_mapping_name": { @@ -40288,365 +43827,13 @@ "api_host": { "description": "The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default.", "type": "string" - } - }, - "required": [ - "registry_type", - "url", - "visibility" - ] - }, - "examples": { - "org-private-registry-with-private-visibility": { - "summary": "Example of a private registry configuration with private visibility", - "value": { - "registry_type": "maven_repository", - "url": "https://maven.pkg.github.com/organization/", - "username": "monalisa", - "replaces_base": true, - "encrypted_value": "c2VjcmV0", - "key_id": "012345678912345678", - "visibility": "private" - } - }, - "org-private-registry-with-selected-visibility": { - "summary": "Example of a private registry configuration with selected visibility", - "value": { - "registry_type": "maven_repository", - "url": "https://maven.pkg.github.com/organization/", - "username": "monalisa", - "encrypted_value": "c2VjcmV0", - "key_id": "012345678912345678", - "visibility": "selected", - "selected_repository_ids": [ - 1296269, - 1296280 - ] - } - }, - "org-private-registry-with-oidc-azure": { - "summary": "Example of an OIDC private registry configuration using Azure", - "value": { - "registry_type": "docker_registry", - "url": "https://myregistry.azurecr.io", - "auth_type": "oidc_azure", - "visibility": "all", - "tenant_id": "12345678-1234-1234-1234-123456789012", - "client_id": "abcdef01-2345-6789-abcd-ef0123456789" - } - }, - "org-private-registry-with-oidc-cloudsmith": { - "summary": "Example of an OIDC private registry configuration using Cloudsmith", - "value": { - "registry_type": "npm_registry", - "url": "https://npm.cloudsmith.io/my-org/my-repo/", - "auth_type": "oidc_cloudsmith", - "visibility": "all", - "namespace": "my-org", - "service_slug": "my-service-account", - "audience": "https://github.com/my-org" - } - } - } - } - } - }, - "responses": { - "201": { - "description": "The organization private registry configuration", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/org-private-registry-configuration-with-selected-repositories" - }, - "examples": { - "org-private-registry-with-selected-visibility": { - "$ref": "#/components/examples/org-private-registry-configuration" }, - "org-private-registry-with-private-visibility": { - "$ref": "#/components/examples/org-private-registry-configuration-with-selected-repositories" - } - } - } - } - }, - "404": { - "$ref": "#/components/responses/not_found" - }, - "422": { - "$ref": "#/components/responses/validation_failed" - } - }, - "x-github": { - "githubCloudOnly": false, - "enabledForGitHubApps": true, - "category": "private-registries", - "subcategory": "organization-configurations" - } - } - }, - "/orgs/{org}/private-registries/public-key": { - "get": { - "summary": "Get private registries public key for an organization", - "description": "\nGets the org public key, which is needed to encrypt private registry secrets. You need to encrypt a secret before you can create or update secrets.\n\nOAuth tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", - "tags": [ - "private-registries" - ], - "operationId": "private-registries/get-org-public-key", - "externalDocs": { - "description": "API method documentation", - "url": "https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization" - }, - "parameters": [ - { - "$ref": "#/components/parameters/org" - } - ], - "responses": { - "200": { - "description": "Response", - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "key_id", - "key" - ], - "properties": { - "key_id": { - "description": "The identifier for the key.", - "example": "012345678912345678", - "type": "string" - }, - "key": { - "description": "The Base64 encoded public key.", - "example": "2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234", - "type": "string" - } - } - }, - "examples": { - "default": { - "$ref": "#/components/examples/private-registries-public-key" - } - } - } - }, - "headers": { - "Link": { - "$ref": "#/components/headers/link" - } - } - }, - "404": { - "$ref": "#/components/responses/not_found" - } - }, - "x-github": { - "githubCloudOnly": false, - "enabledForGitHubApps": true, - "category": "private-registries", - "subcategory": "organization-configurations" - } - } - }, - "/orgs/{org}/private-registries/{secret_name}": { - "get": { - "summary": "Get a private registry for an organization", - "description": "\nGet the configuration of a single private registry defined for an organization, omitting its encrypted value.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", - "tags": [ - "private-registries" - ], - "operationId": "private-registries/get-org-private-registry", - "externalDocs": { - "description": "API method documentation", - "url": "https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#get-a-private-registry-for-an-organization" - }, - "parameters": [ - { - "$ref": "#/components/parameters/org" - }, - { - "$ref": "#/components/parameters/secret-name" - } - ], - "responses": { - "200": { - "description": "The specified private registry configuration for the organization", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/org-private-registry-configuration" - }, - "examples": { - "default": { - "$ref": "#/components/examples/org-private-registry-configuration" - } - } - } - } - }, - "404": { - "$ref": "#/components/responses/not_found" - } - }, - "x-github": { - "githubCloudOnly": false, - "enabledForGitHubApps": true, - "category": "private-registries", - "subcategory": "organization-configurations" - } - }, - "patch": { - "summary": "Update a private registry for an organization", - "description": "\nUpdates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", - "tags": [ - "private-registries" - ], - "operationId": "private-registries/update-org-private-registry", - "externalDocs": { - "description": "API method documentation", - "url": "https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#update-a-private-registry-for-an-organization" - }, - "parameters": [ - { - "$ref": "#/components/parameters/org" - }, - { - "$ref": "#/components/parameters/secret-name" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "registry_type": { - "description": "The registry type.", - "type": "string", - "enum": [ - "maven_repository", - "nuget_feed", - "goproxy_server", - "npm_registry", - "rubygems_server", - "cargo_registry", - "composer_repository", - "docker_registry", - "git_source", - "helm_registry", - "hex_organization", - "hex_repository", - "pub_repository", - "python_index", - "terraform_registry" - ] - }, - "url": { - "description": "The URL of the private registry.", - "type": "string", - "format": "uri" - }, - "username": { - "description": "The username to use when authenticating with the private registry. This field should be omitted if the private registry does not require a username for authentication.", - "type": "string", - "nullable": true - }, - "replaces_base": { - "description": "Whether this private registry should replace the base registry (e.g., npmjs.org for npm, rubygems.org for rubygems). When set to `true`, Dependabot will only use this registry and will not fall back to the public registry. When set to `false` (default), Dependabot will use this registry for scoped packages but may fall back to the public registry for other packages.", - "type": "boolean", - "default": false - }, - "encrypted_value": { - "description": "The value for your secret, encrypted with [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages) using the public key retrieved from the [Get private registries public key for an organization](https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization) endpoint.", - "type": "string", - "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{4})$" - }, - "key_id": { - "description": "The ID of the key you used to encrypt the secret.", - "type": "string" - }, - "visibility": { - "description": "Which type of organization repositories have access to the private registry. `selected` means only the repositories specified by `selected_repository_ids` can access the private registry.", - "type": "string", - "enum": [ - "all", - "private", - "selected" - ] - }, - "selected_repository_ids": { - "description": "An array of repository IDs that can access the organization private registry. You can only provide a list of repository IDs when `visibility` is set to `selected`. This field should be omitted if `visibility` is set to `all` or `private`.", - "type": "array", - "items": { - "type": "integer" - } - }, - "auth_type": { - "description": "The authentication type for the private registry. This field cannot be changed after creation. If provided, it must match the existing `auth_type` of the configuration. To change the authentication type, delete and recreate the configuration.", - "type": "string", - "enum": [ - "token", - "username_password", - "oidc_azure", - "oidc_aws", - "oidc_jfrog", - "oidc_cloudsmith" - ] - }, - "tenant_id": { - "description": "The tenant ID of the Azure AD application. Required when `auth_type` is `oidc_azure`.", - "type": "string" - }, - "client_id": { - "description": "The client ID of the Azure AD application. Required when `auth_type` is `oidc_azure`.", - "type": "string" - }, - "aws_region": { - "description": "The AWS region. Required when `auth_type` is `oidc_aws`.", - "type": "string" - }, - "account_id": { - "description": "The AWS account ID. Required when `auth_type` is `oidc_aws`.", - "type": "string" - }, - "role_name": { - "description": "The AWS IAM role name. Required when `auth_type` is `oidc_aws`.", + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). Required when `auth_type` is `oidc_gcp`.", "type": "string" }, - "domain": { - "description": "The CodeArtifact domain. Required when `auth_type` is `oidc_aws`.", - "type": "string" - }, - "domain_owner": { - "description": "The CodeArtifact domain owner (AWS account ID). Required when `auth_type` is `oidc_aws`.", - "type": "string" - }, - "jfrog_oidc_provider_name": { - "description": "The JFrog OIDC provider name. Required when `auth_type` is `oidc_jfrog`.", - "type": "string" - }, - "audience": { - "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and required for `oidc_cloudsmith` auth types.", - "type": "string" - }, - "identity_mapping_name": { - "description": "The JFrog identity mapping name. Optional for `oidc_jfrog` auth type.", - "type": "string" - }, - "namespace": { - "description": "The Cloudsmith organization namespace. Required when `auth_type` is `oidc_cloudsmith`.", - "type": "string" - }, - "service_slug": { - "description": "The Cloudsmith service account slug. Required when `auth_type` is `oidc_cloudsmith`.", - "type": "string" - }, - "api_host": { - "description": "The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default.", + "service_account": { + "description": "The GCP service account email to impersonate. Optional for `oidc_gcp` auth type. If omitted, the federated token is used directly (direct WIF).", "type": "string" } } @@ -47722,6 +50909,139 @@ } } }, + "/repos/{owner}/{repo}/actions/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a repository", + "description": "Lists the active concurrency groups for a repository.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository" + }, + "parameters": [ + { + "$ref": "#/components/parameters/owner" + }, + { + "$ref": "#/components/parameters/repo" + }, + { + "$ref": "#/components/parameters/per-page" + }, + { + "$ref": "#/components/parameters/pagination-after" + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/concurrency-group-list" + }, + "examples": { + "default": { + "$ref": "#/components/examples/concurrency-group-list" + } + } + } + }, + "headers": { + "Link": { + "$ref": "#/components/headers/link" + } + } + }, + "422": { + "$ref": "#/components/responses/validation_failed" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": { + "get": { + "summary": "Get a concurrency group for a repository", + "description": "Gets a specific concurrency group for a repository, including all instances in the group's queue.\nReturns 404 if the group is inactive or does not exist.\n\nOptionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items\nahead of the specified workflow run or job in the queue, plus the specified item itself\n(returned as the last element). This is useful for determining what is blocking a particular\nrun or job. Returns 422 if the specified run or job is not in this concurrency group.\n\nWhen using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow\nleases held on behalf of that run. Job-level leases within the run are not considered to\nblock the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow\nleases on the job's ancestor paths.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/get-concurrency-group-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository" + }, + "parameters": [ + { + "$ref": "#/components/parameters/owner" + }, + { + "$ref": "#/components/parameters/repo" + }, + { + "$ref": "#/components/parameters/concurrency-group-name" + }, + { + "name": "ahead_of_run", + "description": "Filter to items ahead of this workflow run ID in the queue, plus the run itself.\nMatches workflow-level concurrency and reusable-workflow leases held on behalf of\nthe run. Mutually exclusive with `ahead_of_job`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + }, + { + "name": "ahead_of_job", + "description": "Filter to items ahead of this job ID in the queue, plus the job itself.\nMatches job-level concurrency and reusable-workflow leases on the job's\nancestor paths. Mutually exclusive with `ahead_of_run`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/concurrency-group" + }, + "examples": { + "default": { + "$ref": "#/components/examples/concurrency-group" + } + } + } + } + }, + "404": { + "$ref": "#/components/responses/not_found" + }, + "422": { + "$ref": "#/components/responses/validation_failed" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/jobs/{job_id}": { "get": { "summary": "Get a job for a workflow run", @@ -50133,6 +53453,74 @@ } } }, + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a workflow run", + "description": "Lists all concurrency groups associated with a workflow run or its jobs.\n\nThe set of groups is derived from the run's configuration, so a group is\nincluded even when the run no longer has any items currently holding or\nwaiting in it. In that case the `group_members` array will be empty.\n`total_count` reflects the number of groups the run participates in by\nconfiguration, not the number with active items.\n\nThis differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`,\nwhich returns 404 when a group has no active items. That endpoint reports\nthe live state of a group repo-wide, while this endpoint reports the\ngroups associated with a specific run by configuration.\n\nResults are sorted by group name and support cursor-based pagination via\n`before` and `after`. The `after` cursor paginates forward only and does\nnot emit a `rel=\"prev\"` Link; use `before` to page backward from a\nforward page's `next` cursor.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-workflow-run", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run" + }, + "parameters": [ + { + "$ref": "#/components/parameters/owner" + }, + { + "$ref": "#/components/parameters/repo" + }, + { + "$ref": "#/components/parameters/run-id" + }, + { + "$ref": "#/components/parameters/per-page" + }, + { + "$ref": "#/components/parameters/pagination-before" + }, + { + "$ref": "#/components/parameters/pagination-after" + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/concurrency-group-run-list" + }, + "examples": { + "default": { + "$ref": "#/components/examples/concurrency-group-run-list" + } + } + } + }, + "headers": { + "Link": { + "$ref": "#/components/headers/link" + } + } + }, + "404": { + "$ref": "#/components/responses/not_found" + }, + "422": { + "$ref": "#/components/responses/validation_failed" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": { "post": { "summary": "Review custom deployment protection rules for a workflow run", @@ -146208,7 +149596,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ], "type": "string" }, @@ -146289,6 +149678,14 @@ "description": "The Cloudsmith API host.", "type": "string" }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`).", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. If omitted, the federated token is used directly (direct WIF).", + "type": "string" + }, "created_at": { "type": "string", "format": "date-time" @@ -146345,7 +149742,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ], "type": "string" }, @@ -146432,6 +149830,14 @@ "description": "The Cloudsmith API host.", "type": "string" }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`).", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. If omitted, the federated token is used directly (direct WIF).", + "type": "string" + }, "created_at": { "type": "string", "format": "date-time" @@ -150844,6 +154250,134 @@ "actions_caches" ] }, + "concurrency-group-list": { + "title": "Concurrency Group List", + "description": "A list of active concurrency groups for a repository.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer" + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "last_acquired_at" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "last_acquired_at": { + "type": "string", + "format": "date-time", + "nullable": true + } + } + } + } + } + }, + "concurrency-group": { + "title": "Concurrency Group", + "description": "A concurrency group with the workflow runs and jobs that are either currently holding\nor waiting for the concurrency group lease.", + "type": "object", + "required": [ + "group_name", + "group_url", + "total_count", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "total_count": { + "type": "integer" + }, + "group_members": { + "type": "array", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": "string", + "format": "uri", + "description": "API URL for the workflow run.", + "nullable": true + }, + "run_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the workflow run.", + "nullable": true + }, + "job_id": { + "type": "integer", + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_name": { + "type": "string", + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_url": { + "type": "string", + "format": "uri", + "description": "API URL for the job.", + "nullable": true + }, + "job_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the job.", + "nullable": true + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + }, "job": { "title": "Job", "description": "Information of a job execution in a workflow run", @@ -151579,6 +155113,119 @@ "comment" ] }, + "concurrency-group-run-list": { + "title": "Concurrency Group Run List", + "description": "A list of concurrency groups associated with a workflow run.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer", + "description": "The total number of concurrency groups this workflow run participates in,\nderived from the run's configuration. This count is not filtered by\nwhether the run currently holds or is waiting in each group, so it can\ninclude groups whose `group_members` array is empty (for example, when\nthe run has already released its lease in that group)." + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group. May return 404 if the group\nhas no active items at the time it is requested, since the\nget-by-name endpoint reports the live repo-wide state of a group\nwhile this endpoint lists groups associated with a run by\nconfiguration." + }, + "group_members": { + "type": "array", + "description": "Items belonging to this workflow run that are either currently holding or\nwaiting for the concurrency group lease. May be empty if the run no\nlonger has any active or queued items in this group.", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status", + "position", + "position_url" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": "string", + "format": "uri", + "description": "API URL for the workflow run.", + "nullable": true + }, + "run_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the workflow run.", + "nullable": true + }, + "position": { + "type": "integer", + "description": "Queue position. 0 means the item holds the concurrency lease (in_progress), 1 or higher means queued (pending)." + }, + "position_url": { + "type": "string", + "format": "uri", + "description": "API URL to get items ahead of this item in the concurrency group." + }, + "job_id": { + "type": "integer", + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease.", + "nullable": true + }, + "job_name": { + "type": "string", + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease.", + "nullable": true + }, + "job_url": { + "type": "string", + "format": "uri", + "description": "API URL for the job.", + "nullable": true + }, + "job_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the job.", + "nullable": true + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + } + } + } + }, "review-custom-gates-comment-required": { "type": "object", "properties": { @@ -328279,6 +331926,57 @@ ] } }, + "concurrency-group-list": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "last_acquired_at": "2026-01-15T16:14:23Z" + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "last_acquired_at": "2026-01-15T16:13:55Z" + } + ] + } + }, + "concurrency-group": { + "value": { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "total_count": 3, + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress" + }, + { + "run_id": 30433643, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433643", + "status": "pending" + }, + { + "run_id": 30433644, + "run_name": "Deploy hotfix", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644", + "job_id": 798245260, + "job_name": "deploy", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260", + "status": "pending" + } + ] + } + }, "job": { "value": { "id": 399444496, @@ -329067,6 +332765,47 @@ ] } }, + "concurrency-group-run-list": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress", + "position": 0, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642" + } + ] + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "pending", + "position": 2, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260", + "job_id": 798245260, + "job_name": "build", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260" + } + ] + } + ] + } + }, "pending-deployment-items": { "value": [ { @@ -350020,6 +353759,15 @@ "type": "integer" } }, + "concurrency-group-name": { + "name": "concurrency_group_name", + "description": "The name of the concurrency group.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, "job-id": { "name": "job_id", "description": "The unique identifier of the job.", diff --git a/descriptions/ghec/ghec.2022-11-28.yaml b/descriptions/ghec/ghec.2022-11-28.yaml index 62feb8e3b..ca7d96663 100644 --- a/descriptions/ghec/ghec.2022-11-28.yaml +++ b/descriptions/ghec/ghec.2022-11-28.yaml @@ -351,6 +351,2525 @@ paths: enabledForGitHubApps: true category: security-advisories subcategory: global-advisories + "/agents/repos/{owner}/{repo}/tasks": + get: + summary: List tasks for repository + description: | + > [!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](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks-for-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#list-tasks-for-repository + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: '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`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + - name: creator_id + in: query + schema: + type: integer + description: Filter tasks by creator user ID + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="prev" (when current page > 1), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; + rel="next", ; + rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + post: + summary: Start a task + description: | + > [!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](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/create-task-in-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#start-a-task + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + requestBody: + required: true + description: The task creation parameters, including the user's prompt and + optional agent settings. + content: + application/json: + schema: + type: object + required: + - prompt + properties: + prompt: + type: string + description: The user's prompt for the agent + model: + type: string + 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`' + create_pull_request: + type: boolean + description: Whether to create a PR. + default: false + base_ref: + type: string + description: Base ref for new branch/PR + examples: + default: + value: + prompt: Fix the login button on the homepage + base_ref: main + responses: + '201': + description: Task created successfully + content: + application/json: + schema: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + examples: + default: + value: + id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: queued + session_count: 1 + artifacts: [] + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T00:00:00Z' + '400': + description: Problems parsing JSON + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/repos/{owner}/{repo}/tasks/{task_id}": + get: + summary: Get a task by repo + description: | + > [!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](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-repo-and-id + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#get-a-task-by-repo + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks": + get: + summary: List tasks + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a list of tasks for the authenticated user + + **Fine-grained access tokens for "List tasks"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#list-tasks + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: '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`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; rel="next", + ; rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks/{task_id}": + get: + summary: Get a task by ID + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a task by ID with its associated sessions + + **Fine-grained access tokens for "Get a task by ID"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-id + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#get-a-task-by-id + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Problems parsing request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation "/app": get: summary: Get the authenticated app @@ -29174,7 +31693,7 @@ paths: description: |2- Creates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see "[Encrypting secrets for the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/encrypting-secrets-for-the-rest-api)." - For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted. + For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted. OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. tags: @@ -29267,7 +31786,332 @@ paths: auth_type: description: The authentication type for the private registry. Defaults to `token` if not specified. Use `oidc_azure`, `oidc_aws`, `oidc_jfrog`, - or `oidc_cloudsmith` for OIDC authentication. + `oidc_cloudsmith`, or `oidc_gcp` for OIDC authentication. + type: string + enum: + - token + - username_password + - oidc_azure + - oidc_aws + - oidc_jfrog + - oidc_cloudsmith + - oidc_gcp + tenant_id: + description: The tenant ID of the Azure AD application. Required + when `auth_type` is `oidc_azure`. + type: string + client_id: + description: The client ID of the Azure AD application. Required + when `auth_type` is `oidc_azure`. + type: string + aws_region: + description: The AWS region. Required when `auth_type` is `oidc_aws`. + type: string + account_id: + description: The AWS account ID. Required when `auth_type` is `oidc_aws`. + type: string + role_name: + description: The AWS IAM role name. Required when `auth_type` is + `oidc_aws`. + type: string + domain: + description: The CodeArtifact domain. Required when `auth_type` + is `oidc_aws`. + type: string + domain_owner: + description: The CodeArtifact domain owner (AWS account ID). Required + when `auth_type` is `oidc_aws`. + type: string + jfrog_oidc_provider_name: + description: The JFrog OIDC provider name. Required when `auth_type` + is `oidc_jfrog`. + type: string + audience: + description: The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, + and `oidc_gcp`, and required for `oidc_cloudsmith` auth types. + type: string + identity_mapping_name: + description: The JFrog identity mapping name. Optional for `oidc_jfrog` + auth type. + type: string + namespace: + description: The Cloudsmith organization namespace. Required when + `auth_type` is `oidc_cloudsmith`. + type: string + service_slug: + description: The Cloudsmith service account slug. Required when + `auth_type` is `oidc_cloudsmith`. + type: string + api_host: + description: The Cloudsmith API host. Optional for `oidc_cloudsmith` + auth type. If omitted, `api.cloudsmith.io` is used by default. + type: string + workload_identity_provider: + description: The full resource name of the GCP Workload Identity + Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + Required when `auth_type` is `oidc_gcp`. + type: string + service_account: + description: The GCP service account email to impersonate. Optional + for `oidc_gcp` auth type. If omitted, the federated token is used + directly (direct WIF). + type: string + required: + - registry_type + - url + - visibility + examples: + org-private-registry-with-private-visibility: + summary: Example of a private registry configuration with private + visibility + value: + registry_type: maven_repository + url: https://maven.pkg.github.com/organization/ + username: monalisa + replaces_base: true + encrypted_value: c2VjcmV0 + key_id: '012345678912345678' + visibility: private + org-private-registry-with-selected-visibility: + summary: Example of a private registry configuration with selected + visibility + value: + registry_type: maven_repository + url: https://maven.pkg.github.com/organization/ + username: monalisa + encrypted_value: c2VjcmV0 + key_id: '012345678912345678' + visibility: selected + selected_repository_ids: + - 1296269 + - 1296280 + org-private-registry-with-oidc-azure: + summary: Example of an OIDC private registry configuration using Azure + value: + registry_type: docker_registry + url: https://myregistry.azurecr.io + auth_type: oidc_azure + visibility: all + tenant_id: 12345678-1234-1234-1234-123456789012 + client_id: abcdef01-2345-6789-abcd-ef0123456789 + org-private-registry-with-oidc-cloudsmith: + summary: Example of an OIDC private registry configuration using Cloudsmith + value: + registry_type: npm_registry + url: https://npm.cloudsmith.io/my-org/my-repo/ + auth_type: oidc_cloudsmith + visibility: all + namespace: my-org + service_slug: my-service-account + audience: https://github.com/my-org + org-private-registry-with-oidc-gcp: + summary: Example of an OIDC private registry configuration using Google + Cloud Artifact Registry + value: + registry_type: docker_registry + url: https://us-docker.pkg.dev/my-project/my-repo + auth_type: oidc_gcp + visibility: all + workload_identity_provider: projects/123456789/locations/global/workloadIdentityPools/github-pool/providers/github-provider + service_account: dependabot@my-project.iam.gserviceaccount.com + responses: + '201': + description: The organization private registry configuration + content: + application/json: + schema: + "$ref": "#/components/schemas/org-private-registry-configuration-with-selected-repositories" + examples: + org-private-registry-with-selected-visibility: + "$ref": "#/components/examples/org-private-registry-configuration" + org-private-registry-with-private-visibility: + "$ref": "#/components/examples/org-private-registry-configuration-with-selected-repositories" + '404': + "$ref": "#/components/responses/not_found" + '422': + "$ref": "#/components/responses/validation_failed" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: private-registries + subcategory: organization-configurations + "/orgs/{org}/private-registries/public-key": + get: + summary: Get private registries public key for an organization + description: |2- + + Gets the org public key, which is needed to encrypt private registry secrets. You need to encrypt a secret before you can create or update secrets. + + OAuth tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. + tags: + - private-registries + operationId: private-registries/get-org-public-key + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization + parameters: + - "$ref": "#/components/parameters/org" + responses: + '200': + description: Response + content: + application/json: + schema: + type: object + required: + - key_id + - key + properties: + key_id: + description: The identifier for the key. + example: '012345678912345678' + type: string + key: + description: The Base64 encoded public key. + example: 2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234 + type: string + examples: + default: + "$ref": "#/components/examples/private-registries-public-key" + headers: + Link: + "$ref": "#/components/headers/link" + '404': + "$ref": "#/components/responses/not_found" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: private-registries + subcategory: organization-configurations + "/orgs/{org}/private-registries/{secret_name}": + get: + summary: Get a private registry for an organization + description: |2- + + Get the configuration of a single private registry defined for an organization, omitting its encrypted value. + + OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. + tags: + - private-registries + operationId: private-registries/get-org-private-registry + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#get-a-private-registry-for-an-organization + parameters: + - "$ref": "#/components/parameters/org" + - "$ref": "#/components/parameters/secret-name" + responses: + '200': + description: The specified private registry configuration for the organization + content: + application/json: + schema: + "$ref": "#/components/schemas/org-private-registry-configuration" + examples: + default: + "$ref": "#/components/examples/org-private-registry-configuration" + '404': + "$ref": "#/components/responses/not_found" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: private-registries + subcategory: organization-configurations + patch: + summary: Update a private registry for an organization + description: |2- + + Updates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see "[Encrypting secrets for the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/encrypting-secrets-for-the-rest-api)." + For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted. + + OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. + tags: + - private-registries + operationId: private-registries/update-org-private-registry + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#update-a-private-registry-for-an-organization + parameters: + - "$ref": "#/components/parameters/org" + - "$ref": "#/components/parameters/secret-name" + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + registry_type: + description: The registry type. + type: string + enum: + - maven_repository + - nuget_feed + - goproxy_server + - npm_registry + - rubygems_server + - cargo_registry + - composer_repository + - docker_registry + - git_source + - helm_registry + - hex_organization + - hex_repository + - pub_repository + - python_index + - terraform_registry + url: + description: The URL of the private registry. + type: string + format: uri + username: + description: The username to use when authenticating with the private + registry. This field should be omitted if the private registry + does not require a username for authentication. + type: string + nullable: true + replaces_base: + description: Whether this private registry should replace the base + registry (e.g., npmjs.org for npm, rubygems.org for rubygems). + When set to `true`, Dependabot will only use this registry and + will not fall back to the public registry. When set to `false` + (default), Dependabot will use this registry for scoped packages + but may fall back to the public registry for other packages. + type: boolean + default: false + encrypted_value: + description: The value for your secret, encrypted with [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages) + using the public key retrieved from the [Get private registries + public key for an organization](https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization) + endpoint. + type: string + pattern: "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{4})$" + key_id: + description: The ID of the key you used to encrypt the secret. + type: string + visibility: + description: Which type of organization repositories have access + to the private registry. `selected` means only the repositories + specified by `selected_repository_ids` can access the private + registry. + type: string + enum: + - all + - private + - selected + selected_repository_ids: + description: An array of repository IDs that can access the organization + private registry. You can only provide a list of repository IDs + when `visibility` is set to `selected`. This field should be omitted + if `visibility` is set to `all` or `private`. + type: array + items: + type: integer + auth_type: + description: The authentication type for the private registry. This + field cannot be changed after creation. If provided, it must match + the existing `auth_type` of the configuration. To change the authentication + type, delete and recreate the configuration. type: string enum: - token @@ -29276,6 +32120,7 @@ paths: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp tenant_id: description: The tenant ID of the Azure AD application. Required when `auth_type` is `oidc_azure`. @@ -29308,7 +32153,7 @@ paths: type: string audience: description: The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, - and required for `oidc_cloudsmith` auth types. + and `oidc_gcp`, and required for `oidc_cloudsmith` auth types. type: string identity_mapping_name: description: The JFrog identity mapping name. Optional for `oidc_jfrog` @@ -29326,309 +32171,15 @@ paths: description: The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default. type: string - required: - - registry_type - - url - - visibility - examples: - org-private-registry-with-private-visibility: - summary: Example of a private registry configuration with private - visibility - value: - registry_type: maven_repository - url: https://maven.pkg.github.com/organization/ - username: monalisa - replaces_base: true - encrypted_value: c2VjcmV0 - key_id: '012345678912345678' - visibility: private - org-private-registry-with-selected-visibility: - summary: Example of a private registry configuration with selected - visibility - value: - registry_type: maven_repository - url: https://maven.pkg.github.com/organization/ - username: monalisa - encrypted_value: c2VjcmV0 - key_id: '012345678912345678' - visibility: selected - selected_repository_ids: - - 1296269 - - 1296280 - org-private-registry-with-oidc-azure: - summary: Example of an OIDC private registry configuration using Azure - value: - registry_type: docker_registry - url: https://myregistry.azurecr.io - auth_type: oidc_azure - visibility: all - tenant_id: 12345678-1234-1234-1234-123456789012 - client_id: abcdef01-2345-6789-abcd-ef0123456789 - org-private-registry-with-oidc-cloudsmith: - summary: Example of an OIDC private registry configuration using Cloudsmith - value: - registry_type: npm_registry - url: https://npm.cloudsmith.io/my-org/my-repo/ - auth_type: oidc_cloudsmith - visibility: all - namespace: my-org - service_slug: my-service-account - audience: https://github.com/my-org - responses: - '201': - description: The organization private registry configuration - content: - application/json: - schema: - "$ref": "#/components/schemas/org-private-registry-configuration-with-selected-repositories" - examples: - org-private-registry-with-selected-visibility: - "$ref": "#/components/examples/org-private-registry-configuration" - org-private-registry-with-private-visibility: - "$ref": "#/components/examples/org-private-registry-configuration-with-selected-repositories" - '404': - "$ref": "#/components/responses/not_found" - '422': - "$ref": "#/components/responses/validation_failed" - x-github: - githubCloudOnly: false - enabledForGitHubApps: true - category: private-registries - subcategory: organization-configurations - "/orgs/{org}/private-registries/public-key": - get: - summary: Get private registries public key for an organization - description: |2- - - Gets the org public key, which is needed to encrypt private registry secrets. You need to encrypt a secret before you can create or update secrets. - - OAuth tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. - tags: - - private-registries - operationId: private-registries/get-org-public-key - externalDocs: - description: API method documentation - url: https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization - parameters: - - "$ref": "#/components/parameters/org" - responses: - '200': - description: Response - content: - application/json: - schema: - type: object - required: - - key_id - - key - properties: - key_id: - description: The identifier for the key. - example: '012345678912345678' - type: string - key: - description: The Base64 encoded public key. - example: 2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234 - type: string - examples: - default: - "$ref": "#/components/examples/private-registries-public-key" - headers: - Link: - "$ref": "#/components/headers/link" - '404': - "$ref": "#/components/responses/not_found" - x-github: - githubCloudOnly: false - enabledForGitHubApps: true - category: private-registries - subcategory: organization-configurations - "/orgs/{org}/private-registries/{secret_name}": - get: - summary: Get a private registry for an organization - description: |2- - - Get the configuration of a single private registry defined for an organization, omitting its encrypted value. - - OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. - tags: - - private-registries - operationId: private-registries/get-org-private-registry - externalDocs: - description: API method documentation - url: https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#get-a-private-registry-for-an-organization - parameters: - - "$ref": "#/components/parameters/org" - - "$ref": "#/components/parameters/secret-name" - responses: - '200': - description: The specified private registry configuration for the organization - content: - application/json: - schema: - "$ref": "#/components/schemas/org-private-registry-configuration" - examples: - default: - "$ref": "#/components/examples/org-private-registry-configuration" - '404': - "$ref": "#/components/responses/not_found" - x-github: - githubCloudOnly: false - enabledForGitHubApps: true - category: private-registries - subcategory: organization-configurations - patch: - summary: Update a private registry for an organization - description: |2- - - Updates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see "[Encrypting secrets for the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/encrypting-secrets-for-the-rest-api)." - For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted. - - OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. - tags: - - private-registries - operationId: private-registries/update-org-private-registry - externalDocs: - description: API method documentation - url: https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#update-a-private-registry-for-an-organization - parameters: - - "$ref": "#/components/parameters/org" - - "$ref": "#/components/parameters/secret-name" - requestBody: - required: true - content: - application/json: - schema: - type: object - properties: - registry_type: - description: The registry type. - type: string - enum: - - maven_repository - - nuget_feed - - goproxy_server - - npm_registry - - rubygems_server - - cargo_registry - - composer_repository - - docker_registry - - git_source - - helm_registry - - hex_organization - - hex_repository - - pub_repository - - python_index - - terraform_registry - url: - description: The URL of the private registry. - type: string - format: uri - username: - description: The username to use when authenticating with the private - registry. This field should be omitted if the private registry - does not require a username for authentication. - type: string - nullable: true - replaces_base: - description: Whether this private registry should replace the base - registry (e.g., npmjs.org for npm, rubygems.org for rubygems). - When set to `true`, Dependabot will only use this registry and - will not fall back to the public registry. When set to `false` - (default), Dependabot will use this registry for scoped packages - but may fall back to the public registry for other packages. - type: boolean - default: false - encrypted_value: - description: The value for your secret, encrypted with [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages) - using the public key retrieved from the [Get private registries - public key for an organization](https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization) - endpoint. - type: string - pattern: "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{4})$" - key_id: - description: The ID of the key you used to encrypt the secret. - type: string - visibility: - description: Which type of organization repositories have access - to the private registry. `selected` means only the repositories - specified by `selected_repository_ids` can access the private - registry. - type: string - enum: - - all - - private - - selected - selected_repository_ids: - description: An array of repository IDs that can access the organization - private registry. You can only provide a list of repository IDs - when `visibility` is set to `selected`. This field should be omitted - if `visibility` is set to `all` or `private`. - type: array - items: - type: integer - auth_type: - description: The authentication type for the private registry. This - field cannot be changed after creation. If provided, it must match - the existing `auth_type` of the configuration. To change the authentication - type, delete and recreate the configuration. - type: string - enum: - - token - - username_password - - oidc_azure - - oidc_aws - - oidc_jfrog - - oidc_cloudsmith - tenant_id: - description: The tenant ID of the Azure AD application. Required - when `auth_type` is `oidc_azure`. - type: string - client_id: - description: The client ID of the Azure AD application. Required - when `auth_type` is `oidc_azure`. - type: string - aws_region: - description: The AWS region. Required when `auth_type` is `oidc_aws`. - type: string - account_id: - description: The AWS account ID. Required when `auth_type` is `oidc_aws`. - type: string - role_name: - description: The AWS IAM role name. Required when `auth_type` is - `oidc_aws`. - type: string - domain: - description: The CodeArtifact domain. Required when `auth_type` - is `oidc_aws`. - type: string - domain_owner: - description: The CodeArtifact domain owner (AWS account ID). Required - when `auth_type` is `oidc_aws`. - type: string - jfrog_oidc_provider_name: - description: The JFrog OIDC provider name. Required when `auth_type` - is `oidc_jfrog`. - type: string - audience: - description: The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, - and required for `oidc_cloudsmith` auth types. + workload_identity_provider: + description: The full resource name of the GCP Workload Identity + Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + Required when `auth_type` is `oidc_gcp`. type: string - identity_mapping_name: - description: The JFrog identity mapping name. Optional for `oidc_jfrog` - auth type. - type: string - namespace: - description: The Cloudsmith organization namespace. Required when - `auth_type` is `oidc_cloudsmith`. - type: string - service_slug: - description: The Cloudsmith service account slug. Required when - `auth_type` is `oidc_cloudsmith`. - type: string - api_host: - description: The Cloudsmith API host. Optional for `oidc_cloudsmith` - auth type. If omitted, `api.cloudsmith.io` is used by default. + service_account: + description: The GCP service account email to impersonate. Optional + for `oidc_gcp` auth type. If omitted, the federated token is used + directly (direct WIF). type: string examples: secret-based-update: @@ -34747,6 +37298,111 @@ paths: enabledForGitHubApps: true category: actions subcategory: cache + "/repos/{owner}/{repo}/actions/concurrency_groups": + get: + summary: List concurrency groups for a repository + description: |- + Lists the active concurrency groups for a repository. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository + parameters: + - "$ref": "#/components/parameters/owner" + - "$ref": "#/components/parameters/repo" + - "$ref": "#/components/parameters/per-page" + - "$ref": "#/components/parameters/pagination-after" + responses: + '200': + description: Response + content: + application/json: + schema: + "$ref": "#/components/schemas/concurrency-group-list" + examples: + default: + "$ref": "#/components/examples/concurrency-group-list" + headers: + Link: + "$ref": "#/components/headers/link" + '422': + "$ref": "#/components/responses/validation_failed" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": + get: + summary: Get a concurrency group for a repository + description: |- + Gets a specific concurrency group for a repository, including all instances in the group's queue. + Returns 404 if the group is inactive or does not exist. + + Optionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items + ahead of the specified workflow run or job in the queue, plus the specified item itself + (returned as the last element). This is useful for determining what is blocking a particular + run or job. Returns 422 if the specified run or job is not in this concurrency group. + + When using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow + leases held on behalf of that run. Job-level leases within the run are not considered to + block the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow + leases on the job's ancestor paths. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/get-concurrency-group-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository + parameters: + - "$ref": "#/components/parameters/owner" + - "$ref": "#/components/parameters/repo" + - "$ref": "#/components/parameters/concurrency-group-name" + - name: ahead_of_run + description: |- + Filter to items ahead of this workflow run ID in the queue, plus the run itself. + Matches workflow-level concurrency and reusable-workflow leases held on behalf of + the run. Mutually exclusive with `ahead_of_job`. + in: query + required: false + schema: + type: integer + minimum: 1 + - name: ahead_of_job + description: |- + Filter to items ahead of this job ID in the queue, plus the job itself. + Matches job-level concurrency and reusable-workflow leases on the job's + ancestor paths. Mutually exclusive with `ahead_of_run`. + in: query + required: false + schema: + type: integer + minimum: 1 + responses: + '200': + description: Response + content: + application/json: + schema: + "$ref": "#/components/schemas/concurrency-group" + examples: + default: + "$ref": "#/components/examples/concurrency-group" + '404': + "$ref": "#/components/responses/not_found" + '422': + "$ref": "#/components/responses/validation_failed" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/jobs/{job_id}": get: summary: Get a job for a workflow run @@ -36456,6 +39112,64 @@ paths: enabledForGitHubApps: true category: actions subcategory: workflow-runs + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": + get: + summary: List concurrency groups for a workflow run + description: |- + Lists all concurrency groups associated with a workflow run or its jobs. + + The set of groups is derived from the run's configuration, so a group is + included even when the run no longer has any items currently holding or + waiting in it. In that case the `group_members` array will be empty. + `total_count` reflects the number of groups the run participates in by + configuration, not the number with active items. + + This differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`, + which returns 404 when a group has no active items. That endpoint reports + the live state of a group repo-wide, while this endpoint reports the + groups associated with a specific run by configuration. + + Results are sorted by group name and support cursor-based pagination via + `before` and `after`. The `after` cursor paginates forward only and does + not emit a `rel="prev"` Link; use `before` to page backward from a + forward page's `next` cursor. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-workflow-run + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run + parameters: + - "$ref": "#/components/parameters/owner" + - "$ref": "#/components/parameters/repo" + - "$ref": "#/components/parameters/run-id" + - "$ref": "#/components/parameters/per-page" + - "$ref": "#/components/parameters/pagination-before" + - "$ref": "#/components/parameters/pagination-after" + responses: + '200': + description: Response + content: + application/json: + schema: + "$ref": "#/components/schemas/concurrency-group-run-list" + examples: + default: + "$ref": "#/components/examples/concurrency-group-run-list" + headers: + Link: + "$ref": "#/components/headers/link" + '404': + "$ref": "#/components/responses/not_found" + '422': + "$ref": "#/components/responses/validation_failed" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": post: summary: Review custom deployment protection rules for a workflow run @@ -107077,6 +109791,7 @@ components: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp type: string url: description: The URL of the private registry. @@ -107142,6 +109857,14 @@ components: api_host: description: The Cloudsmith API host. type: string + workload_identity_provider: + description: The full resource name of the GCP Workload Identity Provider + (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + type: string + service_account: + description: The GCP service account email to impersonate. If omitted, the + federated token is used directly (direct WIF). + type: string created_at: type: string format: date-time @@ -107191,6 +109914,7 @@ components: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp type: string url: description: The URL of the private registry. @@ -107262,6 +109986,14 @@ components: api_host: description: The Cloudsmith API host. type: string + workload_identity_provider: + description: The full resource name of the GCP Workload Identity Provider + (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + type: string + service_account: + description: The GCP service account email to impersonate. If omitted, the + federated token is used directly (direct WIF). + type: string created_at: type: string format: date-time @@ -110730,6 +113462,107 @@ components: required: - total_count - actions_caches + concurrency-group-list: + title: Concurrency Group List + description: A list of active concurrency groups for a repository. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - last_acquired_at + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + last_acquired_at: + type: string + format: date-time + nullable: true + concurrency-group: + title: Concurrency Group + description: |- + A concurrency group with the workflow runs and jobs that are either currently holding + or waiting for the concurrency group lease. + type: object + required: + - group_name + - group_url + - total_count + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + total_count: + type: integer + group_members: + type: array + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: string + format: uri + description: API URL for the workflow run. + nullable: true + run_html_url: + type: string + format: uri + description: Web URL for the workflow run. + nullable: true + job_id: + type: integer + description: The ID of the job, when the item represents a job-level + or reusable-workflow-level lease. + job_name: + type: string + description: The display name of the job, when the item represents + a job-level or reusable-workflow-level lease. + job_url: + type: string + format: uri + description: API URL for the job. + nullable: true + job_html_url: + type: string + format: uri + description: Web URL for the job. + nullable: true + status: + type: string + enum: + - in_progress + - pending job: title: Job description: Information of a job execution in a workflow run @@ -111337,6 +114170,110 @@ components: - state - user - comment + concurrency-group-run-list: + title: Concurrency Group Run List + description: A list of concurrency groups associated with a workflow run. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + description: |- + The total number of concurrency groups this workflow run participates in, + derived from the run's configuration. This count is not filtered by + whether the run currently holds or is waiting in each group, so it can + include groups whose `group_members` array is empty (for example, when + the run has already released its lease in that group). + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: |- + API URL for this concurrency group. May return 404 if the group + has no active items at the time it is requested, since the + get-by-name endpoint reports the live repo-wide state of a group + while this endpoint lists groups associated with a run by + configuration. + group_members: + type: array + description: |- + Items belonging to this workflow run that are either currently holding or + waiting for the concurrency group lease. May be empty if the run no + longer has any active or queued items in this group. + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + - position + - position_url + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: string + format: uri + description: API URL for the workflow run. + nullable: true + run_html_url: + type: string + format: uri + description: Web URL for the workflow run. + nullable: true + position: + type: integer + description: Queue position. 0 means the item holds the concurrency + lease (in_progress), 1 or higher means queued (pending). + position_url: + type: string + format: uri + description: API URL to get items ahead of this item in the + concurrency group. + job_id: + type: integer + description: The ID of the job, when the item represents a job-level + or reusable-workflow-level lease. + nullable: true + job_name: + type: string + description: The display name of the job, when the item represents + a job-level or reusable-workflow-level lease. + nullable: true + job_url: + type: string + format: uri + description: API URL for the job. + nullable: true + job_html_url: + type: string + format: uri + description: Web URL for the job. + nullable: true + status: + type: string + enum: + - in_progress + - pending review-custom-gates-comment-required: type: object properties: @@ -246161,6 +249098,41 @@ components: last_accessed_at: '2019-01-24T22:45:36.000Z' created_at: '2019-01-24T22:45:36.000Z' size_in_bytes: 1024 + concurrency-group-list: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + last_acquired_at: '2026-01-15T16:14:23Z' + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + last_acquired_at: '2026-01-15T16:13:55Z' + concurrency-group: + value: + group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + total_count: 3 + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + - run_id: 30433643 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433643 + status: pending + - run_id: 30433644 + run_name: Deploy hotfix + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644 + job_id: 798245260 + job_name: deploy + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260 + status: pending job: value: id: 399444496 @@ -246837,6 +249809,34 @@ components: runner_group_name: my runner group workflow_name: CI head_branch: main + concurrency-group-run-list: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + position: 0 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642 + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: pending + position: 2 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260 + job_id: 798245260 + job_name: build + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260 pending-deployment-items: value: - environment: @@ -264904,6 +267904,13 @@ components: required: true schema: type: integer + concurrency-group-name: + name: concurrency_group_name + description: The name of the concurrency group. + in: path + required: true + schema: + type: string job-id: name: job_id description: The unique identifier of the job. diff --git a/descriptions/ghec/ghec.2026-03-10.json b/descriptions/ghec/ghec.2026-03-10.json index 14befb4e7..e390987fc 100644 --- a/descriptions/ghec/ghec.2026-03-10.json +++ b/descriptions/ghec/ghec.2026-03-10.json @@ -546,6 +546,3164 @@ } } }, + "/agents/repos/{owner}/{repo}/tasks": { + "get": { + "summary": "List tasks for repository", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for a specific repository\n\n**Fine-grained access tokens for \"List tasks for repository\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks-for-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#list-tasks-for-repository" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "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`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + }, + { + "name": "creator_id", + "in": "query", + "schema": { + "type": "integer" + }, + "description": "Filter tasks by creator user ID" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"prev\" (when current page > 1),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + }, + "post": { + "summary": "Start a task", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nStarts a new Copilot cloud agent task for a repository.\n\nThis endpoint is only available to users with a Copilot Business or Copilot Enterprise subscription.\n\n**Fine-grained access tokens for \"Start a task\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read and write)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/create-task-in-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#start-a-task" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + } + ], + "requestBody": { + "required": true, + "description": "The task creation parameters, including the user's prompt and optional agent settings.", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "prompt" + ], + "properties": { + "prompt": { + "type": "string", + "description": "The user's prompt for the agent" + }, + "model": { + "type": "string", + "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`" + }, + "create_pull_request": { + "type": "boolean", + "description": "Whether to create a PR.", + "default": false + }, + "base_ref": { + "type": "string", + "description": "Base ref for new branch/PR" + } + } + }, + "examples": { + "default": { + "value": { + "prompt": "Fix the login button on the homepage", + "base_ref": "main" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Task created successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "examples": { + "default": { + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "queued", + "session_count": 1, + "artifacts": [], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T00:00:00Z" + } + } + } + } + } + }, + "400": { + "description": "Problems parsing JSON", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/repos/{owner}/{repo}/tasks/{task_id}": { + "get": { + "summary": "Get a task by repo", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID scoped to an owner/repo path\n\n**Fine-grained access tokens for \"Get a task by repo\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-repo-and-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#get-a-task-by-repo" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks": { + "get": { + "summary": "List tasks", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for the authenticated user\n\n**Fine-grained access tokens for \"List tasks\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#list-tasks" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "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`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks/{task_id}": { + "get": { + "summary": "Get a task by ID", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID with its associated sessions\n\n**Fine-grained access tokens for \"Get a task by ID\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#get-a-task-by-id" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Problems parsing request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, "/app": { "get": { "summary": "Get the authenticated app", @@ -40084,7 +43242,7 @@ }, "post": { "summary": "Create a private registry for an organization", - "description": "\nCreates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", + "description": "\nCreates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", "tags": [ "private-registries" ], @@ -40167,7 +43325,387 @@ } }, "auth_type": { - "description": "The authentication type for the private registry. Defaults to `token` if not specified. Use `oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith` for OIDC authentication.", + "description": "The authentication type for the private registry. Defaults to `token` if not specified. Use `oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp` for OIDC authentication.", + "type": "string", + "enum": [ + "token", + "username_password", + "oidc_azure", + "oidc_aws", + "oidc_jfrog", + "oidc_cloudsmith", + "oidc_gcp" + ] + }, + "tenant_id": { + "description": "The tenant ID of the Azure AD application. Required when `auth_type` is `oidc_azure`.", + "type": "string" + }, + "client_id": { + "description": "The client ID of the Azure AD application. Required when `auth_type` is `oidc_azure`.", + "type": "string" + }, + "aws_region": { + "description": "The AWS region. Required when `auth_type` is `oidc_aws`.", + "type": "string" + }, + "account_id": { + "description": "The AWS account ID. Required when `auth_type` is `oidc_aws`.", + "type": "string" + }, + "role_name": { + "description": "The AWS IAM role name. Required when `auth_type` is `oidc_aws`.", + "type": "string" + }, + "domain": { + "description": "The CodeArtifact domain. Required when `auth_type` is `oidc_aws`.", + "type": "string" + }, + "domain_owner": { + "description": "The CodeArtifact domain owner (AWS account ID). Required when `auth_type` is `oidc_aws`.", + "type": "string" + }, + "jfrog_oidc_provider_name": { + "description": "The JFrog OIDC provider name. Required when `auth_type` is `oidc_jfrog`.", + "type": "string" + }, + "audience": { + "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and `oidc_gcp`, and required for `oidc_cloudsmith` auth types.", + "type": "string" + }, + "identity_mapping_name": { + "description": "The JFrog identity mapping name. Optional for `oidc_jfrog` auth type.", + "type": "string" + }, + "namespace": { + "description": "The Cloudsmith organization namespace. Required when `auth_type` is `oidc_cloudsmith`.", + "type": "string" + }, + "service_slug": { + "description": "The Cloudsmith service account slug. Required when `auth_type` is `oidc_cloudsmith`.", + "type": "string" + }, + "api_host": { + "description": "The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default.", + "type": "string" + }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). Required when `auth_type` is `oidc_gcp`.", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. Optional for `oidc_gcp` auth type. If omitted, the federated token is used directly (direct WIF).", + "type": "string" + } + }, + "required": [ + "registry_type", + "url", + "visibility" + ] + }, + "examples": { + "org-private-registry-with-private-visibility": { + "summary": "Example of a private registry configuration with private visibility", + "value": { + "registry_type": "maven_repository", + "url": "https://maven.pkg.github.com/organization/", + "username": "monalisa", + "replaces_base": true, + "encrypted_value": "c2VjcmV0", + "key_id": "012345678912345678", + "visibility": "private" + } + }, + "org-private-registry-with-selected-visibility": { + "summary": "Example of a private registry configuration with selected visibility", + "value": { + "registry_type": "maven_repository", + "url": "https://maven.pkg.github.com/organization/", + "username": "monalisa", + "encrypted_value": "c2VjcmV0", + "key_id": "012345678912345678", + "visibility": "selected", + "selected_repository_ids": [ + 1296269, + 1296280 + ] + } + }, + "org-private-registry-with-oidc-azure": { + "summary": "Example of an OIDC private registry configuration using Azure", + "value": { + "registry_type": "docker_registry", + "url": "https://myregistry.azurecr.io", + "auth_type": "oidc_azure", + "visibility": "all", + "tenant_id": "12345678-1234-1234-1234-123456789012", + "client_id": "abcdef01-2345-6789-abcd-ef0123456789" + } + }, + "org-private-registry-with-oidc-cloudsmith": { + "summary": "Example of an OIDC private registry configuration using Cloudsmith", + "value": { + "registry_type": "npm_registry", + "url": "https://npm.cloudsmith.io/my-org/my-repo/", + "auth_type": "oidc_cloudsmith", + "visibility": "all", + "namespace": "my-org", + "service_slug": "my-service-account", + "audience": "https://github.com/my-org" + } + }, + "org-private-registry-with-oidc-gcp": { + "summary": "Example of an OIDC private registry configuration using Google Cloud Artifact Registry", + "value": { + "registry_type": "docker_registry", + "url": "https://us-docker.pkg.dev/my-project/my-repo", + "auth_type": "oidc_gcp", + "visibility": "all", + "workload_identity_provider": "projects/123456789/locations/global/workloadIdentityPools/github-pool/providers/github-provider", + "service_account": "dependabot@my-project.iam.gserviceaccount.com" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "The organization private registry configuration", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/org-private-registry-configuration-with-selected-repositories" + }, + "examples": { + "org-private-registry-with-selected-visibility": { + "$ref": "#/components/examples/org-private-registry-configuration" + }, + "org-private-registry-with-private-visibility": { + "$ref": "#/components/examples/org-private-registry-configuration-with-selected-repositories" + } + } + } + } + }, + "404": { + "$ref": "#/components/responses/not_found" + }, + "422": { + "$ref": "#/components/responses/validation_failed" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "private-registries", + "subcategory": "organization-configurations" + } + } + }, + "/orgs/{org}/private-registries/public-key": { + "get": { + "summary": "Get private registries public key for an organization", + "description": "\nGets the org public key, which is needed to encrypt private registry secrets. You need to encrypt a secret before you can create or update secrets.\n\nOAuth tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", + "tags": [ + "private-registries" + ], + "operationId": "private-registries/get-org-public-key", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization" + }, + "parameters": [ + { + "$ref": "#/components/parameters/org" + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "key_id", + "key" + ], + "properties": { + "key_id": { + "description": "The identifier for the key.", + "example": "012345678912345678", + "type": "string" + }, + "key": { + "description": "The Base64 encoded public key.", + "example": "2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234", + "type": "string" + } + } + }, + "examples": { + "default": { + "$ref": "#/components/examples/private-registries-public-key" + } + } + } + }, + "headers": { + "Link": { + "$ref": "#/components/headers/link" + } + } + }, + "404": { + "$ref": "#/components/responses/not_found" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "private-registries", + "subcategory": "organization-configurations" + } + } + }, + "/orgs/{org}/private-registries/{secret_name}": { + "get": { + "summary": "Get a private registry for an organization", + "description": "\nGet the configuration of a single private registry defined for an organization, omitting its encrypted value.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", + "tags": [ + "private-registries" + ], + "operationId": "private-registries/get-org-private-registry", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#get-a-private-registry-for-an-organization" + }, + "parameters": [ + { + "$ref": "#/components/parameters/org" + }, + { + "$ref": "#/components/parameters/secret-name" + } + ], + "responses": { + "200": { + "description": "The specified private registry configuration for the organization", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/org-private-registry-configuration" + }, + "examples": { + "default": { + "$ref": "#/components/examples/org-private-registry-configuration" + } + } + } + } + }, + "404": { + "$ref": "#/components/responses/not_found" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "private-registries", + "subcategory": "organization-configurations" + } + }, + "patch": { + "summary": "Update a private registry for an organization", + "description": "\nUpdates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", + "tags": [ + "private-registries" + ], + "operationId": "private-registries/update-org-private-registry", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#update-a-private-registry-for-an-organization" + }, + "parameters": [ + { + "$ref": "#/components/parameters/org" + }, + { + "$ref": "#/components/parameters/secret-name" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "registry_type": { + "description": "The registry type.", + "type": "string", + "enum": [ + "maven_repository", + "nuget_feed", + "goproxy_server", + "npm_registry", + "rubygems_server", + "cargo_registry", + "composer_repository", + "docker_registry", + "git_source", + "helm_registry", + "hex_organization", + "hex_repository", + "pub_repository", + "python_index", + "terraform_registry" + ] + }, + "url": { + "description": "The URL of the private registry.", + "type": "string", + "format": "uri" + }, + "username": { + "description": "The username to use when authenticating with the private registry. This field should be omitted if the private registry does not require a username for authentication.", + "type": "string", + "nullable": true + }, + "replaces_base": { + "description": "Whether this private registry should replace the base registry (e.g., npmjs.org for npm, rubygems.org for rubygems). When set to `true`, Dependabot will only use this registry and will not fall back to the public registry. When set to `false` (default), Dependabot will use this registry for scoped packages but may fall back to the public registry for other packages.", + "type": "boolean", + "default": false + }, + "encrypted_value": { + "description": "The value for your secret, encrypted with [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages) using the public key retrieved from the [Get private registries public key for an organization](https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization) endpoint.", + "type": "string", + "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{4})$" + }, + "key_id": { + "description": "The ID of the key you used to encrypt the secret.", + "type": "string" + }, + "visibility": { + "description": "Which type of organization repositories have access to the private registry. `selected` means only the repositories specified by `selected_repository_ids` can access the private registry.", + "type": "string", + "enum": [ + "all", + "private", + "selected" + ] + }, + "selected_repository_ids": { + "description": "An array of repository IDs that can access the organization private registry. You can only provide a list of repository IDs when `visibility` is set to `selected`. This field should be omitted if `visibility` is set to `all` or `private`.", + "type": "array", + "items": { + "type": "integer" + } + }, + "auth_type": { + "description": "The authentication type for the private registry. This field cannot be changed after creation. If provided, it must match the existing `auth_type` of the configuration. To change the authentication type, delete and recreate the configuration.", "type": "string", "enum": [ "token", @@ -40175,7 +43713,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ] }, "tenant_id": { @@ -40211,7 +43750,7 @@ "type": "string" }, "audience": { - "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and required for `oidc_cloudsmith` auth types.", + "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and `oidc_gcp`, and required for `oidc_cloudsmith` auth types.", "type": "string" }, "identity_mapping_name": { @@ -40229,365 +43768,13 @@ "api_host": { "description": "The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default.", "type": "string" - } - }, - "required": [ - "registry_type", - "url", - "visibility" - ] - }, - "examples": { - "org-private-registry-with-private-visibility": { - "summary": "Example of a private registry configuration with private visibility", - "value": { - "registry_type": "maven_repository", - "url": "https://maven.pkg.github.com/organization/", - "username": "monalisa", - "replaces_base": true, - "encrypted_value": "c2VjcmV0", - "key_id": "012345678912345678", - "visibility": "private" - } - }, - "org-private-registry-with-selected-visibility": { - "summary": "Example of a private registry configuration with selected visibility", - "value": { - "registry_type": "maven_repository", - "url": "https://maven.pkg.github.com/organization/", - "username": "monalisa", - "encrypted_value": "c2VjcmV0", - "key_id": "012345678912345678", - "visibility": "selected", - "selected_repository_ids": [ - 1296269, - 1296280 - ] - } - }, - "org-private-registry-with-oidc-azure": { - "summary": "Example of an OIDC private registry configuration using Azure", - "value": { - "registry_type": "docker_registry", - "url": "https://myregistry.azurecr.io", - "auth_type": "oidc_azure", - "visibility": "all", - "tenant_id": "12345678-1234-1234-1234-123456789012", - "client_id": "abcdef01-2345-6789-abcd-ef0123456789" - } - }, - "org-private-registry-with-oidc-cloudsmith": { - "summary": "Example of an OIDC private registry configuration using Cloudsmith", - "value": { - "registry_type": "npm_registry", - "url": "https://npm.cloudsmith.io/my-org/my-repo/", - "auth_type": "oidc_cloudsmith", - "visibility": "all", - "namespace": "my-org", - "service_slug": "my-service-account", - "audience": "https://github.com/my-org" - } - } - } - } - } - }, - "responses": { - "201": { - "description": "The organization private registry configuration", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/org-private-registry-configuration-with-selected-repositories" - }, - "examples": { - "org-private-registry-with-selected-visibility": { - "$ref": "#/components/examples/org-private-registry-configuration" }, - "org-private-registry-with-private-visibility": { - "$ref": "#/components/examples/org-private-registry-configuration-with-selected-repositories" - } - } - } - } - }, - "404": { - "$ref": "#/components/responses/not_found" - }, - "422": { - "$ref": "#/components/responses/validation_failed" - } - }, - "x-github": { - "githubCloudOnly": false, - "enabledForGitHubApps": true, - "category": "private-registries", - "subcategory": "organization-configurations" - } - } - }, - "/orgs/{org}/private-registries/public-key": { - "get": { - "summary": "Get private registries public key for an organization", - "description": "\nGets the org public key, which is needed to encrypt private registry secrets. You need to encrypt a secret before you can create or update secrets.\n\nOAuth tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", - "tags": [ - "private-registries" - ], - "operationId": "private-registries/get-org-public-key", - "externalDocs": { - "description": "API method documentation", - "url": "https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization" - }, - "parameters": [ - { - "$ref": "#/components/parameters/org" - } - ], - "responses": { - "200": { - "description": "Response", - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "key_id", - "key" - ], - "properties": { - "key_id": { - "description": "The identifier for the key.", - "example": "012345678912345678", - "type": "string" - }, - "key": { - "description": "The Base64 encoded public key.", - "example": "2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234", - "type": "string" - } - } - }, - "examples": { - "default": { - "$ref": "#/components/examples/private-registries-public-key" - } - } - } - }, - "headers": { - "Link": { - "$ref": "#/components/headers/link" - } - } - }, - "404": { - "$ref": "#/components/responses/not_found" - } - }, - "x-github": { - "githubCloudOnly": false, - "enabledForGitHubApps": true, - "category": "private-registries", - "subcategory": "organization-configurations" - } - } - }, - "/orgs/{org}/private-registries/{secret_name}": { - "get": { - "summary": "Get a private registry for an organization", - "description": "\nGet the configuration of a single private registry defined for an organization, omitting its encrypted value.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", - "tags": [ - "private-registries" - ], - "operationId": "private-registries/get-org-private-registry", - "externalDocs": { - "description": "API method documentation", - "url": "https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#get-a-private-registry-for-an-organization" - }, - "parameters": [ - { - "$ref": "#/components/parameters/org" - }, - { - "$ref": "#/components/parameters/secret-name" - } - ], - "responses": { - "200": { - "description": "The specified private registry configuration for the organization", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/org-private-registry-configuration" - }, - "examples": { - "default": { - "$ref": "#/components/examples/org-private-registry-configuration" - } - } - } - } - }, - "404": { - "$ref": "#/components/responses/not_found" - } - }, - "x-github": { - "githubCloudOnly": false, - "enabledForGitHubApps": true, - "category": "private-registries", - "subcategory": "organization-configurations" - } - }, - "patch": { - "summary": "Update a private registry for an organization", - "description": "\nUpdates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", - "tags": [ - "private-registries" - ], - "operationId": "private-registries/update-org-private-registry", - "externalDocs": { - "description": "API method documentation", - "url": "https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#update-a-private-registry-for-an-organization" - }, - "parameters": [ - { - "$ref": "#/components/parameters/org" - }, - { - "$ref": "#/components/parameters/secret-name" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "registry_type": { - "description": "The registry type.", - "type": "string", - "enum": [ - "maven_repository", - "nuget_feed", - "goproxy_server", - "npm_registry", - "rubygems_server", - "cargo_registry", - "composer_repository", - "docker_registry", - "git_source", - "helm_registry", - "hex_organization", - "hex_repository", - "pub_repository", - "python_index", - "terraform_registry" - ] - }, - "url": { - "description": "The URL of the private registry.", - "type": "string", - "format": "uri" - }, - "username": { - "description": "The username to use when authenticating with the private registry. This field should be omitted if the private registry does not require a username for authentication.", - "type": "string", - "nullable": true - }, - "replaces_base": { - "description": "Whether this private registry should replace the base registry (e.g., npmjs.org for npm, rubygems.org for rubygems). When set to `true`, Dependabot will only use this registry and will not fall back to the public registry. When set to `false` (default), Dependabot will use this registry for scoped packages but may fall back to the public registry for other packages.", - "type": "boolean", - "default": false - }, - "encrypted_value": { - "description": "The value for your secret, encrypted with [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages) using the public key retrieved from the [Get private registries public key for an organization](https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization) endpoint.", - "type": "string", - "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{4})$" - }, - "key_id": { - "description": "The ID of the key you used to encrypt the secret.", - "type": "string" - }, - "visibility": { - "description": "Which type of organization repositories have access to the private registry. `selected` means only the repositories specified by `selected_repository_ids` can access the private registry.", - "type": "string", - "enum": [ - "all", - "private", - "selected" - ] - }, - "selected_repository_ids": { - "description": "An array of repository IDs that can access the organization private registry. You can only provide a list of repository IDs when `visibility` is set to `selected`. This field should be omitted if `visibility` is set to `all` or `private`.", - "type": "array", - "items": { - "type": "integer" - } - }, - "auth_type": { - "description": "The authentication type for the private registry. This field cannot be changed after creation. If provided, it must match the existing `auth_type` of the configuration. To change the authentication type, delete and recreate the configuration.", - "type": "string", - "enum": [ - "token", - "username_password", - "oidc_azure", - "oidc_aws", - "oidc_jfrog", - "oidc_cloudsmith" - ] - }, - "tenant_id": { - "description": "The tenant ID of the Azure AD application. Required when `auth_type` is `oidc_azure`.", - "type": "string" - }, - "client_id": { - "description": "The client ID of the Azure AD application. Required when `auth_type` is `oidc_azure`.", - "type": "string" - }, - "aws_region": { - "description": "The AWS region. Required when `auth_type` is `oidc_aws`.", - "type": "string" - }, - "account_id": { - "description": "The AWS account ID. Required when `auth_type` is `oidc_aws`.", - "type": "string" - }, - "role_name": { - "description": "The AWS IAM role name. Required when `auth_type` is `oidc_aws`.", + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). Required when `auth_type` is `oidc_gcp`.", "type": "string" }, - "domain": { - "description": "The CodeArtifact domain. Required when `auth_type` is `oidc_aws`.", - "type": "string" - }, - "domain_owner": { - "description": "The CodeArtifact domain owner (AWS account ID). Required when `auth_type` is `oidc_aws`.", - "type": "string" - }, - "jfrog_oidc_provider_name": { - "description": "The JFrog OIDC provider name. Required when `auth_type` is `oidc_jfrog`.", - "type": "string" - }, - "audience": { - "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and required for `oidc_cloudsmith` auth types.", - "type": "string" - }, - "identity_mapping_name": { - "description": "The JFrog identity mapping name. Optional for `oidc_jfrog` auth type.", - "type": "string" - }, - "namespace": { - "description": "The Cloudsmith organization namespace. Required when `auth_type` is `oidc_cloudsmith`.", - "type": "string" - }, - "service_slug": { - "description": "The Cloudsmith service account slug. Required when `auth_type` is `oidc_cloudsmith`.", - "type": "string" - }, - "api_host": { - "description": "The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default.", + "service_account": { + "description": "The GCP service account email to impersonate. Optional for `oidc_gcp` auth type. If omitted, the federated token is used directly (direct WIF).", "type": "string" } } @@ -47657,6 +50844,139 @@ } } }, + "/repos/{owner}/{repo}/actions/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a repository", + "description": "Lists the active concurrency groups for a repository.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository" + }, + "parameters": [ + { + "$ref": "#/components/parameters/owner" + }, + { + "$ref": "#/components/parameters/repo" + }, + { + "$ref": "#/components/parameters/per-page" + }, + { + "$ref": "#/components/parameters/pagination-after" + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/concurrency-group-list" + }, + "examples": { + "default": { + "$ref": "#/components/examples/concurrency-group-list" + } + } + } + }, + "headers": { + "Link": { + "$ref": "#/components/headers/link" + } + } + }, + "422": { + "$ref": "#/components/responses/validation_failed" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": { + "get": { + "summary": "Get a concurrency group for a repository", + "description": "Gets a specific concurrency group for a repository, including all instances in the group's queue.\nReturns 404 if the group is inactive or does not exist.\n\nOptionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items\nahead of the specified workflow run or job in the queue, plus the specified item itself\n(returned as the last element). This is useful for determining what is blocking a particular\nrun or job. Returns 422 if the specified run or job is not in this concurrency group.\n\nWhen using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow\nleases held on behalf of that run. Job-level leases within the run are not considered to\nblock the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow\nleases on the job's ancestor paths.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/get-concurrency-group-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository" + }, + "parameters": [ + { + "$ref": "#/components/parameters/owner" + }, + { + "$ref": "#/components/parameters/repo" + }, + { + "$ref": "#/components/parameters/concurrency-group-name" + }, + { + "name": "ahead_of_run", + "description": "Filter to items ahead of this workflow run ID in the queue, plus the run itself.\nMatches workflow-level concurrency and reusable-workflow leases held on behalf of\nthe run. Mutually exclusive with `ahead_of_job`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + }, + { + "name": "ahead_of_job", + "description": "Filter to items ahead of this job ID in the queue, plus the job itself.\nMatches job-level concurrency and reusable-workflow leases on the job's\nancestor paths. Mutually exclusive with `ahead_of_run`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/concurrency-group" + }, + "examples": { + "default": { + "$ref": "#/components/examples/concurrency-group" + } + } + } + } + }, + "404": { + "$ref": "#/components/responses/not_found" + }, + "422": { + "$ref": "#/components/responses/validation_failed" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/jobs/{job_id}": { "get": { "summary": "Get a job for a workflow run", @@ -50068,6 +53388,74 @@ } } }, + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a workflow run", + "description": "Lists all concurrency groups associated with a workflow run or its jobs.\n\nThe set of groups is derived from the run's configuration, so a group is\nincluded even when the run no longer has any items currently holding or\nwaiting in it. In that case the `group_members` array will be empty.\n`total_count` reflects the number of groups the run participates in by\nconfiguration, not the number with active items.\n\nThis differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`,\nwhich returns 404 when a group has no active items. That endpoint reports\nthe live state of a group repo-wide, while this endpoint reports the\ngroups associated with a specific run by configuration.\n\nResults are sorted by group name and support cursor-based pagination via\n`before` and `after`. The `after` cursor paginates forward only and does\nnot emit a `rel=\"prev\"` Link; use `before` to page backward from a\nforward page's `next` cursor.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-workflow-run", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run" + }, + "parameters": [ + { + "$ref": "#/components/parameters/owner" + }, + { + "$ref": "#/components/parameters/repo" + }, + { + "$ref": "#/components/parameters/run-id" + }, + { + "$ref": "#/components/parameters/per-page" + }, + { + "$ref": "#/components/parameters/pagination-before" + }, + { + "$ref": "#/components/parameters/pagination-after" + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/concurrency-group-run-list" + }, + "examples": { + "default": { + "$ref": "#/components/examples/concurrency-group-run-list" + } + } + } + }, + "headers": { + "Link": { + "$ref": "#/components/headers/link" + } + } + }, + "404": { + "$ref": "#/components/responses/not_found" + }, + "422": { + "$ref": "#/components/responses/validation_failed" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": { "post": { "summary": "Review custom deployment protection rules for a workflow run", @@ -145691,7 +149079,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ], "type": "string" }, @@ -145772,6 +149161,14 @@ "description": "The Cloudsmith API host.", "type": "string" }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`).", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. If omitted, the federated token is used directly (direct WIF).", + "type": "string" + }, "created_at": { "type": "string", "format": "date-time" @@ -145828,7 +149225,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ], "type": "string" }, @@ -145915,6 +149313,14 @@ "description": "The Cloudsmith API host.", "type": "string" }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`).", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. If omitted, the federated token is used directly (direct WIF).", + "type": "string" + }, "created_at": { "type": "string", "format": "date-time" @@ -150257,6 +153663,134 @@ "actions_caches" ] }, + "concurrency-group-list": { + "title": "Concurrency Group List", + "description": "A list of active concurrency groups for a repository.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer" + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "last_acquired_at" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "last_acquired_at": { + "type": "string", + "format": "date-time", + "nullable": true + } + } + } + } + } + }, + "concurrency-group": { + "title": "Concurrency Group", + "description": "A concurrency group with the workflow runs and jobs that are either currently holding\nor waiting for the concurrency group lease.", + "type": "object", + "required": [ + "group_name", + "group_url", + "total_count", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "total_count": { + "type": "integer" + }, + "group_members": { + "type": "array", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": "string", + "format": "uri", + "description": "API URL for the workflow run.", + "nullable": true + }, + "run_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the workflow run.", + "nullable": true + }, + "job_id": { + "type": "integer", + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_name": { + "type": "string", + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_url": { + "type": "string", + "format": "uri", + "description": "API URL for the job.", + "nullable": true + }, + "job_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the job.", + "nullable": true + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + }, "job": { "title": "Job", "description": "Information of a job execution in a workflow run", @@ -150992,6 +154526,119 @@ "comment" ] }, + "concurrency-group-run-list": { + "title": "Concurrency Group Run List", + "description": "A list of concurrency groups associated with a workflow run.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer", + "description": "The total number of concurrency groups this workflow run participates in,\nderived from the run's configuration. This count is not filtered by\nwhether the run currently holds or is waiting in each group, so it can\ninclude groups whose `group_members` array is empty (for example, when\nthe run has already released its lease in that group)." + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group. May return 404 if the group\nhas no active items at the time it is requested, since the\nget-by-name endpoint reports the live repo-wide state of a group\nwhile this endpoint lists groups associated with a run by\nconfiguration." + }, + "group_members": { + "type": "array", + "description": "Items belonging to this workflow run that are either currently holding or\nwaiting for the concurrency group lease. May be empty if the run no\nlonger has any active or queued items in this group.", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status", + "position", + "position_url" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": "string", + "format": "uri", + "description": "API URL for the workflow run.", + "nullable": true + }, + "run_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the workflow run.", + "nullable": true + }, + "position": { + "type": "integer", + "description": "Queue position. 0 means the item holds the concurrency lease (in_progress), 1 or higher means queued (pending)." + }, + "position_url": { + "type": "string", + "format": "uri", + "description": "API URL to get items ahead of this item in the concurrency group." + }, + "job_id": { + "type": "integer", + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease.", + "nullable": true + }, + "job_name": { + "type": "string", + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease.", + "nullable": true + }, + "job_url": { + "type": "string", + "format": "uri", + "description": "API URL for the job.", + "nullable": true + }, + "job_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the job.", + "nullable": true + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + } + } + } + }, "review-custom-gates-comment-required": { "type": "object", "properties": { @@ -327506,6 +331153,57 @@ ] } }, + "concurrency-group-list": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "last_acquired_at": "2026-01-15T16:14:23Z" + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "last_acquired_at": "2026-01-15T16:13:55Z" + } + ] + } + }, + "concurrency-group": { + "value": { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "total_count": 3, + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress" + }, + { + "run_id": 30433643, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433643", + "status": "pending" + }, + { + "run_id": 30433644, + "run_name": "Deploy hotfix", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644", + "job_id": 798245260, + "job_name": "deploy", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260", + "status": "pending" + } + ] + } + }, "job": { "value": { "id": 399444496, @@ -328294,6 +331992,47 @@ ] } }, + "concurrency-group-run-list": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress", + "position": 0, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642" + } + ] + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "pending", + "position": 2, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260", + "job_id": 798245260, + "job_name": "build", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260" + } + ] + } + ] + } + }, "pending-deployment-items": { "value": [ { @@ -349157,6 +352896,15 @@ "type": "integer" } }, + "concurrency-group-name": { + "name": "concurrency_group_name", + "description": "The name of the concurrency group.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, "job-id": { "name": "job_id", "description": "The unique identifier of the job.", diff --git a/descriptions/ghec/ghec.2026-03-10.yaml b/descriptions/ghec/ghec.2026-03-10.yaml index dbd8931ca..20449c69d 100644 --- a/descriptions/ghec/ghec.2026-03-10.yaml +++ b/descriptions/ghec/ghec.2026-03-10.yaml @@ -351,6 +351,2525 @@ paths: enabledForGitHubApps: true category: security-advisories subcategory: global-advisories + "/agents/repos/{owner}/{repo}/tasks": + get: + summary: List tasks for repository + description: | + > [!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](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks-for-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#list-tasks-for-repository + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: '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`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + - name: creator_id + in: query + schema: + type: integer + description: Filter tasks by creator user ID + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="prev" (when current page > 1), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; + rel="next", ; + rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + post: + summary: Start a task + description: | + > [!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](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/create-task-in-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#start-a-task + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + requestBody: + required: true + description: The task creation parameters, including the user's prompt and + optional agent settings. + content: + application/json: + schema: + type: object + required: + - prompt + properties: + prompt: + type: string + description: The user's prompt for the agent + model: + type: string + 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`' + create_pull_request: + type: boolean + description: Whether to create a PR. + default: false + base_ref: + type: string + description: Base ref for new branch/PR + examples: + default: + value: + prompt: Fix the login button on the homepage + base_ref: main + responses: + '201': + description: Task created successfully + content: + application/json: + schema: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + examples: + default: + value: + id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: queued + session_count: 1 + artifacts: [] + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T00:00:00Z' + '400': + description: Problems parsing JSON + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/repos/{owner}/{repo}/tasks/{task_id}": + get: + summary: Get a task by repo + description: | + > [!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](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-repo-and-id + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#get-a-task-by-repo + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks": + get: + summary: List tasks + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a list of tasks for the authenticated user + + **Fine-grained access tokens for "List tasks"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#list-tasks + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: '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`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; rel="next", + ; rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks/{task_id}": + get: + summary: Get a task by ID + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a task by ID with its associated sessions + + **Fine-grained access tokens for "Get a task by ID"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-id + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#get-a-task-by-id + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: string + format: date-time + nullable: true + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + html_url: https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + creator: + id: 1 + creator_type: user + owner: + id: 1 + repository: + id: 1296269 + state: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Problems parsing request + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + Structured error response following GitHub REST API conventions. + For 422 Unprocessable Entity the errors array contains validation + details; for other error status codes only message and + documentation_url are returned. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation "/app": get: summary: Get the authenticated app @@ -29131,7 +31650,7 @@ paths: description: |2- Creates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see "[Encrypting secrets for the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/encrypting-secrets-for-the-rest-api)." - For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted. + For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted. OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. tags: @@ -29224,7 +31743,332 @@ paths: auth_type: description: The authentication type for the private registry. Defaults to `token` if not specified. Use `oidc_azure`, `oidc_aws`, `oidc_jfrog`, - or `oidc_cloudsmith` for OIDC authentication. + `oidc_cloudsmith`, or `oidc_gcp` for OIDC authentication. + type: string + enum: + - token + - username_password + - oidc_azure + - oidc_aws + - oidc_jfrog + - oidc_cloudsmith + - oidc_gcp + tenant_id: + description: The tenant ID of the Azure AD application. Required + when `auth_type` is `oidc_azure`. + type: string + client_id: + description: The client ID of the Azure AD application. Required + when `auth_type` is `oidc_azure`. + type: string + aws_region: + description: The AWS region. Required when `auth_type` is `oidc_aws`. + type: string + account_id: + description: The AWS account ID. Required when `auth_type` is `oidc_aws`. + type: string + role_name: + description: The AWS IAM role name. Required when `auth_type` is + `oidc_aws`. + type: string + domain: + description: The CodeArtifact domain. Required when `auth_type` + is `oidc_aws`. + type: string + domain_owner: + description: The CodeArtifact domain owner (AWS account ID). Required + when `auth_type` is `oidc_aws`. + type: string + jfrog_oidc_provider_name: + description: The JFrog OIDC provider name. Required when `auth_type` + is `oidc_jfrog`. + type: string + audience: + description: The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, + and `oidc_gcp`, and required for `oidc_cloudsmith` auth types. + type: string + identity_mapping_name: + description: The JFrog identity mapping name. Optional for `oidc_jfrog` + auth type. + type: string + namespace: + description: The Cloudsmith organization namespace. Required when + `auth_type` is `oidc_cloudsmith`. + type: string + service_slug: + description: The Cloudsmith service account slug. Required when + `auth_type` is `oidc_cloudsmith`. + type: string + api_host: + description: The Cloudsmith API host. Optional for `oidc_cloudsmith` + auth type. If omitted, `api.cloudsmith.io` is used by default. + type: string + workload_identity_provider: + description: The full resource name of the GCP Workload Identity + Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + Required when `auth_type` is `oidc_gcp`. + type: string + service_account: + description: The GCP service account email to impersonate. Optional + for `oidc_gcp` auth type. If omitted, the federated token is used + directly (direct WIF). + type: string + required: + - registry_type + - url + - visibility + examples: + org-private-registry-with-private-visibility: + summary: Example of a private registry configuration with private + visibility + value: + registry_type: maven_repository + url: https://maven.pkg.github.com/organization/ + username: monalisa + replaces_base: true + encrypted_value: c2VjcmV0 + key_id: '012345678912345678' + visibility: private + org-private-registry-with-selected-visibility: + summary: Example of a private registry configuration with selected + visibility + value: + registry_type: maven_repository + url: https://maven.pkg.github.com/organization/ + username: monalisa + encrypted_value: c2VjcmV0 + key_id: '012345678912345678' + visibility: selected + selected_repository_ids: + - 1296269 + - 1296280 + org-private-registry-with-oidc-azure: + summary: Example of an OIDC private registry configuration using Azure + value: + registry_type: docker_registry + url: https://myregistry.azurecr.io + auth_type: oidc_azure + visibility: all + tenant_id: 12345678-1234-1234-1234-123456789012 + client_id: abcdef01-2345-6789-abcd-ef0123456789 + org-private-registry-with-oidc-cloudsmith: + summary: Example of an OIDC private registry configuration using Cloudsmith + value: + registry_type: npm_registry + url: https://npm.cloudsmith.io/my-org/my-repo/ + auth_type: oidc_cloudsmith + visibility: all + namespace: my-org + service_slug: my-service-account + audience: https://github.com/my-org + org-private-registry-with-oidc-gcp: + summary: Example of an OIDC private registry configuration using Google + Cloud Artifact Registry + value: + registry_type: docker_registry + url: https://us-docker.pkg.dev/my-project/my-repo + auth_type: oidc_gcp + visibility: all + workload_identity_provider: projects/123456789/locations/global/workloadIdentityPools/github-pool/providers/github-provider + service_account: dependabot@my-project.iam.gserviceaccount.com + responses: + '201': + description: The organization private registry configuration + content: + application/json: + schema: + "$ref": "#/components/schemas/org-private-registry-configuration-with-selected-repositories" + examples: + org-private-registry-with-selected-visibility: + "$ref": "#/components/examples/org-private-registry-configuration" + org-private-registry-with-private-visibility: + "$ref": "#/components/examples/org-private-registry-configuration-with-selected-repositories" + '404': + "$ref": "#/components/responses/not_found" + '422': + "$ref": "#/components/responses/validation_failed" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: private-registries + subcategory: organization-configurations + "/orgs/{org}/private-registries/public-key": + get: + summary: Get private registries public key for an organization + description: |2- + + Gets the org public key, which is needed to encrypt private registry secrets. You need to encrypt a secret before you can create or update secrets. + + OAuth tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. + tags: + - private-registries + operationId: private-registries/get-org-public-key + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization + parameters: + - "$ref": "#/components/parameters/org" + responses: + '200': + description: Response + content: + application/json: + schema: + type: object + required: + - key_id + - key + properties: + key_id: + description: The identifier for the key. + example: '012345678912345678' + type: string + key: + description: The Base64 encoded public key. + example: 2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234 + type: string + examples: + default: + "$ref": "#/components/examples/private-registries-public-key" + headers: + Link: + "$ref": "#/components/headers/link" + '404': + "$ref": "#/components/responses/not_found" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: private-registries + subcategory: organization-configurations + "/orgs/{org}/private-registries/{secret_name}": + get: + summary: Get a private registry for an organization + description: |2- + + Get the configuration of a single private registry defined for an organization, omitting its encrypted value. + + OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. + tags: + - private-registries + operationId: private-registries/get-org-private-registry + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#get-a-private-registry-for-an-organization + parameters: + - "$ref": "#/components/parameters/org" + - "$ref": "#/components/parameters/secret-name" + responses: + '200': + description: The specified private registry configuration for the organization + content: + application/json: + schema: + "$ref": "#/components/schemas/org-private-registry-configuration" + examples: + default: + "$ref": "#/components/examples/org-private-registry-configuration" + '404': + "$ref": "#/components/responses/not_found" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: private-registries + subcategory: organization-configurations + patch: + summary: Update a private registry for an organization + description: |2- + + Updates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see "[Encrypting secrets for the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/encrypting-secrets-for-the-rest-api)." + For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted. + + OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. + tags: + - private-registries + operationId: private-registries/update-org-private-registry + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#update-a-private-registry-for-an-organization + parameters: + - "$ref": "#/components/parameters/org" + - "$ref": "#/components/parameters/secret-name" + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + registry_type: + description: The registry type. + type: string + enum: + - maven_repository + - nuget_feed + - goproxy_server + - npm_registry + - rubygems_server + - cargo_registry + - composer_repository + - docker_registry + - git_source + - helm_registry + - hex_organization + - hex_repository + - pub_repository + - python_index + - terraform_registry + url: + description: The URL of the private registry. + type: string + format: uri + username: + description: The username to use when authenticating with the private + registry. This field should be omitted if the private registry + does not require a username for authentication. + type: string + nullable: true + replaces_base: + description: Whether this private registry should replace the base + registry (e.g., npmjs.org for npm, rubygems.org for rubygems). + When set to `true`, Dependabot will only use this registry and + will not fall back to the public registry. When set to `false` + (default), Dependabot will use this registry for scoped packages + but may fall back to the public registry for other packages. + type: boolean + default: false + encrypted_value: + description: The value for your secret, encrypted with [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages) + using the public key retrieved from the [Get private registries + public key for an organization](https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization) + endpoint. + type: string + pattern: "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{4})$" + key_id: + description: The ID of the key you used to encrypt the secret. + type: string + visibility: + description: Which type of organization repositories have access + to the private registry. `selected` means only the repositories + specified by `selected_repository_ids` can access the private + registry. + type: string + enum: + - all + - private + - selected + selected_repository_ids: + description: An array of repository IDs that can access the organization + private registry. You can only provide a list of repository IDs + when `visibility` is set to `selected`. This field should be omitted + if `visibility` is set to `all` or `private`. + type: array + items: + type: integer + auth_type: + description: The authentication type for the private registry. This + field cannot be changed after creation. If provided, it must match + the existing `auth_type` of the configuration. To change the authentication + type, delete and recreate the configuration. type: string enum: - token @@ -29233,6 +32077,7 @@ paths: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp tenant_id: description: The tenant ID of the Azure AD application. Required when `auth_type` is `oidc_azure`. @@ -29265,7 +32110,7 @@ paths: type: string audience: description: The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, - and required for `oidc_cloudsmith` auth types. + and `oidc_gcp`, and required for `oidc_cloudsmith` auth types. type: string identity_mapping_name: description: The JFrog identity mapping name. Optional for `oidc_jfrog` @@ -29283,309 +32128,15 @@ paths: description: The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default. type: string - required: - - registry_type - - url - - visibility - examples: - org-private-registry-with-private-visibility: - summary: Example of a private registry configuration with private - visibility - value: - registry_type: maven_repository - url: https://maven.pkg.github.com/organization/ - username: monalisa - replaces_base: true - encrypted_value: c2VjcmV0 - key_id: '012345678912345678' - visibility: private - org-private-registry-with-selected-visibility: - summary: Example of a private registry configuration with selected - visibility - value: - registry_type: maven_repository - url: https://maven.pkg.github.com/organization/ - username: monalisa - encrypted_value: c2VjcmV0 - key_id: '012345678912345678' - visibility: selected - selected_repository_ids: - - 1296269 - - 1296280 - org-private-registry-with-oidc-azure: - summary: Example of an OIDC private registry configuration using Azure - value: - registry_type: docker_registry - url: https://myregistry.azurecr.io - auth_type: oidc_azure - visibility: all - tenant_id: 12345678-1234-1234-1234-123456789012 - client_id: abcdef01-2345-6789-abcd-ef0123456789 - org-private-registry-with-oidc-cloudsmith: - summary: Example of an OIDC private registry configuration using Cloudsmith - value: - registry_type: npm_registry - url: https://npm.cloudsmith.io/my-org/my-repo/ - auth_type: oidc_cloudsmith - visibility: all - namespace: my-org - service_slug: my-service-account - audience: https://github.com/my-org - responses: - '201': - description: The organization private registry configuration - content: - application/json: - schema: - "$ref": "#/components/schemas/org-private-registry-configuration-with-selected-repositories" - examples: - org-private-registry-with-selected-visibility: - "$ref": "#/components/examples/org-private-registry-configuration" - org-private-registry-with-private-visibility: - "$ref": "#/components/examples/org-private-registry-configuration-with-selected-repositories" - '404': - "$ref": "#/components/responses/not_found" - '422': - "$ref": "#/components/responses/validation_failed" - x-github: - githubCloudOnly: false - enabledForGitHubApps: true - category: private-registries - subcategory: organization-configurations - "/orgs/{org}/private-registries/public-key": - get: - summary: Get private registries public key for an organization - description: |2- - - Gets the org public key, which is needed to encrypt private registry secrets. You need to encrypt a secret before you can create or update secrets. - - OAuth tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. - tags: - - private-registries - operationId: private-registries/get-org-public-key - externalDocs: - description: API method documentation - url: https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization - parameters: - - "$ref": "#/components/parameters/org" - responses: - '200': - description: Response - content: - application/json: - schema: - type: object - required: - - key_id - - key - properties: - key_id: - description: The identifier for the key. - example: '012345678912345678' - type: string - key: - description: The Base64 encoded public key. - example: 2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234 - type: string - examples: - default: - "$ref": "#/components/examples/private-registries-public-key" - headers: - Link: - "$ref": "#/components/headers/link" - '404': - "$ref": "#/components/responses/not_found" - x-github: - githubCloudOnly: false - enabledForGitHubApps: true - category: private-registries - subcategory: organization-configurations - "/orgs/{org}/private-registries/{secret_name}": - get: - summary: Get a private registry for an organization - description: |2- - - Get the configuration of a single private registry defined for an organization, omitting its encrypted value. - - OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. - tags: - - private-registries - operationId: private-registries/get-org-private-registry - externalDocs: - description: API method documentation - url: https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#get-a-private-registry-for-an-organization - parameters: - - "$ref": "#/components/parameters/org" - - "$ref": "#/components/parameters/secret-name" - responses: - '200': - description: The specified private registry configuration for the organization - content: - application/json: - schema: - "$ref": "#/components/schemas/org-private-registry-configuration" - examples: - default: - "$ref": "#/components/examples/org-private-registry-configuration" - '404': - "$ref": "#/components/responses/not_found" - x-github: - githubCloudOnly: false - enabledForGitHubApps: true - category: private-registries - subcategory: organization-configurations - patch: - summary: Update a private registry for an organization - description: |2- - - Updates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see "[Encrypting secrets for the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/encrypting-secrets-for-the-rest-api)." - For OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted. - - OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint. - tags: - - private-registries - operationId: private-registries/update-org-private-registry - externalDocs: - description: API method documentation - url: https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#update-a-private-registry-for-an-organization - parameters: - - "$ref": "#/components/parameters/org" - - "$ref": "#/components/parameters/secret-name" - requestBody: - required: true - content: - application/json: - schema: - type: object - properties: - registry_type: - description: The registry type. - type: string - enum: - - maven_repository - - nuget_feed - - goproxy_server - - npm_registry - - rubygems_server - - cargo_registry - - composer_repository - - docker_registry - - git_source - - helm_registry - - hex_organization - - hex_repository - - pub_repository - - python_index - - terraform_registry - url: - description: The URL of the private registry. - type: string - format: uri - username: - description: The username to use when authenticating with the private - registry. This field should be omitted if the private registry - does not require a username for authentication. - type: string - nullable: true - replaces_base: - description: Whether this private registry should replace the base - registry (e.g., npmjs.org for npm, rubygems.org for rubygems). - When set to `true`, Dependabot will only use this registry and - will not fall back to the public registry. When set to `false` - (default), Dependabot will use this registry for scoped packages - but may fall back to the public registry for other packages. - type: boolean - default: false - encrypted_value: - description: The value for your secret, encrypted with [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages) - using the public key retrieved from the [Get private registries - public key for an organization](https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization) - endpoint. - type: string - pattern: "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{4})$" - key_id: - description: The ID of the key you used to encrypt the secret. - type: string - visibility: - description: Which type of organization repositories have access - to the private registry. `selected` means only the repositories - specified by `selected_repository_ids` can access the private - registry. - type: string - enum: - - all - - private - - selected - selected_repository_ids: - description: An array of repository IDs that can access the organization - private registry. You can only provide a list of repository IDs - when `visibility` is set to `selected`. This field should be omitted - if `visibility` is set to `all` or `private`. - type: array - items: - type: integer - auth_type: - description: The authentication type for the private registry. This - field cannot be changed after creation. If provided, it must match - the existing `auth_type` of the configuration. To change the authentication - type, delete and recreate the configuration. - type: string - enum: - - token - - username_password - - oidc_azure - - oidc_aws - - oidc_jfrog - - oidc_cloudsmith - tenant_id: - description: The tenant ID of the Azure AD application. Required - when `auth_type` is `oidc_azure`. - type: string - client_id: - description: The client ID of the Azure AD application. Required - when `auth_type` is `oidc_azure`. - type: string - aws_region: - description: The AWS region. Required when `auth_type` is `oidc_aws`. - type: string - account_id: - description: The AWS account ID. Required when `auth_type` is `oidc_aws`. - type: string - role_name: - description: The AWS IAM role name. Required when `auth_type` is - `oidc_aws`. - type: string - domain: - description: The CodeArtifact domain. Required when `auth_type` - is `oidc_aws`. - type: string - domain_owner: - description: The CodeArtifact domain owner (AWS account ID). Required - when `auth_type` is `oidc_aws`. - type: string - jfrog_oidc_provider_name: - description: The JFrog OIDC provider name. Required when `auth_type` - is `oidc_jfrog`. - type: string - audience: - description: The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, - and required for `oidc_cloudsmith` auth types. + workload_identity_provider: + description: The full resource name of the GCP Workload Identity + Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + Required when `auth_type` is `oidc_gcp`. type: string - identity_mapping_name: - description: The JFrog identity mapping name. Optional for `oidc_jfrog` - auth type. - type: string - namespace: - description: The Cloudsmith organization namespace. Required when - `auth_type` is `oidc_cloudsmith`. - type: string - service_slug: - description: The Cloudsmith service account slug. Required when - `auth_type` is `oidc_cloudsmith`. - type: string - api_host: - description: The Cloudsmith API host. Optional for `oidc_cloudsmith` - auth type. If omitted, `api.cloudsmith.io` is used by default. + service_account: + description: The GCP service account email to impersonate. Optional + for `oidc_gcp` auth type. If omitted, the federated token is used + directly (direct WIF). type: string examples: secret-based-update: @@ -34698,6 +37249,111 @@ paths: enabledForGitHubApps: true category: actions subcategory: cache + "/repos/{owner}/{repo}/actions/concurrency_groups": + get: + summary: List concurrency groups for a repository + description: |- + Lists the active concurrency groups for a repository. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository + parameters: + - "$ref": "#/components/parameters/owner" + - "$ref": "#/components/parameters/repo" + - "$ref": "#/components/parameters/per-page" + - "$ref": "#/components/parameters/pagination-after" + responses: + '200': + description: Response + content: + application/json: + schema: + "$ref": "#/components/schemas/concurrency-group-list" + examples: + default: + "$ref": "#/components/examples/concurrency-group-list" + headers: + Link: + "$ref": "#/components/headers/link" + '422': + "$ref": "#/components/responses/validation_failed" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": + get: + summary: Get a concurrency group for a repository + description: |- + Gets a specific concurrency group for a repository, including all instances in the group's queue. + Returns 404 if the group is inactive or does not exist. + + Optionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items + ahead of the specified workflow run or job in the queue, plus the specified item itself + (returned as the last element). This is useful for determining what is blocking a particular + run or job. Returns 422 if the specified run or job is not in this concurrency group. + + When using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow + leases held on behalf of that run. Job-level leases within the run are not considered to + block the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow + leases on the job's ancestor paths. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/get-concurrency-group-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository + parameters: + - "$ref": "#/components/parameters/owner" + - "$ref": "#/components/parameters/repo" + - "$ref": "#/components/parameters/concurrency-group-name" + - name: ahead_of_run + description: |- + Filter to items ahead of this workflow run ID in the queue, plus the run itself. + Matches workflow-level concurrency and reusable-workflow leases held on behalf of + the run. Mutually exclusive with `ahead_of_job`. + in: query + required: false + schema: + type: integer + minimum: 1 + - name: ahead_of_job + description: |- + Filter to items ahead of this job ID in the queue, plus the job itself. + Matches job-level concurrency and reusable-workflow leases on the job's + ancestor paths. Mutually exclusive with `ahead_of_run`. + in: query + required: false + schema: + type: integer + minimum: 1 + responses: + '200': + description: Response + content: + application/json: + schema: + "$ref": "#/components/schemas/concurrency-group" + examples: + default: + "$ref": "#/components/examples/concurrency-group" + '404': + "$ref": "#/components/responses/not_found" + '422': + "$ref": "#/components/responses/validation_failed" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/jobs/{job_id}": get: summary: Get a job for a workflow run @@ -36407,6 +39063,64 @@ paths: enabledForGitHubApps: true category: actions subcategory: workflow-runs + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": + get: + summary: List concurrency groups for a workflow run + description: |- + Lists all concurrency groups associated with a workflow run or its jobs. + + The set of groups is derived from the run's configuration, so a group is + included even when the run no longer has any items currently holding or + waiting in it. In that case the `group_members` array will be empty. + `total_count` reflects the number of groups the run participates in by + configuration, not the number with active items. + + This differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`, + which returns 404 when a group has no active items. That endpoint reports + the live state of a group repo-wide, while this endpoint reports the + groups associated with a specific run by configuration. + + Results are sorted by group name and support cursor-based pagination via + `before` and `after`. The `after` cursor paginates forward only and does + not emit a `rel="prev"` Link; use `before` to page backward from a + forward page's `next` cursor. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-workflow-run + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run + parameters: + - "$ref": "#/components/parameters/owner" + - "$ref": "#/components/parameters/repo" + - "$ref": "#/components/parameters/run-id" + - "$ref": "#/components/parameters/per-page" + - "$ref": "#/components/parameters/pagination-before" + - "$ref": "#/components/parameters/pagination-after" + responses: + '200': + description: Response + content: + application/json: + schema: + "$ref": "#/components/schemas/concurrency-group-run-list" + examples: + default: + "$ref": "#/components/examples/concurrency-group-run-list" + headers: + Link: + "$ref": "#/components/headers/link" + '404': + "$ref": "#/components/responses/not_found" + '422': + "$ref": "#/components/responses/validation_failed" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": post: summary: Review custom deployment protection rules for a workflow run @@ -106671,6 +109385,7 @@ components: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp type: string url: description: The URL of the private registry. @@ -106736,6 +109451,14 @@ components: api_host: description: The Cloudsmith API host. type: string + workload_identity_provider: + description: The full resource name of the GCP Workload Identity Provider + (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + type: string + service_account: + description: The GCP service account email to impersonate. If omitted, the + federated token is used directly (direct WIF). + type: string created_at: type: string format: date-time @@ -106785,6 +109508,7 @@ components: - oidc_aws - oidc_jfrog - oidc_cloudsmith + - oidc_gcp type: string url: description: The URL of the private registry. @@ -106856,6 +109580,14 @@ components: api_host: description: The Cloudsmith API host. type: string + workload_identity_provider: + description: The full resource name of the GCP Workload Identity Provider + (e.g. `projects//locations/global/workloadIdentityPools//providers/`). + type: string + service_account: + description: The GCP service account email to impersonate. If omitted, the + federated token is used directly (direct WIF). + type: string created_at: type: string format: date-time @@ -110266,6 +112998,107 @@ components: required: - total_count - actions_caches + concurrency-group-list: + title: Concurrency Group List + description: A list of active concurrency groups for a repository. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - last_acquired_at + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + last_acquired_at: + type: string + format: date-time + nullable: true + concurrency-group: + title: Concurrency Group + description: |- + A concurrency group with the workflow runs and jobs that are either currently holding + or waiting for the concurrency group lease. + type: object + required: + - group_name + - group_url + - total_count + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + total_count: + type: integer + group_members: + type: array + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: string + format: uri + description: API URL for the workflow run. + nullable: true + run_html_url: + type: string + format: uri + description: Web URL for the workflow run. + nullable: true + job_id: + type: integer + description: The ID of the job, when the item represents a job-level + or reusable-workflow-level lease. + job_name: + type: string + description: The display name of the job, when the item represents + a job-level or reusable-workflow-level lease. + job_url: + type: string + format: uri + description: API URL for the job. + nullable: true + job_html_url: + type: string + format: uri + description: Web URL for the job. + nullable: true + status: + type: string + enum: + - in_progress + - pending job: title: Job description: Information of a job execution in a workflow run @@ -110873,6 +113706,110 @@ components: - state - user - comment + concurrency-group-run-list: + title: Concurrency Group Run List + description: A list of concurrency groups associated with a workflow run. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + description: |- + The total number of concurrency groups this workflow run participates in, + derived from the run's configuration. This count is not filtered by + whether the run currently holds or is waiting in each group, so it can + include groups whose `group_members` array is empty (for example, when + the run has already released its lease in that group). + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: |- + API URL for this concurrency group. May return 404 if the group + has no active items at the time it is requested, since the + get-by-name endpoint reports the live repo-wide state of a group + while this endpoint lists groups associated with a run by + configuration. + group_members: + type: array + description: |- + Items belonging to this workflow run that are either currently holding or + waiting for the concurrency group lease. May be empty if the run no + longer has any active or queued items in this group. + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + - position + - position_url + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: string + format: uri + description: API URL for the workflow run. + nullable: true + run_html_url: + type: string + format: uri + description: Web URL for the workflow run. + nullable: true + position: + type: integer + description: Queue position. 0 means the item holds the concurrency + lease (in_progress), 1 or higher means queued (pending). + position_url: + type: string + format: uri + description: API URL to get items ahead of this item in the + concurrency group. + job_id: + type: integer + description: The ID of the job, when the item represents a job-level + or reusable-workflow-level lease. + nullable: true + job_name: + type: string + description: The display name of the job, when the item represents + a job-level or reusable-workflow-level lease. + nullable: true + job_url: + type: string + format: uri + description: API URL for the job. + nullable: true + job_html_url: + type: string + format: uri + description: Web URL for the job. + nullable: true + status: + type: string + enum: + - in_progress + - pending review-custom-gates-comment-required: type: object properties: @@ -245468,6 +248405,41 @@ components: last_accessed_at: '2019-01-24T22:45:36.000Z' created_at: '2019-01-24T22:45:36.000Z' size_in_bytes: 1024 + concurrency-group-list: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + last_acquired_at: '2026-01-15T16:14:23Z' + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + last_acquired_at: '2026-01-15T16:13:55Z' + concurrency-group: + value: + group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + total_count: 3 + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + - run_id: 30433643 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433643 + status: pending + - run_id: 30433644 + run_name: Deploy hotfix + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644 + job_id: 798245260 + job_name: deploy + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260 + status: pending job: value: id: 399444496 @@ -246144,6 +249116,34 @@ components: runner_group_name: my runner group workflow_name: CI head_branch: main + concurrency-group-run-list: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + position: 0 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642 + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: pending + position: 2 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260 + job_id: 798245260 + job_name: build + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260 pending-deployment-items: value: - environment: @@ -264126,6 +267126,13 @@ components: required: true schema: type: integer + concurrency-group-name: + name: concurrency_group_name + description: The name of the concurrency group. + in: path + required: true + schema: + type: string job-id: name: job_id description: The unique identifier of the job. diff --git a/descriptions/ghec/ghec.json b/descriptions/ghec/ghec.json index d9b871a39..0227d728e 100644 --- a/descriptions/ghec/ghec.json +++ b/descriptions/ghec/ghec.json @@ -546,6 +546,3164 @@ } } }, + "/agents/repos/{owner}/{repo}/tasks": { + "get": { + "summary": "List tasks for repository", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for a specific repository\n\n**Fine-grained access tokens for \"List tasks for repository\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks-for-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#list-tasks-for-repository" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "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`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + }, + { + "name": "creator_id", + "in": "query", + "schema": { + "type": "integer" + }, + "description": "Filter tasks by creator user ID" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"prev\" (when current page > 1),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + }, + "post": { + "summary": "Start a task", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nStarts a new Copilot cloud agent task for a repository.\n\nThis endpoint is only available to users with a Copilot Business or Copilot Enterprise subscription.\n\n**Fine-grained access tokens for \"Start a task\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read and write)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/create-task-in-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#start-a-task" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + } + ], + "requestBody": { + "required": true, + "description": "The task creation parameters, including the user's prompt and optional agent settings.", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "prompt" + ], + "properties": { + "prompt": { + "type": "string", + "description": "The user's prompt for the agent" + }, + "model": { + "type": "string", + "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`" + }, + "create_pull_request": { + "type": "boolean", + "description": "Whether to create a PR.", + "default": false + }, + "base_ref": { + "type": "string", + "description": "Base ref for new branch/PR" + } + } + }, + "examples": { + "default": { + "value": { + "prompt": "Fix the login button on the homepage", + "base_ref": "main" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Task created successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "examples": { + "default": { + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "queued", + "session_count": 1, + "artifacts": [], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T00:00:00Z" + } + } + } + } + } + }, + "400": { + "description": "Problems parsing JSON", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/repos/{owner}/{repo}/tasks/{task_id}": { + "get": { + "summary": "Get a task by repo", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID scoped to an owner/repo path\n\n**Fine-grained access tokens for \"Get a task by repo\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-repo-and-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#get-a-task-by-repo" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks": { + "get": { + "summary": "List tasks", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for the authenticated user\n\n**Fine-grained access tokens for \"List tasks\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#list-tasks" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "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`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks/{task_id}": { + "get": { + "summary": "Get a task by ID", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID with its associated sessions\n\n**Fine-grained access tokens for \"Get a task by ID\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#get-a-task-by-id" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "creator": { + "id": 1 + }, + "creator_type": "user", + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "state": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Problems parsing request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, "/app": { "get": { "summary": "Get the authenticated app", @@ -40348,7 +43506,7 @@ }, "post": { "summary": "Create a private registry for an organization", - "description": "\nCreates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", + "description": "\nCreates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", "tags": [ "private-registries" ], @@ -40431,7 +43589,387 @@ } }, "auth_type": { - "description": "The authentication type for the private registry. Defaults to `token` if not specified. Use `oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith` for OIDC authentication.", + "description": "The authentication type for the private registry. Defaults to `token` if not specified. Use `oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp` for OIDC authentication.", + "type": "string", + "enum": [ + "token", + "username_password", + "oidc_azure", + "oidc_aws", + "oidc_jfrog", + "oidc_cloudsmith", + "oidc_gcp" + ] + }, + "tenant_id": { + "description": "The tenant ID of the Azure AD application. Required when `auth_type` is `oidc_azure`.", + "type": "string" + }, + "client_id": { + "description": "The client ID of the Azure AD application. Required when `auth_type` is `oidc_azure`.", + "type": "string" + }, + "aws_region": { + "description": "The AWS region. Required when `auth_type` is `oidc_aws`.", + "type": "string" + }, + "account_id": { + "description": "The AWS account ID. Required when `auth_type` is `oidc_aws`.", + "type": "string" + }, + "role_name": { + "description": "The AWS IAM role name. Required when `auth_type` is `oidc_aws`.", + "type": "string" + }, + "domain": { + "description": "The CodeArtifact domain. Required when `auth_type` is `oidc_aws`.", + "type": "string" + }, + "domain_owner": { + "description": "The CodeArtifact domain owner (AWS account ID). Required when `auth_type` is `oidc_aws`.", + "type": "string" + }, + "jfrog_oidc_provider_name": { + "description": "The JFrog OIDC provider name. Required when `auth_type` is `oidc_jfrog`.", + "type": "string" + }, + "audience": { + "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and `oidc_gcp`, and required for `oidc_cloudsmith` auth types.", + "type": "string" + }, + "identity_mapping_name": { + "description": "The JFrog identity mapping name. Optional for `oidc_jfrog` auth type.", + "type": "string" + }, + "namespace": { + "description": "The Cloudsmith organization namespace. Required when `auth_type` is `oidc_cloudsmith`.", + "type": "string" + }, + "service_slug": { + "description": "The Cloudsmith service account slug. Required when `auth_type` is `oidc_cloudsmith`.", + "type": "string" + }, + "api_host": { + "description": "The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default.", + "type": "string" + }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). Required when `auth_type` is `oidc_gcp`.", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. Optional for `oidc_gcp` auth type. If omitted, the federated token is used directly (direct WIF).", + "type": "string" + } + }, + "required": [ + "registry_type", + "url", + "visibility" + ] + }, + "examples": { + "org-private-registry-with-private-visibility": { + "summary": "Example of a private registry configuration with private visibility", + "value": { + "registry_type": "maven_repository", + "url": "https://maven.pkg.github.com/organization/", + "username": "monalisa", + "replaces_base": true, + "encrypted_value": "c2VjcmV0", + "key_id": "012345678912345678", + "visibility": "private" + } + }, + "org-private-registry-with-selected-visibility": { + "summary": "Example of a private registry configuration with selected visibility", + "value": { + "registry_type": "maven_repository", + "url": "https://maven.pkg.github.com/organization/", + "username": "monalisa", + "encrypted_value": "c2VjcmV0", + "key_id": "012345678912345678", + "visibility": "selected", + "selected_repository_ids": [ + 1296269, + 1296280 + ] + } + }, + "org-private-registry-with-oidc-azure": { + "summary": "Example of an OIDC private registry configuration using Azure", + "value": { + "registry_type": "docker_registry", + "url": "https://myregistry.azurecr.io", + "auth_type": "oidc_azure", + "visibility": "all", + "tenant_id": "12345678-1234-1234-1234-123456789012", + "client_id": "abcdef01-2345-6789-abcd-ef0123456789" + } + }, + "org-private-registry-with-oidc-cloudsmith": { + "summary": "Example of an OIDC private registry configuration using Cloudsmith", + "value": { + "registry_type": "npm_registry", + "url": "https://npm.cloudsmith.io/my-org/my-repo/", + "auth_type": "oidc_cloudsmith", + "visibility": "all", + "namespace": "my-org", + "service_slug": "my-service-account", + "audience": "https://github.com/my-org" + } + }, + "org-private-registry-with-oidc-gcp": { + "summary": "Example of an OIDC private registry configuration using Google Cloud Artifact Registry", + "value": { + "registry_type": "docker_registry", + "url": "https://us-docker.pkg.dev/my-project/my-repo", + "auth_type": "oidc_gcp", + "visibility": "all", + "workload_identity_provider": "projects/123456789/locations/global/workloadIdentityPools/github-pool/providers/github-provider", + "service_account": "dependabot@my-project.iam.gserviceaccount.com" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "The organization private registry configuration", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/org-private-registry-configuration-with-selected-repositories" + }, + "examples": { + "org-private-registry-with-selected-visibility": { + "$ref": "#/components/examples/org-private-registry-configuration" + }, + "org-private-registry-with-private-visibility": { + "$ref": "#/components/examples/org-private-registry-configuration-with-selected-repositories" + } + } + } + } + }, + "404": { + "$ref": "#/components/responses/not_found" + }, + "422": { + "$ref": "#/components/responses/validation_failed" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "private-registries", + "subcategory": "organization-configurations" + } + } + }, + "/orgs/{org}/private-registries/public-key": { + "get": { + "summary": "Get private registries public key for an organization", + "description": "\nGets the org public key, which is needed to encrypt private registry secrets. You need to encrypt a secret before you can create or update secrets.\n\nOAuth tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", + "tags": [ + "private-registries" + ], + "operationId": "private-registries/get-org-public-key", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization" + }, + "parameters": [ + { + "$ref": "#/components/parameters/org" + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "key_id", + "key" + ], + "properties": { + "key_id": { + "description": "The identifier for the key.", + "example": "012345678912345678", + "type": "string" + }, + "key": { + "description": "The Base64 encoded public key.", + "example": "2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234", + "type": "string" + } + } + }, + "examples": { + "default": { + "$ref": "#/components/examples/private-registries-public-key" + } + } + } + }, + "headers": { + "Link": { + "$ref": "#/components/headers/link" + } + } + }, + "404": { + "$ref": "#/components/responses/not_found" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "private-registries", + "subcategory": "organization-configurations" + } + } + }, + "/orgs/{org}/private-registries/{secret_name}": { + "get": { + "summary": "Get a private registry for an organization", + "description": "\nGet the configuration of a single private registry defined for an organization, omitting its encrypted value.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", + "tags": [ + "private-registries" + ], + "operationId": "private-registries/get-org-private-registry", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#get-a-private-registry-for-an-organization" + }, + "parameters": [ + { + "$ref": "#/components/parameters/org" + }, + { + "$ref": "#/components/parameters/secret-name" + } + ], + "responses": { + "200": { + "description": "The specified private registry configuration for the organization", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/org-private-registry-configuration" + }, + "examples": { + "default": { + "$ref": "#/components/examples/org-private-registry-configuration" + } + } + } + } + }, + "404": { + "$ref": "#/components/responses/not_found" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "private-registries", + "subcategory": "organization-configurations" + } + }, + "patch": { + "summary": "Update a private registry for an organization", + "description": "\nUpdates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, `oidc_cloudsmith`, or `oidc_gcp`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", + "tags": [ + "private-registries" + ], + "operationId": "private-registries/update-org-private-registry", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#update-a-private-registry-for-an-organization" + }, + "parameters": [ + { + "$ref": "#/components/parameters/org" + }, + { + "$ref": "#/components/parameters/secret-name" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "registry_type": { + "description": "The registry type.", + "type": "string", + "enum": [ + "maven_repository", + "nuget_feed", + "goproxy_server", + "npm_registry", + "rubygems_server", + "cargo_registry", + "composer_repository", + "docker_registry", + "git_source", + "helm_registry", + "hex_organization", + "hex_repository", + "pub_repository", + "python_index", + "terraform_registry" + ] + }, + "url": { + "description": "The URL of the private registry.", + "type": "string", + "format": "uri" + }, + "username": { + "description": "The username to use when authenticating with the private registry. This field should be omitted if the private registry does not require a username for authentication.", + "type": "string", + "nullable": true + }, + "replaces_base": { + "description": "Whether this private registry should replace the base registry (e.g., npmjs.org for npm, rubygems.org for rubygems). When set to `true`, Dependabot will only use this registry and will not fall back to the public registry. When set to `false` (default), Dependabot will use this registry for scoped packages but may fall back to the public registry for other packages.", + "type": "boolean", + "default": false + }, + "encrypted_value": { + "description": "The value for your secret, encrypted with [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages) using the public key retrieved from the [Get private registries public key for an organization](https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization) endpoint.", + "type": "string", + "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{4})$" + }, + "key_id": { + "description": "The ID of the key you used to encrypt the secret.", + "type": "string" + }, + "visibility": { + "description": "Which type of organization repositories have access to the private registry. `selected` means only the repositories specified by `selected_repository_ids` can access the private registry.", + "type": "string", + "enum": [ + "all", + "private", + "selected" + ] + }, + "selected_repository_ids": { + "description": "An array of repository IDs that can access the organization private registry. You can only provide a list of repository IDs when `visibility` is set to `selected`. This field should be omitted if `visibility` is set to `all` or `private`.", + "type": "array", + "items": { + "type": "integer" + } + }, + "auth_type": { + "description": "The authentication type for the private registry. This field cannot be changed after creation. If provided, it must match the existing `auth_type` of the configuration. To change the authentication type, delete and recreate the configuration.", "type": "string", "enum": [ "token", @@ -40439,7 +43977,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ] }, "tenant_id": { @@ -40475,7 +44014,7 @@ "type": "string" }, "audience": { - "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and required for `oidc_cloudsmith` auth types.", + "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and `oidc_gcp`, and required for `oidc_cloudsmith` auth types.", "type": "string" }, "identity_mapping_name": { @@ -40493,365 +44032,13 @@ "api_host": { "description": "The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default.", "type": "string" - } - }, - "required": [ - "registry_type", - "url", - "visibility" - ] - }, - "examples": { - "org-private-registry-with-private-visibility": { - "summary": "Example of a private registry configuration with private visibility", - "value": { - "registry_type": "maven_repository", - "url": "https://maven.pkg.github.com/organization/", - "username": "monalisa", - "replaces_base": true, - "encrypted_value": "c2VjcmV0", - "key_id": "012345678912345678", - "visibility": "private" - } - }, - "org-private-registry-with-selected-visibility": { - "summary": "Example of a private registry configuration with selected visibility", - "value": { - "registry_type": "maven_repository", - "url": "https://maven.pkg.github.com/organization/", - "username": "monalisa", - "encrypted_value": "c2VjcmV0", - "key_id": "012345678912345678", - "visibility": "selected", - "selected_repository_ids": [ - 1296269, - 1296280 - ] - } - }, - "org-private-registry-with-oidc-azure": { - "summary": "Example of an OIDC private registry configuration using Azure", - "value": { - "registry_type": "docker_registry", - "url": "https://myregistry.azurecr.io", - "auth_type": "oidc_azure", - "visibility": "all", - "tenant_id": "12345678-1234-1234-1234-123456789012", - "client_id": "abcdef01-2345-6789-abcd-ef0123456789" - } - }, - "org-private-registry-with-oidc-cloudsmith": { - "summary": "Example of an OIDC private registry configuration using Cloudsmith", - "value": { - "registry_type": "npm_registry", - "url": "https://npm.cloudsmith.io/my-org/my-repo/", - "auth_type": "oidc_cloudsmith", - "visibility": "all", - "namespace": "my-org", - "service_slug": "my-service-account", - "audience": "https://github.com/my-org" - } - } - } - } - } - }, - "responses": { - "201": { - "description": "The organization private registry configuration", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/org-private-registry-configuration-with-selected-repositories" - }, - "examples": { - "org-private-registry-with-selected-visibility": { - "$ref": "#/components/examples/org-private-registry-configuration" }, - "org-private-registry-with-private-visibility": { - "$ref": "#/components/examples/org-private-registry-configuration-with-selected-repositories" - } - } - } - } - }, - "404": { - "$ref": "#/components/responses/not_found" - }, - "422": { - "$ref": "#/components/responses/validation_failed" - } - }, - "x-github": { - "githubCloudOnly": false, - "enabledForGitHubApps": true, - "category": "private-registries", - "subcategory": "organization-configurations" - } - } - }, - "/orgs/{org}/private-registries/public-key": { - "get": { - "summary": "Get private registries public key for an organization", - "description": "\nGets the org public key, which is needed to encrypt private registry secrets. You need to encrypt a secret before you can create or update secrets.\n\nOAuth tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", - "tags": [ - "private-registries" - ], - "operationId": "private-registries/get-org-public-key", - "externalDocs": { - "description": "API method documentation", - "url": "https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization" - }, - "parameters": [ - { - "$ref": "#/components/parameters/org" - } - ], - "responses": { - "200": { - "description": "Response", - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "key_id", - "key" - ], - "properties": { - "key_id": { - "description": "The identifier for the key.", - "example": "012345678912345678", - "type": "string" - }, - "key": { - "description": "The Base64 encoded public key.", - "example": "2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234", - "type": "string" - } - } - }, - "examples": { - "default": { - "$ref": "#/components/examples/private-registries-public-key" - } - } - } - }, - "headers": { - "Link": { - "$ref": "#/components/headers/link" - } - } - }, - "404": { - "$ref": "#/components/responses/not_found" - } - }, - "x-github": { - "githubCloudOnly": false, - "enabledForGitHubApps": true, - "category": "private-registries", - "subcategory": "organization-configurations" - } - } - }, - "/orgs/{org}/private-registries/{secret_name}": { - "get": { - "summary": "Get a private registry for an organization", - "description": "\nGet the configuration of a single private registry defined for an organization, omitting its encrypted value.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", - "tags": [ - "private-registries" - ], - "operationId": "private-registries/get-org-private-registry", - "externalDocs": { - "description": "API method documentation", - "url": "https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#get-a-private-registry-for-an-organization" - }, - "parameters": [ - { - "$ref": "#/components/parameters/org" - }, - { - "$ref": "#/components/parameters/secret-name" - } - ], - "responses": { - "200": { - "description": "The specified private registry configuration for the organization", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/org-private-registry-configuration" - }, - "examples": { - "default": { - "$ref": "#/components/examples/org-private-registry-configuration" - } - } - } - } - }, - "404": { - "$ref": "#/components/responses/not_found" - } - }, - "x-github": { - "githubCloudOnly": false, - "enabledForGitHubApps": true, - "category": "private-registries", - "subcategory": "organization-configurations" - } - }, - "patch": { - "summary": "Update a private registry for an organization", - "description": "\nUpdates a private registry configuration with an encrypted value for an organization. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). For more information, see \"[Encrypting secrets for the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/encrypting-secrets-for-the-rest-api).\"\nFor OIDC-based registries (`oidc_azure`, `oidc_aws`, `oidc_jfrog`, or `oidc_cloudsmith`), the `encrypted_value` and `key_id` fields should be omitted.\n\nOAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.", - "tags": [ - "private-registries" - ], - "operationId": "private-registries/update-org-private-registry", - "externalDocs": { - "description": "API method documentation", - "url": "https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#update-a-private-registry-for-an-organization" - }, - "parameters": [ - { - "$ref": "#/components/parameters/org" - }, - { - "$ref": "#/components/parameters/secret-name" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "registry_type": { - "description": "The registry type.", - "type": "string", - "enum": [ - "maven_repository", - "nuget_feed", - "goproxy_server", - "npm_registry", - "rubygems_server", - "cargo_registry", - "composer_repository", - "docker_registry", - "git_source", - "helm_registry", - "hex_organization", - "hex_repository", - "pub_repository", - "python_index", - "terraform_registry" - ] - }, - "url": { - "description": "The URL of the private registry.", - "type": "string", - "format": "uri" - }, - "username": { - "description": "The username to use when authenticating with the private registry. This field should be omitted if the private registry does not require a username for authentication.", - "type": "string", - "nullable": true - }, - "replaces_base": { - "description": "Whether this private registry should replace the base registry (e.g., npmjs.org for npm, rubygems.org for rubygems). When set to `true`, Dependabot will only use this registry and will not fall back to the public registry. When set to `false` (default), Dependabot will use this registry for scoped packages but may fall back to the public registry for other packages.", - "type": "boolean", - "default": false - }, - "encrypted_value": { - "description": "The value for your secret, encrypted with [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages) using the public key retrieved from the [Get private registries public key for an organization](https://docs.github.com/enterprise-cloud@latest/rest/private-registries/organization-configurations#get-private-registries-public-key-for-an-organization) endpoint.", - "type": "string", - "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{4})$" - }, - "key_id": { - "description": "The ID of the key you used to encrypt the secret.", - "type": "string" - }, - "visibility": { - "description": "Which type of organization repositories have access to the private registry. `selected` means only the repositories specified by `selected_repository_ids` can access the private registry.", - "type": "string", - "enum": [ - "all", - "private", - "selected" - ] - }, - "selected_repository_ids": { - "description": "An array of repository IDs that can access the organization private registry. You can only provide a list of repository IDs when `visibility` is set to `selected`. This field should be omitted if `visibility` is set to `all` or `private`.", - "type": "array", - "items": { - "type": "integer" - } - }, - "auth_type": { - "description": "The authentication type for the private registry. This field cannot be changed after creation. If provided, it must match the existing `auth_type` of the configuration. To change the authentication type, delete and recreate the configuration.", - "type": "string", - "enum": [ - "token", - "username_password", - "oidc_azure", - "oidc_aws", - "oidc_jfrog", - "oidc_cloudsmith" - ] - }, - "tenant_id": { - "description": "The tenant ID of the Azure AD application. Required when `auth_type` is `oidc_azure`.", - "type": "string" - }, - "client_id": { - "description": "The client ID of the Azure AD application. Required when `auth_type` is `oidc_azure`.", - "type": "string" - }, - "aws_region": { - "description": "The AWS region. Required when `auth_type` is `oidc_aws`.", - "type": "string" - }, - "account_id": { - "description": "The AWS account ID. Required when `auth_type` is `oidc_aws`.", - "type": "string" - }, - "role_name": { - "description": "The AWS IAM role name. Required when `auth_type` is `oidc_aws`.", + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`). Required when `auth_type` is `oidc_gcp`.", "type": "string" }, - "domain": { - "description": "The CodeArtifact domain. Required when `auth_type` is `oidc_aws`.", - "type": "string" - }, - "domain_owner": { - "description": "The CodeArtifact domain owner (AWS account ID). Required when `auth_type` is `oidc_aws`.", - "type": "string" - }, - "jfrog_oidc_provider_name": { - "description": "The JFrog OIDC provider name. Required when `auth_type` is `oidc_jfrog`.", - "type": "string" - }, - "audience": { - "description": "The OIDC audience. Optional for `oidc_aws`, `oidc_jfrog`, and required for `oidc_cloudsmith` auth types.", - "type": "string" - }, - "identity_mapping_name": { - "description": "The JFrog identity mapping name. Optional for `oidc_jfrog` auth type.", - "type": "string" - }, - "namespace": { - "description": "The Cloudsmith organization namespace. Required when `auth_type` is `oidc_cloudsmith`.", - "type": "string" - }, - "service_slug": { - "description": "The Cloudsmith service account slug. Required when `auth_type` is `oidc_cloudsmith`.", - "type": "string" - }, - "api_host": { - "description": "The Cloudsmith API host. Optional for `oidc_cloudsmith` auth type. If omitted, `api.cloudsmith.io` is used by default.", + "service_account": { + "description": "The GCP service account email to impersonate. Optional for `oidc_gcp` auth type. If omitted, the federated token is used directly (direct WIF).", "type": "string" } } @@ -47960,6 +51147,139 @@ } } }, + "/repos/{owner}/{repo}/actions/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a repository", + "description": "Lists the active concurrency groups for a repository.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository" + }, + "parameters": [ + { + "$ref": "#/components/parameters/owner" + }, + { + "$ref": "#/components/parameters/repo" + }, + { + "$ref": "#/components/parameters/per-page" + }, + { + "$ref": "#/components/parameters/pagination-after" + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/concurrency-group-list" + }, + "examples": { + "default": { + "$ref": "#/components/examples/concurrency-group-list" + } + } + } + }, + "headers": { + "Link": { + "$ref": "#/components/headers/link" + } + } + }, + "422": { + "$ref": "#/components/responses/validation_failed" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": { + "get": { + "summary": "Get a concurrency group for a repository", + "description": "Gets a specific concurrency group for a repository, including all instances in the group's queue.\nReturns 404 if the group is inactive or does not exist.\n\nOptionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items\nahead of the specified workflow run or job in the queue, plus the specified item itself\n(returned as the last element). This is useful for determining what is blocking a particular\nrun or job. Returns 422 if the specified run or job is not in this concurrency group.\n\nWhen using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow\nleases held on behalf of that run. Job-level leases within the run are not considered to\nblock the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow\nleases on the job's ancestor paths.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/get-concurrency-group-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository" + }, + "parameters": [ + { + "$ref": "#/components/parameters/owner" + }, + { + "$ref": "#/components/parameters/repo" + }, + { + "$ref": "#/components/parameters/concurrency-group-name" + }, + { + "name": "ahead_of_run", + "description": "Filter to items ahead of this workflow run ID in the queue, plus the run itself.\nMatches workflow-level concurrency and reusable-workflow leases held on behalf of\nthe run. Mutually exclusive with `ahead_of_job`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + }, + { + "name": "ahead_of_job", + "description": "Filter to items ahead of this job ID in the queue, plus the job itself.\nMatches job-level concurrency and reusable-workflow leases on the job's\nancestor paths. Mutually exclusive with `ahead_of_run`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/concurrency-group" + }, + "examples": { + "default": { + "$ref": "#/components/examples/concurrency-group" + } + } + } + } + }, + "404": { + "$ref": "#/components/responses/not_found" + }, + "422": { + "$ref": "#/components/responses/validation_failed" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/jobs/{job_id}": { "get": { "summary": "Get a job for a workflow run", @@ -50371,6 +53691,74 @@ } } }, + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a workflow run", + "description": "Lists all concurrency groups associated with a workflow run or its jobs.\n\nThe set of groups is derived from the run's configuration, so a group is\nincluded even when the run no longer has any items currently holding or\nwaiting in it. In that case the `group_members` array will be empty.\n`total_count` reflects the number of groups the run participates in by\nconfiguration, not the number with active items.\n\nThis differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`,\nwhich returns 404 when a group has no active items. That endpoint reports\nthe live state of a group repo-wide, while this endpoint reports the\ngroups associated with a specific run by configuration.\n\nResults are sorted by group name and support cursor-based pagination via\n`before` and `after`. The `after` cursor paginates forward only and does\nnot emit a `rel=\"prev\"` Link; use `before` to page backward from a\nforward page's `next` cursor.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-workflow-run", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run" + }, + "parameters": [ + { + "$ref": "#/components/parameters/owner" + }, + { + "$ref": "#/components/parameters/repo" + }, + { + "$ref": "#/components/parameters/run-id" + }, + { + "$ref": "#/components/parameters/per-page" + }, + { + "$ref": "#/components/parameters/pagination-before" + }, + { + "$ref": "#/components/parameters/pagination-after" + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/concurrency-group-run-list" + }, + "examples": { + "default": { + "$ref": "#/components/examples/concurrency-group-run-list" + } + } + } + }, + "headers": { + "Link": { + "$ref": "#/components/headers/link" + } + } + }, + "404": { + "$ref": "#/components/responses/not_found" + }, + "422": { + "$ref": "#/components/responses/validation_failed" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": { "post": { "summary": "Review custom deployment protection rules for a workflow run", @@ -147016,7 +150404,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ], "type": "string" }, @@ -147097,6 +150486,14 @@ "description": "The Cloudsmith API host.", "type": "string" }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`).", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. If omitted, the federated token is used directly (direct WIF).", + "type": "string" + }, "created_at": { "type": "string", "format": "date-time" @@ -147153,7 +150550,8 @@ "oidc_azure", "oidc_aws", "oidc_jfrog", - "oidc_cloudsmith" + "oidc_cloudsmith", + "oidc_gcp" ], "type": "string" }, @@ -147240,6 +150638,14 @@ "description": "The Cloudsmith API host.", "type": "string" }, + "workload_identity_provider": { + "description": "The full resource name of the GCP Workload Identity Provider (e.g. `projects//locations/global/workloadIdentityPools//providers/`).", + "type": "string" + }, + "service_account": { + "description": "The GCP service account email to impersonate. If omitted, the federated token is used directly (direct WIF).", + "type": "string" + }, "created_at": { "type": "string", "format": "date-time" @@ -151995,6 +155401,134 @@ "actions_caches" ] }, + "concurrency-group-list": { + "title": "Concurrency Group List", + "description": "A list of active concurrency groups for a repository.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer" + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "last_acquired_at" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "last_acquired_at": { + "type": "string", + "format": "date-time", + "nullable": true + } + } + } + } + } + }, + "concurrency-group": { + "title": "Concurrency Group", + "description": "A concurrency group with the workflow runs and jobs that are either currently holding\nor waiting for the concurrency group lease.", + "type": "object", + "required": [ + "group_name", + "group_url", + "total_count", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "total_count": { + "type": "integer" + }, + "group_members": { + "type": "array", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": "string", + "format": "uri", + "description": "API URL for the workflow run.", + "nullable": true + }, + "run_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the workflow run.", + "nullable": true + }, + "job_id": { + "type": "integer", + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_name": { + "type": "string", + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_url": { + "type": "string", + "format": "uri", + "description": "API URL for the job.", + "nullable": true + }, + "job_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the job.", + "nullable": true + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + }, "job": { "title": "Job", "description": "Information of a job execution in a workflow run", @@ -152730,6 +156264,119 @@ "comment" ] }, + "concurrency-group-run-list": { + "title": "Concurrency Group Run List", + "description": "A list of concurrency groups associated with a workflow run.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer", + "description": "The total number of concurrency groups this workflow run participates in,\nderived from the run's configuration. This count is not filtered by\nwhether the run currently holds or is waiting in each group, so it can\ninclude groups whose `group_members` array is empty (for example, when\nthe run has already released its lease in that group)." + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group. May return 404 if the group\nhas no active items at the time it is requested, since the\nget-by-name endpoint reports the live repo-wide state of a group\nwhile this endpoint lists groups associated with a run by\nconfiguration." + }, + "group_members": { + "type": "array", + "description": "Items belonging to this workflow run that are either currently holding or\nwaiting for the concurrency group lease. May be empty if the run no\nlonger has any active or queued items in this group.", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status", + "position", + "position_url" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": "string", + "format": "uri", + "description": "API URL for the workflow run.", + "nullable": true + }, + "run_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the workflow run.", + "nullable": true + }, + "position": { + "type": "integer", + "description": "Queue position. 0 means the item holds the concurrency lease (in_progress), 1 or higher means queued (pending)." + }, + "position_url": { + "type": "string", + "format": "uri", + "description": "API URL to get items ahead of this item in the concurrency group." + }, + "job_id": { + "type": "integer", + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease.", + "nullable": true + }, + "job_name": { + "type": "string", + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease.", + "nullable": true + }, + "job_url": { + "type": "string", + "format": "uri", + "description": "API URL for the job.", + "nullable": true + }, + "job_html_url": { + "type": "string", + "format": "uri", + "description": "Web URL for the job.", + "nullable": true + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + } + } + } + }, "review-custom-gates-comment-required": { "type": "object", "properties": { @@ -330488,6 +334135,57 @@ ] } }, + "concurrency-group-list": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "last_acquired_at": "2026-01-15T16:14:23Z" + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "last_acquired_at": "2026-01-15T16:13:55Z" + } + ] + } + }, + "concurrency-group": { + "value": { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "total_count": 3, + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/{"code":"deadline_exceeded","msg":"operation timed out"}