runs

Accessed as client.repos.actions.runs; the async client mirrors it.

SyncAsync

ReposActionsRuns

The repos.actions.runs namespace.

artifacts

artifacts(
    owner: str, repo: str, run_id: int, *, name: str | None = None, page: int | None = None, limit: int | None = None
) -> Paginated[ActionArtifact]

List artifacts of a workflow run.

Parameters:

Name	Type	Description	Default
`owner`	`str`	owner of the repo	required
`repo`	`str`	name of the repo	required
`run_id`	`int`	ID of the workflow run	required
`name`	`str \| None`	filter by artifact name	`None`
`page`	`int \| None`	1-based page to start iteration at.	`None`
`limit`	`int \| None`	Page size; the instance caps it server-side.	`None`

Returns:

Type	Description
`Paginated[ActionArtifact]`	ActionArtifactList.

Raises:

Type	Description
`BadRequestError`	APIError is error format response.
`ForbiddenError`	APIForbiddenError is a forbidden error response.
`NotFoundError`	APINotFound is a not found error response.

Operation ID: ListActionRunArtifacts

cancel

cancel(owner: str, repo: str, run_id: int) -> None

Cancel a pending or running workflow run.

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.

Parameters:

Name	Type	Description	Default
`owner`	`str`	owner of the repo	required
`repo`	`str`	name of the repo	required
`run_id`	`int`	ID of the workflow run	required

Returns:

Type	Description
`None`	No content.

Raises:

Type	Description
`ForbiddenError`	APIForbiddenError is a forbidden error response.
`NotFoundError`	APINotFound is a not found error response.

Operation ID: CancelActionRun

delete

delete(owner: str, repo: str, run_id: int) -> None

Delete a completed workflow run.

Remove a particular workflow run. The workflow run must have completed (succeeded, failed, cancelled) for the operation to succeed. Otherwise, an error is returned.

Parameters:

Name	Type	Description	Default
`owner`	`str`	owner of the repo	required
`repo`	`str`	name of the repo	required
`run_id`	`int`	id of the action run	required

Returns:

Type	Description
`None`	No content.

Raises:

Type	Description
`BadRequestError`	APIError is error format response.
`ForbiddenError`	APIForbiddenError is a forbidden error response.
`NotFoundError`	APINotFound is a not found error response.

Operation ID: DeleteActionRun

get

get(owner: str, repo: str, run_id: int) -> ActionRun

Get an action run.

Parameters:

Name	Type	Description	Default
`owner`	`str`	owner of the repo	required
`repo`	`str`	name of the repo	required
`run_id`	`int`	id of the action run	required

Returns:

Type	Description
`ActionRun`	ActionRun.

Raises:

Type	Description
`BadRequestError`	APIError is error format response.
`ForbiddenError`	APIForbiddenError is a forbidden error response.
`NotFoundError`	APINotFound is a not found error response.

Operation ID: ActionRun

jobs

jobs(owner: str, repo: str, run_id: int) -> list[ActionRunJob]

List jobs of a workflow run.

Parameters:

Name	Type	Description	Default
`owner`	`str`	owner of the repo	required
`repo`	`str`	name of the repo	required
`run_id`	`int`	ID of the workflow run	required

Returns:

Type	Description
`list[ActionRunJob]`	ActionRunJobList.

Raises:

Type	Description
`BadRequestError`	APIError is error format response.
`ForbiddenError`	APIForbiddenError is a forbidden error response.
`NotFoundError`	APINotFound is a not found error response.

Operation ID: ListActionRunJobs

list

list(
    owner: str,
    repo: str,
    *,
    page: int | None = None,
    limit: int | None = None,
    event: list[str] | None = None,
    status: list[Literal["unknown", "waiting", "running", "success", "failure", "cancelled", "skipped", "blocked"]]
    | None = None,
    run_number: int | None = None,
    head_sha: str | None = None,
    ref: str | None = None,
    workflow_id: str | None = None,
) -> ListActionRunResponse

List a repository's action runs.

Parameters:

Name	Type	Description	Default
`owner`	`str`	owner of the repo	required
`repo`	`str`	name of the repo	required
`page`	`int \| None`	page number of results to return (1-based)	`None`
`limit`	`int \| None`	page size of results, default maximum page size is 50	`None`
`event`	`list[str] \| None`	Returns workflow run triggered by the specified events. For example, `push`, `pull_request` or `workflow_dispatch`.	`None`
`status`	`list[Literal['unknown', 'waiting', 'running', 'success', 'failure', 'cancelled', 'skipped', 'blocked']] \| None`	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.	`None`
`run_number`	`int \| None`	Returns the workflow run associated with the run number.	`None`
`head_sha`	`str \| None`	Only returns workflow runs that are associated with the specified head_sha.	`None`
`ref`	`str \| None`	Only return workflow runs that involve the given Git reference, for example, `refs/heads/main`.	`None`
`workflow_id`	`str \| None`	Only return workflow runs that involve the given workflow ID.	`None`

Returns:

Type	Description
`ListActionRunResponse`	ActionRunList.

Raises:

Type	Description
`BadRequestError`	APIError is error format response.
`ForbiddenError`	APIForbiddenError is a forbidden error response.

Operation ID: ListActionRuns

logs

logs(owner: str, repo: str, run_id: int) -> bytes

Download a ZIP of plaintext logs for every job in an action run.

Parameters:

Name	Type	Description	Default
`owner`	`str`	owner of the repo	required
`repo`	`str`	name of the repo	required
`run_id`	`int`	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.	required

Returns:

Type	Description
`bytes`	ZIP archive of per-job log files.

Raises:

Type	Description
`UnauthorizedError`	APIUnauthorizedError is a unauthorized error response.
`ForbiddenError`	APIForbiddenError is a forbidden error response.
`NotFoundError`	APINotFound is a not found error response.

Operation ID: repoGetActionRunLogs

AsyncReposActionsRuns

The repos.actions.runs namespace.

artifacts

artifacts(
    owner: str, repo: str, run_id: int, *, name: str | None = None, page: int | None = None, limit: int | None = None
) -> AsyncPaginated[ActionArtifact]

List artifacts of a workflow run.

Parameters:

Name	Type	Description	Default
`owner`	`str`	owner of the repo	required
`repo`	`str`	name of the repo	required
`run_id`	`int`	ID of the workflow run	required
`name`	`str \| None`	filter by artifact name	`None`
`page`	`int \| None`	1-based page to start iteration at.	`None`
`limit`	`int \| None`	Page size; the instance caps it server-side.	`None`

Returns:

Type	Description
`AsyncPaginated[ActionArtifact]`	ActionArtifactList.

Raises:

Type	Description
`BadRequestError`	APIError is error format response.
`ForbiddenError`	APIForbiddenError is a forbidden error response.
`NotFoundError`	APINotFound is a not found error response.

Operation ID: ListActionRunArtifacts

cancel

cancel(owner: str, repo: str, run_id: int) -> None

Cancel a pending or running workflow run.

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.

Parameters:

Name	Type	Description	Default
`owner`	`str`	owner of the repo	required
`repo`	`str`	name of the repo	required
`run_id`	`int`	ID of the workflow run	required

Returns:

Type	Description
`None`	No content.

Raises:

Type	Description
`ForbiddenError`	APIForbiddenError is a forbidden error response.
`NotFoundError`	APINotFound is a not found error response.

Operation ID: CancelActionRun

delete

delete(owner: str, repo: str, run_id: int) -> None

Delete a completed workflow run.

Remove a particular workflow run. The workflow run must have completed (succeeded, failed, cancelled) for the operation to succeed. Otherwise, an error is returned.

Parameters:

Name	Type	Description	Default
`owner`	`str`	owner of the repo	required
`repo`	`str`	name of the repo	required
`run_id`	`int`	id of the action run	required

Returns:

Type	Description
`None`	No content.

Raises:

Type	Description
`BadRequestError`	APIError is error format response.
`ForbiddenError`	APIForbiddenError is a forbidden error response.
`NotFoundError`	APINotFound is a not found error response.

Operation ID: DeleteActionRun

get

get(owner: str, repo: str, run_id: int) -> ActionRun

Get an action run.

Parameters:

Name	Type	Description	Default
`owner`	`str`	owner of the repo	required
`repo`	`str`	name of the repo	required
`run_id`	`int`	id of the action run	required

Returns:

Type	Description
`ActionRun`	ActionRun.

Raises:

Type	Description
`BadRequestError`	APIError is error format response.
`ForbiddenError`	APIForbiddenError is a forbidden error response.
`NotFoundError`	APINotFound is a not found error response.

Operation ID: ActionRun

jobs

jobs(owner: str, repo: str, run_id: int) -> list[ActionRunJob]

List jobs of a workflow run.

Parameters:

Name	Type	Description	Default
`owner`	`str`	owner of the repo	required
`repo`	`str`	name of the repo	required
`run_id`	`int`	ID of the workflow run	required

Returns:

Type	Description
`list[ActionRunJob]`	ActionRunJobList.

Raises:

Type	Description
`BadRequestError`	APIError is error format response.
`ForbiddenError`	APIForbiddenError is a forbidden error response.
`NotFoundError`	APINotFound is a not found error response.

Operation ID: ListActionRunJobs

list

list(
    owner: str,
    repo: str,
    *,
    page: int | None = None,
    limit: int | None = None,
    event: list[str] | None = None,
    status: list[Literal["unknown", "waiting", "running", "success", "failure", "cancelled", "skipped", "blocked"]]
    | None = None,
    run_number: int | None = None,
    head_sha: str | None = None,
    ref: str | None = None,
    workflow_id: str | None = None,
) -> ListActionRunResponse

List a repository's action runs.

Parameters:

Name	Type	Description	Default
`owner`	`str`	owner of the repo	required
`repo`	`str`	name of the repo	required
`page`	`int \| None`	page number of results to return (1-based)	`None`
`limit`	`int \| None`	page size of results, default maximum page size is 50	`None`
`event`	`list[str] \| None`	Returns workflow run triggered by the specified events. For example, `push`, `pull_request` or `workflow_dispatch`.	`None`
`status`	`list[Literal['unknown', 'waiting', 'running', 'success', 'failure', 'cancelled', 'skipped', 'blocked']] \| None`	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.	`None`
`run_number`	`int \| None`	Returns the workflow run associated with the run number.	`None`
`head_sha`	`str \| None`	Only returns workflow runs that are associated with the specified head_sha.	`None`
`ref`	`str \| None`	Only return workflow runs that involve the given Git reference, for example, `refs/heads/main`.	`None`
`workflow_id`	`str \| None`	Only return workflow runs that involve the given workflow ID.	`None`

Returns:

Type	Description
`ListActionRunResponse`	ActionRunList.

Raises:

Type	Description
`BadRequestError`	APIError is error format response.
`ForbiddenError`	APIForbiddenError is a forbidden error response.

Operation ID: ListActionRuns

logs

logs(owner: str, repo: str, run_id: int) -> bytes

Download a ZIP of plaintext logs for every job in an action run.

Parameters:

Name	Type	Description	Default
`owner`	`str`	owner of the repo	required
`repo`	`str`	name of the repo	required
`run_id`	`int`	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.	required

Returns:

Type	Description
`bytes`	ZIP archive of per-job log files.

Raises:

Type	Description
`UnauthorizedError`	APIUnauthorizedError is a unauthorized error response.
`ForbiddenError`	APIForbiddenError is a forbidden error response.
`NotFoundError`	APINotFound is a not found error response.

Operation ID: repoGetActionRunLogs