Forgejo repository API
The repository API from Forgejo — 126 operation(s) for repository.
The repository API from Forgejo — 126 operation(s) for repository.
swagger: '2.0'
info:
description: This documentation describes the Forgejo API.
title: Forgejo activitypub repository API
license:
name: This file is distributed under the MIT license for the purpose of interoperability
url: http://opensource.org/licenses/MIT
version: 16.0.0-dev-465-4b83448b7d+gitea-1.22.0
basePath: /api/v1
schemes:
- https
- http
consumes:
- application/json
- text/plain
produces:
- application/json
- text/html
security:
- BasicAuth: []
- AuthorizationHeaderToken: []
- SudoParam: []
- SudoHeader: []
- TOTPHeader: []
tags:
- name: repository
paths:
/repos/migrate:
post:
consumes:
- application/json
produces:
- application/json
tags:
- repository
summary: Migrate a remote git repository
operationId: repoMigrate
parameters:
- name: body
in: body
schema:
$ref: '#/definitions/MigrateRepoOptions'
responses:
'201':
$ref: '#/responses/Repository'
'403':
$ref: '#/responses/forbidden'
'409':
description: The repository with the same name already exists.
'413':
$ref: '#/responses/quotaExceeded'
'422':
$ref: '#/responses/validationError'
/repos/search:
get:
produces:
- application/json
tags:
- repository
summary: Search for repositories
operationId: repoSearch
parameters:
- type: string
description: keyword
name: q
in: query
- type: boolean
description: Limit search to repositories with keyword as topic
name: topic
in: query
- type: boolean
description: include search of keyword within repository description
name: includeDesc
in: query
- type: integer
format: int64
description: search only for repos that the user with the given id owns or contributes to
name: uid
in: query
- type: integer
format: int64
description: repo owner to prioritize in the results
name: priority_owner_id
in: query
- type: integer
format: int64
description: search only for repos that belong to the given team id
name: team_id
in: query
- type: integer
format: int64
description: search only for repos that the user with the given id has starred
name: starredBy
in: query
- type: boolean
description: include private repositories this user has access to (defaults to true)
name: private
in: query
- type: boolean
description: show only public, private or all repositories (defaults to all)
name: is_private
in: query
- type: boolean
description: include template repositories this user has access to (defaults to true)
name: template
in: query
- type: boolean
description: show only archived, non-archived or all repositories (defaults to all)
name: archived
in: query
- type: string
description: type of repository to search for. Supported values are "fork", "source", "mirror" and "collaborative"
name: mode
in: query
- type: boolean
description: if `uid` is given, search only for repos that the user owns
name: exclusive
in: query
- enum:
- alpha
- created
- updated
- size
- git_size
- lfs_size
- id
- stars
- forks
type: string
description: sort repos by attribute. Supported values are "alpha", "created", "updated", "size", "git_size", "lfs_size", "stars", "forks" and "id". Default is "alpha"
name: sort
in: query
- enum:
- asc
- desc
type: string
description: sort order, either "asc" (ascending) or "desc" (descending). Default is "asc", ignored if "sort" is not specified.
name: order
in: query
- type: integer
description: page number of results to return (1-based)
name: page
in: query
- type: integer
description: page size of results
name: limit
in: query
responses:
'200':
$ref: '#/responses/SearchResults'
'422':
$ref: '#/responses/validationError'
/repos/{owner}/{repo}:
get:
produces:
- application/json
tags:
- repository
summary: Get a repository
operationId: repoGet
parameters:
- type: string
description: owner of the repo
name: owner
in: path
required: true
- type: string
description: name of the repo
name: repo
in: path
required: true
responses:
'200':
$ref: '#/responses/Repository'
'404':
$ref: '#/responses/notFound'
delete:
produces:
- application/json
tags:
- repository
summary: Delete a repository
operationId: repoDelete
parameters:
- type: string
description: owner of the repo to delete
name: owner
in: path
required: true
- type: string
description: name of the repo to delete
name: repo
in: path
required: true
responses:
'204':
$ref: '#/responses/empty'
'403':
$ref: '#/responses/forbidden'
'404':
$ref: '#/responses/notFound'
patch:
produces:
- application/json
tags:
- repository
summary: Edit a repository's properties. Only fields that are set will be changed.
operationId: repoEdit
parameters:
- type: string
description: owner of the repo to edit
name: owner
in: path
required: true
- type: string
description: name of the repo to edit
name: repo
in: path
required: true
- description: Properties of a repo that you can edit
name: body
in: body
schema:
$ref: '#/definitions/EditRepoOption'
responses:
'200':
$ref: '#/responses/Repository'
'403':
$ref: '#/responses/forbidden'
'404':
$ref: '#/responses/notFound'
'422':
$ref: '#/responses/validationError'
/repos/{owner}/{repo}/actions/artifacts:
get:
produces:
- application/json
tags:
- repository
summary: List a repository's artifacts
operationId: ListActionArtifacts
parameters:
- type: string
description: owner of the repo
name: owner
in: path
required: true
- type: string
description: name of the repo
name: repo
in: path
required: true
- type: string
description: filter by artifact name
name: name
in: query
- type: integer
description: page number of results to return (1-based)
name: page
in: query
- type: integer
description: page size of results, default maximum page size is 50
name: limit
in: query
responses:
'200':
$ref: '#/responses/ActionArtifactList'
'400':
$ref: '#/responses/error'
'403':
$ref: '#/responses/forbidden'
/repos/{owner}/{repo}/actions/artifacts/{artifact_id}:
get:
produces:
- application/json
tags:
- repository
summary: Get an artifact by ID
operationId: GetActionArtifact
parameters:
- type: string
description: owner of the repo
name: owner
in: path
required: true
- type: string
description: name of the repo
name: repo
in: path
required: true
- type: integer
format: int64
description: ID of the artifact
name: artifact_id
in: path
required: true
responses:
'200':
$ref: '#/responses/ActionArtifact'
'400':
$ref: '#/responses/error'
'403':
$ref: '#/responses/forbidden'
'404':
$ref: '#/responses/notFound'
delete:
description: 'Marks the artifact for deletion. Storage space will be reclaimed
asynchronously by a background job.
'
tags:
- repository
summary: Mark an artifact for deletion
operationId: DeleteActionArtifact
parameters:
- type: string
description: owner of the repo
name: owner
in: path
required: true
- type: string
description: name of the repo
name: repo
in: path
required: true
- type: integer
format: int64
description: ID of the artifact
name: artifact_id
in: path
required: true
responses:
'204':
description: artifact marked for deletion
'400':
$ref: '#/responses/error'
'403':
$ref: '#/responses/forbidden'
'404':
$ref: '#/responses/notFound'
/repos/{owner}/{repo}/actions/artifacts/{artifact_id}/zip:
get:
produces:
- application/zip
tags:
- repository
summary: Download an artifact
operationId: DownloadActionArtifact
parameters:
- type: string
description: owner of the repo
name: owner
in: path
required: true
- type: string
description: name of the repo
name: repo
in: path
required: true
- type: integer
format: int64
description: ID of the artifact
name: artifact_id
in: path
required: true
responses:
'200':
description: the artifact archive
'400':
$ref: '#/responses/error'
'403':
$ref: '#/responses/forbidden'
'404':
$ref: '#/responses/notFound'
/repos/{owner}/{repo}/actions/jobs/{job_id}/logs:
get:
description: 'Returns the plaintext log for the job. By default the log for the most recent attempt is returned (ActionRunJob.TaskID tracks the latest task). Pass `?attempt=N` to fetch the log for a specific historical attempt; the value matches the `attempt` field returned by the job listing endpoints.
'
produces:
- text/plain
tags:
- repository
summary: Download the plaintext logs of an action job
operationId: repoGetActionJobLogs
parameters:
- type: string
description: owner of the repo
name: owner
in: path
required: true
- type: string
description: name of the repo
name: repo
in: path
required: true
- type: integer
format: int64
description: ID of the workflow job
name: job_id
in: path
required: true
- type: integer
format: int64
description: 1-based attempt number matching the value of `attempt` in the job listing; omit to fetch the latest attempt of the job
name: attempt
in: query
responses:
'200':
description: Plaintext log content
schema:
type: string
'206':
description: Partial log content (Range request)
schema:
type: string
'401':
$ref: '#/responses/unauthorized'
'403':
$ref: '#/responses/forbidden'
'404':
$ref: '#/responses/notFound'
/repos/{owner}/{repo}/actions/runners:
get:
produces:
- application/json
tags:
- repository
summary: Get runners belonging to the repository
operationId: getRepoRunners
parameters:
- type: string
description: owner of the repo
name: owner
in: path
required: true
- type: string
description: name of the repo
name: repo
in: path
required: true
- type: boolean
description: whether to include all visible runners (true) or only those that are directly owned by the repository (false)
name: visible
in: query
- type: integer
description: page number of results to return (1-based)
name: page
in: query
- type: integer
description: page size of results
name: limit
in: query
responses:
'200':
$ref: '#/responses/ActionRunnerList'
'400':
$ref: '#/responses/error'
'404':
$ref: '#/responses/notFound'
post:
consumes:
- application/json
produces:
- application/json
tags:
- repository
summary: Register a new repository-level runner
operationId: registerRepoRunner
parameters:
- type: string
description: owner of the repo
name: owner
in: path
required: true
- type: string
description: name of the repo
name: repo
in: path
required: true
- name: body
in: body
schema:
$ref: '#/definitions/RegisterRunnerOptions'
responses:
'201':
$ref: '#/responses/RegisterRunnerResponse'
'400':
$ref: '#/responses/error'
'401':
$ref: '#/responses/unauthorized'
'404':
$ref: '#/responses/notFound'
/repos/{owner}/{repo}/actions/runners/jobs:
get:
produces:
- application/json
tags:
- repository
summary: Search for repository's action jobs according filter conditions
operationId: repoSearchRunJobs
parameters:
- type: string
description: owner of the repo
name: owner
in: path
required: true
- type: string
description: name of the repo
name: repo
in: path
required: true
- type: string
description: a comma separated list of run job labels to search for
name: labels
in: query
responses:
'200':
$ref: '#/responses/RunJobList'
'403':
$ref: '#/responses/forbidden'
/repos/{owner}/{repo}/actions/runners/registration-token:
get:
description: 'This operation has been deprecated in Forgejo 15. Use the web UI or [`/repos/{owner}/{repo}/actions/runners`](#/repository/registerRepoRunner) instead.
'
produces:
- application/json
tags:
- repository
summary: Get a repository's runner registration token
operationId: repoGetRunnerRegistrationToken
deprecated: true
parameters:
- type: string
description: owner of the repo
name: owner
in: path
required: true
- type: string
description: name of the repo
name: repo
in: path
required: true
responses:
'200':
$ref: '#/responses/RegistrationToken'
/repos/{owner}/{repo}/actions/runners/{runner_id}:
get:
produces:
- application/json
tags:
- repository
summary: Get a particular runner that belongs to the repository
operationId: getRepoRunner
parameters:
- type: string
description: owner of the repo
name: owner
in: path
required: true
- type: string
description: name of the repo
name: repo
in: path
required: true
- type: string
description: ID of the runner
name: runner_id
in: path
required: true
responses:
'200':
$ref: '#/responses/ActionRunner'
'400':
$ref: '#/responses/error'
'404':
$ref: '#/responses/notFound'
delete:
produces:
- application/json
tags:
- repository
summary: Delete a particular runner that belongs to a repository
operationId: deleteRepoRunner
parameters:
- type: string
description: owner of the repo
name: owner
in: path
required: true
- type: string
description: name of the repo
name: repo
in: path
required: true
- type: string
description: ID of the runner
name: runner_id
in: path
required: true
responses:
'204':
description: runner has been deleted
'400':
$ref: '#/responses/error'
'404':
$ref: '#/responses/notFound'
/repos/{owner}/{repo}/actions/runs:
get:
produces:
- application/json
tags:
- repository
summary: List a repository's action runs
operationId: ListActionRuns
parameters:
- type: string
description: owner of the repo
name: owner
in: path
required: true
- type: string
description: name of the repo
name: repo
in: path
required: true
- type: integer
description: page number of results to return (1-based)
name: page
in: query
- type: integer
description: page size of results, default maximum page size is 50
name: limit
in: query
- type: array
items:
type: string
description: Returns workflow run triggered by the specified events. For example, `push`, `pull_request` or `workflow_dispatch`.
name: event
in: query
- type: array
items:
enum:
- unknown
- waiting
- running
- success
- failure
- cancelled
- skipped
- blocked
type: string
description: 'Returns workflow runs with the check run status or conclusion that is specified. For example, a conclusion can be success or a status can be in_progress. Only Forgejo Actions can set a status of waiting, pending, or requested.
'
name: status
in: query
- type: integer
format: int64
description: 'Returns the workflow run associated with the run number.
'
name: run_number
in: query
- type: string
description: Only returns workflow runs that are associated with the specified head_sha.
name: head_sha
in: query
- type: string
description: Only return workflow runs that involve the given Git reference, for example, `refs/heads/main`.
name: ref
in: query
- type: string
description: Only return workflow runs that involve the given workflow ID.
name: workflow_id
in: query
responses:
'200':
$ref: '#/responses/ActionRunList'
'400':
$ref: '#/responses/error'
'403':
$ref: '#/responses/forbidden'
/repos/{owner}/{repo}/actions/runs/{run_id}:
get:
produces:
- application/json
tags:
- repository
summary: Get an action run
operationId: ActionRun
parameters:
- type: string
description: owner of the repo
name: owner
in: path
required: true
- type: string
description: name of the repo
name: repo
in: path
required: true
- type: integer
format: int64
description: id of the action run
name: run_id
in: path
required: true
responses:
'200':
$ref: '#/responses/ActionRun'
'400':
$ref: '#/responses/error'
'403':
$ref: '#/responses/forbidden'
'404':
$ref: '#/responses/notFound'
delete:
description: 'Remove a particular workflow run. The workflow run must have completed (succeeded, failed, cancelled) for the operation to succeed. Otherwise, an error is returned.
'
produces:
- application/json
tags:
- repository
summary: Delete a completed workflow run.
operationId: DeleteActionRun
parameters:
- type: string
description: owner of the repo
name: owner
in: path
required: true
- type: string
description: name of the repo
name: repo
in: path
required: true
- type: integer
format: int64
description: id of the action run
name: run_id
in: path
required: true
responses:
'204':
description: Workflow run has been removed
'400':
$ref: '#/responses/error'
'403':
$ref: '#/responses/forbidden'
'404':
$ref: '#/responses/notFound'
/repos/{owner}/{repo}/actions/runs/{run_id}/artifacts:
get:
produces:
- application/json
tags:
- repository
summary: List artifacts of a workflow run
operationId: ListActionRunArtifacts
parameters:
- type: string
description: owner of the repo
name: owner
in: path
required: true
- type: string
description: name of the repo
name: repo
in: path
required: true
- type: integer
format: int64
description: ID of the workflow run
name: run_id
in: path
required: true
- type: string
description: filter by artifact name
name: name
in: query
- type: integer
description: page number of results to return (1-based)
name: page
in: query
- type: integer
description: page size of results, default maximum page size is 50
name: limit
in: query
responses:
'200':
$ref: '#/responses/ActionArtifactList'
'400':
$ref: '#/responses/error'
'403':
$ref: '#/responses/forbidden'
'404':
$ref: '#/responses/notFound'
/repos/{owner}/{repo}/actions/runs/{run_id}/cancel:
post:
description: 'Cancel a particular workflow run. Pending or running jobs of the run are cancelled. A run that has already finished, whether cancelled, failed, skipped or succeeded, is left unchanged. In both cases the endpoint responds with HTTP 204.
'
produces:
- application/json
tags:
- repository
summary: Cancel a pending or running workflow run.
operationId: CancelActionRun
parameters:
- type: string
description: owner of the repo
name: owner
in: path
required: true
- type: string
description: name of the repo
name: repo
in: path
required: true
- type: integer
format: int64
description: ID of the workflow run
name: run_id
in: path
required: true
responses:
'204':
description: Workflow run has been cancelled
'403':
$ref: '#/responses/forbidden'
'404':
$ref: '#/responses/notFound'
/repos/{owner}/{repo}/actions/runs/{run_id}/jobs:
get:
produces:
- application/json
tags:
- repository
summary: List jobs of a workflow run
operationId: ListActionRunJobs
parameters:
- type: string
description: owner of the repo
name: owner
in: path
required: true
- type: string
description: name of the repo
name: repo
in: path
required: true
- type: integer
format: int64
description: ID of the workflow run
name: run_id
in: path
required: true
responses:
'200':
$ref: '#/responses/ActionRunJobList'
'400':
$ref: '#/responses/error'
'403':
$ref: '#/responses/forbidden'
'404':
$ref: '#/responses/notFound'
/repos/{owner}/{repo}/actions/runs/{run_id}/logs:
get:
produces:
- application/zip
tags:
- repository
summary: Download a ZIP of plaintext logs for every job in an action run
operationId: repoGetActionRunLogs
parameters:
- type: string
description: owner of the repo
name: owner
in: path
required: true
- type: string
description: name of the repo
name: repo
in: path
required: true
- type: integer
format: int64
description: 'ID of the workflow run. The ZIP contains the latest attempt of each job in the run, with each entry named `{job-name}-{job-id}-attempt-{N}.log` (the job ID prevents collisions when two jobs share a name; the attempt number records which run the log came from). The run itself has no attempt number — jobs are re-run independently, so use the per-job logs endpoint with `?attempt` to fetch a specific historical attempt of one job.
'
name: run_id
in: path
required: true
responses:
'200':
description: ZIP archive of per-job log files
schema:
type: string
format: binary
'401':
$ref: '#/responses/unauthorized'
'403':
$ref: '#/responses/forbidden'
'404':
$ref: '#/responses/notFound'
/repos/{owner}/{repo}/actions/secrets:
get:
produces:
- application/json
tags:
- repository
summary: List an repo's actions secrets
operationId: repoListActionsSecrets
parameters:
- type: string
description: owner of the repository
name: owner
in: path
required: true
- type: string
description: name of the repository
name: repo
in: path
required: true
- type: integer
description: page number of results to return (1-based)
name: page
in: query
- type: integer
description: page size of results
name: limit
in: query
responses:
'200':
$ref: '#/responses/SecretList'
'404':
$ref: '#/responses/notFound'
/repos/{owner}/{repo}/actions/secrets/{secretname}:
put:
consumes:
- application/json
produces:
- application/json
tags:
- repository
summary: Create or Update a secret value in a repository
operationId: updateRepoSecret
parameters:
- type: string
description: owner of the repository
name: owner
in: path
required: true
- type: string
description: name of the repository
name: repo
in: path
required: true
- type: string
description: name of the secret
name: secretname
in: path
required: true
- name: body
in: body
schema:
$ref: '#/definitions/CreateOrUpdateSecretOption'
responses:
'201':
description: response when creating a secret
'204':
description: response when updating a secret
'400':
$ref: '#/responses/error'
'404':
$ref: '#/responses/notFound'
delete:
consumes:
- application/json
produces:
- application/json
tags:
- repository
summary: Delete a secret in a repository
operationId: deleteRepoSecret
parameters:
- type: string
description: owner of the repository
name: owner
in: path
required: true
- type: string
description: name of the repository
name: repo
in: path
required: true
- type: string
description: name of the secret
name: secretname
in: path
required: true
responses:
'204':
description: delete one secret of the organization
'400':
$ref: '#/responses/error'
'404':
$ref: '#/responses/notFound'
/repos/{owner}/{repo}/actions/tasks:
get:
produces:
- application/json
tags:
- repository
summary: List a repository's action tasks
operationId: ListActionTasks
parameters:
- type: string
description: owner of the repo
name: owner
in: path
required: true
- type: string
description: name of the repo
name: repo
in: path
required: true
- type: integer
description: page number of results to return (1-based)
name: page
in: query
- type: integer
description: page size of results, default maximum page size is 50
name: limit
in: query
- type: array
items:
enum:
- unknown
- waiting
- running
- success
- failure
- cancelled
- skipped
- blocked
type: string
description: "Returns workflow tasks with the check run status or conclusion that is specified.\n For example, a conclusion can be success or a status can be in_progress.\n"
name: status
in: query
responses:
'200':
$ref: '#/responses/TasksList'
'400':
$ref: '#/responses/error'
'403':
$ref: '#/responses/forbidden'
'404':
$ref: '#/responses/notFound'
'409':
$ref: '#/responses/conflict'
'422':
$ref: '#/responses/validationError'
/repos/{owner}/{repo}/actions/variables:
get:
produces:
- application/json
tags:
- repository
summary: Get repo-level variables list
operationId: getRepoVariablesList
parameters:
- type: string
description: name of the owner
name: owner
in: path
required: true
- type: string
description: name of the repository
name: repo
in: path
required: true
- type: integer
description: page number of results to return (1-based)
name: page
in: query
- type: integer
description: page size of results
name: limit
in: query
responses:
'200':
$ref: '#/responses/VariableList'
'400':
$ref: '#/responses/error'
'404':
$ref: '#/responses/notFound'
/repos/{owner}/{repo}/actions/variables/{variablename}:
get:
produces:
- application/json
tags:
- repository
summary: Get a repo-level variable
operationId: getRepoVariable
parameters:
- type: string
description: name of the owner
name: owner
in: path
required: true
- type: string
description: name of the repository
name: repo
in: path
required: true
- type: string
description: name of the variable
name: variablename
in: path
required: true
responses:
'200':
$ref: '#/responses/ActionVariable'
'400':
$ref: '#/responses/error'
'404':
$ref: '#/responses/notFound'
put:
produces:
- application/json
tags:
- repository
summary: Update a repo-level variable
operationId: updateRepoVariable
parameters:
- type: string
description: name of the owner
name: owner
in: path
required: true
- type: string
description: name of the repository
name: repo
in: path
required: true
- type: string
description: name of the variable
name: variablename
in: path
required: true
- name: body
in: body
schema:
$ref: '#/definitions/UpdateVariableOption'
responses:
'201':
description: response when updating a repo-level variable
'204':
description: response when updating a repo-level variable
'400':
$ref: '#/responses/error'
'404':
$ref: '#/responses/notFound'
post:
produces:
- application/json
tags:
- repository
summary: Create a repo-level variable
operationId: createRepoVariable
parameters:
- type: string
description: name of the owner
name: owner
in: path
required: true
- type: string
description: name of the repository
name: repo
in: path
required: true
- type: string
description: name of the variable
name: variablename
in: path
# --- truncated at 32 KB (303 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/forgejo/refs/heads/main/openapi/forgejo-repository-api-openapi.yml