> ## Documentation Index > Fetch the complete documentation index at: https://docs.runaether.dev/llms.txt > Use this file to discover all available pages before exploring further. # Save a task to GitHub > Gives a task with no repository one: the project gains the repository the body names (created under an installation's account, picked, or the project's own), the task is bound to it, and its workspace gives the task's history a home there: as the repository's first history when it has none, else replayed onto its default branch, with a conflict left to the agent (the outcome says which). A step a previous save completed is skipped; a retry resumes at the one that failed. Use this tool when you need to: - Give the work of a task in a project with no repository a GitHub repository Examples: - POST /tasks/{taskID}/repository {"kind": "create", "installation_id": 12345678, "name": "weather-app", "private": true} Hints: - taskID is the task's uuid. - Use downloadTask instead to take the work out as a zip without GitHub. - Restricted to the task's creator or an admin or owner of its organization, through a web session, an API key or an agent host's grant, each acting as its user: another member is refused with 403 control_forbidden, a viewer or billing member with 403 org_role_insufficient, and a task the caller cannot see is 404. - Only the task's creator saves with kind create or pick, since the save reaches GitHub as them; anyone else saves with kind project into the project's repository, and a create or pick is refused with 409 save_requires_task_creator, naming the creator. - Refused for the task with 409 task_is_child (a child leaves through downloadTask), task_bound_at_creation, task_already_saved, task_not_started, task_creator_deleted, project_archived or workspace_gone, and then task_executing (save once the agent's turn ends) or save_in_progress (another save of the task is running). - Refused for the workspace's history before anything is created or linked with 409 task_has_no_commits, task_branch_mismatch, task_rebase_in_progress (the agent finishes the rebase first) or task_file_too_large (a file over GitHub's 100 MB limit, named). - Refused for the repository with 409 project_repository_differs or project_has_no_repository when the body does not match the project's repository, 409 repository_administration_not_granted, repository_owner_not_caller, repository_create_rejected or repository_create_forbidden for GitHub's refusals of the create, 409 repository_created_not_linked, naming the repository, when the project's link to the repository the save created fails (pick it to finish), 409 repository_already_connected for a repository another project holds, 409 project_repo_disconnected for a project whose GitHub link is disconnected, 409 task_branch_is_default for a task branch named as the default branch, refused before a created or picked repository is linked (a repository the save created is named and left unlinked), 400 naming the default branch of a picked repository whose default branch has surrounding whitespace, 502 naming a repository GitHub created but answered with nothing the project can link (or saying its answer did not name the repository), 409 creator_github_access_missing when the creator's GitHub access does not reach the repository (or must be reconnected, for a saver who is not the creator), and 409 github_reconnect_required for a creator who must reconnect GitHub. - Refused for the push or the replay with 409 working_tree_dirty (uncommitted changes a replay onto the repository's history would disturb), task_history_has_merges, task_branch_diverged, push_file_too_large, push_secret_detected or push_rejected, with GitHub's words; a step already done stays done. - 502 when GitHub fails to answer and 503 when the workspace cannot be started. ## OpenAPI ````yaml api-reference/openapi.json POST /tasks/{taskID}/repository openapi: 3.1.0 info: title: Aether API version: 0.1.0 servers: - url: https://api.runaether.dev security: - bearerAuth: [] paths: /tasks/{taskID}/repository: post: tags: - tasks summary: Save a task to GitHub description: >- Gives a task with no repository one: the project gains the repository the body names (created under an installation's account, picked, or the project's own), the task is bound to it, and its workspace gives the task's history a home there: as the repository's first history when it has none, else replayed onto its default branch, with a conflict left to the agent (the outcome says which). A step a previous save completed is skipped; a retry resumes at the one that failed. Use this tool when you need to: - Give the work of a task in a project with no repository a GitHub repository Examples: - POST /tasks/{taskID}/repository {"kind": "create", "installation_id": 12345678, "name": "weather-app", "private": true} Hints: - taskID is the task's uuid. - Use downloadTask instead to take the work out as a zip without GitHub. - Restricted to the task's creator or an admin or owner of its organization, through a web session, an API key or an agent host's grant, each acting as its user: another member is refused with 403 control_forbidden, a viewer or billing member with 403 org_role_insufficient, and a task the caller cannot see is 404. - Only the task's creator saves with kind create or pick, since the save reaches GitHub as them; anyone else saves with kind project into the project's repository, and a create or pick is refused with 409 save_requires_task_creator, naming the creator. - Refused for the task with 409 task_is_child (a child leaves through downloadTask), task_bound_at_creation, task_already_saved, task_not_started, task_creator_deleted, project_archived or workspace_gone, and then task_executing (save once the agent's turn ends) or save_in_progress (another save of the task is running). - Refused for the workspace's history before anything is created or linked with 409 task_has_no_commits, task_branch_mismatch, task_rebase_in_progress (the agent finishes the rebase first) or task_file_too_large (a file over GitHub's 100 MB limit, named). - Refused for the repository with 409 project_repository_differs or project_has_no_repository when the body does not match the project's repository, 409 repository_administration_not_granted, repository_owner_not_caller, repository_create_rejected or repository_create_forbidden for GitHub's refusals of the create, 409 repository_created_not_linked, naming the repository, when the project's link to the repository the save created fails (pick it to finish), 409 repository_already_connected for a repository another project holds, 409 project_repo_disconnected for a project whose GitHub link is disconnected, 409 task_branch_is_default for a task branch named as the default branch, refused before a created or picked repository is linked (a repository the save created is named and left unlinked), 400 naming the default branch of a picked repository whose default branch has surrounding whitespace, 502 naming a repository GitHub created but answered with nothing the project can link (or saying its answer did not name the repository), 409 creator_github_access_missing when the creator's GitHub access does not reach the repository (or must be reconnected, for a saver who is not the creator), and 409 github_reconnect_required for a creator who must reconnect GitHub. - Refused for the push or the replay with 409 working_tree_dirty (uncommitted changes a replay onto the repository's history would disturb), task_history_has_merges, task_branch_diverged, push_file_too_large, push_secret_detected or push_rejected, with GitHub's words; a step already done stays done. - 502 when GitHub fails to answer and 503 when the workspace cannot be started. operationId: saveTaskRepository parameters: - in: path name: taskID required: true schema: format: uuid pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/SaveTaskRepositoryRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/SaveTaskRepositoryResponse' description: OK '400': content: application/json: schema: $ref: '#/components/schemas/TasksErrorResponse' description: Bad Request '401': content: application/json: schema: $ref: '#/components/schemas/TasksErrorResponse' description: Unauthorized '403': content: application/json: schema: anyOf: - $ref: '#/components/schemas/TasksErrorResponse' - $ref: '#/components/schemas/OrgAuthorizationErrorResponse' - $ref: '#/components/schemas/ControlForbiddenErrorResponse' description: Forbidden '404': content: application/json: schema: $ref: '#/components/schemas/TasksErrorResponse' description: Not Found '409': content: application/json: schema: $ref: '#/components/schemas/TasksErrorResponse' description: Conflict '422': content: application/json: schema: $ref: '#/components/schemas/TasksErrorResponse' description: Unprocessable Entity '500': content: application/json: schema: $ref: '#/components/schemas/TasksErrorResponse' description: Internal Server Error '502': content: application/json: schema: $ref: '#/components/schemas/TasksErrorResponse' description: Bad Gateway '503': content: application/json: schema: $ref: '#/components/schemas/TasksErrorResponse' description: Service Unavailable components: schemas: SaveTaskRepositoryRequest: discriminator: mapping: create: '#/components/schemas/SaveTaskRepositoryCreate' pick: '#/components/schemas/SaveTaskRepositoryPick' project: '#/components/schemas/SaveTaskRepositoryProject' propertyName: kind oneOf: - $ref: '#/components/schemas/SaveTaskRepositoryCreate' - $ref: '#/components/schemas/SaveTaskRepositoryPick' - $ref: '#/components/schemas/SaveTaskRepositoryProject' SaveTaskRepositoryResponse: additionalProperties: false properties: binding: $ref: '#/components/schemas/TaskRepositoryBinding' outcome: $ref: '#/components/schemas/SaveTaskRepositoryOutcome' repository: $ref: '#/components/schemas/ProjectRepository' required: - repository - binding - outcome type: object TasksErrorResponse: additionalProperties: false properties: code: enum: - account_deleting - aether_inference_unserved - agent_pr_blocked - agent_pr_pending - agent_profile_changed - app_identity_missing - attribution_unavailable - bad_gateway - bad_request - caller_inactive - conflict - connection_harness_mismatch - connection_not_held - contents_write_required - continuation_failed - continuation_unavailable - control_forbidden - creator_github_access_missing - embeddings_unavailable - fix_not_requested - fix_requests_unrecorded - forbidden - fork_branch_delete_unsupported - fork_forbidden - gateway_timeout - github_claim_unverified - github_failed - github_identity_mismatch - github_identity_required - github_push_access_required - github_reconnect_required - github_ref_not_found - gone - handed_branch_protected - idempotency_key_reused - inference_proxy_unavailable - insufficient_credits - insufficient_inference_balance - internal_error - invalid_request - mcp_server_not_connected - message_not_queued - method_not_allowed - mode_forbidden - no_dispatch_target - not_acceptable - not_found - not_implemented - onboarding_already_completed - onboarding_requirements_missing - org_role_insufficient - org_suspended - payment_required - pr_review_actor_required - pr_review_publish_forbidden - precondition_failed - project_archived - project_has_no_repository - project_repo_disconnected - project_repository_differs - pull_request_closed - pull_request_mirror_failed - pull_request_not_mirrored - push_file_too_large - push_rejected - push_secret_detected - queued_stop_requires_discard - rate_limited - repository_administration_not_granted - repository_already_connected - repository_create_forbidden - repository_create_rejected - repository_created_not_linked - repository_owner_not_caller - request_canceled - request_timeout - request_too_large - save_in_progress - save_requires_task_creator - service_unavailable - stack_cycle - stack_too_large - stack_two_parents - stale_execution - stale_or_indeterminate - stale_pending_input - stream_delivery_gap - stream_event_conflict - task_already_saved - task_awaiting_message - task_awaiting_tool_response - task_bound_at_creation - task_branch_diverged - task_branch_is_default - task_branch_mismatch - task_branch_missing - task_connection_disconnected - task_creator_deleted - task_executing - task_file_too_large - task_has_no_commits - task_has_no_files - task_has_no_repository - task_history_has_merges - task_ineligible - task_is_child - task_not_accepting_messages - task_not_pinnable - task_not_started - task_rebase_in_progress - task_settings_changed - teleport_unavailable - unauthenticated - unsigned_aether_head - unsigned_commit - unsupported_changes - unsupported_media_type - untyped_error - validation_failed - working_tree_dirty - workspace_git_unavailable - workspace_gone - workspace_outdated - workspace_rejected minLength: 1 type: string error: minLength: 1 type: string errors: items: $ref: '#/components/schemas/ErrorDetail' type: array required: - error - code type: object OrgAuthorizationErrorResponse: additionalProperties: false properties: code: enum: - org_membership_required - org_role_insufficient - org_suspended - account_deleting - agent_host_route_not_allowed - credential_kind_not_admitted type: string error: minLength: 1 type: string required: - error - code type: object ControlForbiddenErrorResponse: additionalProperties: false properties: code: enum: - control_forbidden type: string error: minLength: 1 type: string required: - error - code type: object SaveTaskRepositoryCreate: additionalProperties: false properties: installation_id: format: int64 minimum: 1 type: integer kind: enum: - create type: string name: maxLength: 100 minLength: 1 pattern: ^[A-Za-z0-9_.-]+$ type: string private: type: boolean required: - kind - installation_id - name - private type: object SaveTaskRepositoryPick: additionalProperties: false properties: installation_id: format: int64 minimum: 1 type: integer kind: enum: - pick type: string repo_url: minLength: 1 type: string required: - kind - installation_id - repo_url type: object SaveTaskRepositoryProject: additionalProperties: false properties: kind: enum: - project type: string required: - kind type: object TaskRepositoryBinding: additionalProperties: false properties: base_branch: minLength: 1 pattern: \S type: string bound_at: format: date-time type: string required: - base_branch - bound_at type: object SaveTaskRepositoryOutcome: discriminator: mapping: published: '#/components/schemas/SaveTaskRepositoryPublished' rebase_conflict: '#/components/schemas/SaveTaskRepositoryRebaseConflict' propertyName: kind oneOf: - $ref: '#/components/schemas/SaveTaskRepositoryPublished' - $ref: '#/components/schemas/SaveTaskRepositoryRebaseConflict' ProjectRepository: additionalProperties: false description: >- A project's one linked GitHub repository: its identity and the state of the link that reaches it. properties: default_branch: minLength: 1 pattern: \S type: string github_repo_id: format: int64 maximum: 9007199254740991 minimum: 1 type: integer link: $ref: '#/components/schemas/ProjectRepositoryLink' name: minLength: 1 pattern: \S type: string owner: minLength: 1 pattern: \S type: string url: minLength: 1 pattern: \S type: string required: - url - owner - name - github_repo_id - default_branch - link type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object SaveTaskRepositoryPublished: additionalProperties: false properties: head_sha: pattern: ^[0-9a-f]{40}$ type: string kind: enum: - published type: string rebased: type: boolean uncommitted_changes: type: boolean required: - kind - head_sha - rebased - uncommitted_changes type: object SaveTaskRepositoryRebaseConflict: additionalProperties: false properties: default_branch: minLength: 1 type: string kind: enum: - rebase_conflict type: string required: - kind - default_branch type: object ProjectRepositoryLink: description: >- The link state: connected through the installation that reaches the repository, or disconnected while the repository identity is kept. discriminator: mapping: connected: '#/components/schemas/ProjectRepositoryLinkConnected' disconnected: '#/components/schemas/ProjectRepositoryLinkDisconnected' propertyName: state oneOf: - $ref: '#/components/schemas/ProjectRepositoryLinkConnected' - $ref: '#/components/schemas/ProjectRepositoryLinkDisconnected' ProjectRepositoryLinkConnected: additionalProperties: false properties: installation_id: format: int64 maximum: 9007199254740991 minimum: 1 type: integer state: enum: - connected type: string required: - state - installation_id type: object ProjectRepositoryLinkDisconnected: additionalProperties: false properties: state: enum: - disconnected type: string required: - state type: object securitySchemes: bearerAuth: bearerFormat: JWT scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.