Actions API - Gitea

Overview

Gitea Actions provides a powerful CI/CD system integrated directly into your repositories. The Actions API allows you to programmatically manage workflows, runs, jobs, runners, secrets, variables, and artifacts.

Workflows

List Repository Workflows

Get all workflows defined in a repository.

curl -X GET "https://gitea.example.com/api/v1/repos/{owner}/{repo}/actions/workflows" \
  -H "Authorization: token YOUR_TOKEN"

owner

string

required

Owner of the repository

repo

string

required

Name of the repository

workflows

array

List of workflow definitions

string

Workflow identifier (filename)

name

string

Display name of the workflow

path

string

Path to workflow file in repository

state

string

Workflow state (active, disabled)

Get Workflow

Retrieve details about a specific workflow.

curl -X GET "https://gitea.example.com/api/v1/repos/{owner}/{repo}/actions/workflows/{workflow_id}" \
  -H "Authorization: token YOUR_TOKEN"

workflow_id

string

required

Workflow identifier (filename or ID)

Enable/Disable Workflow

Enable or disable a workflow from running.

# Enable workflow
curl -X PUT "https://gitea.example.com/api/v1/repos/{owner}/{repo}/actions/workflows/{workflow_id}/enable" \
  -H "Authorization: token YOUR_TOKEN"

# Disable workflow
curl -X PUT "https://gitea.example.com/api/v1/repos/{owner}/{repo}/actions/workflows/{workflow_id}/disable" \
  -H "Authorization: token YOUR_TOKEN"

Dispatch Workflow

Manually trigger a workflow run with custom inputs.

curl -X POST "https://gitea.example.com/api/v1/repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ref": "main",
    "inputs": {
      "environment": "production",
      "version": "1.0.0"
    }
  }'

ref

string

required

Git reference (branch, tag, or commit SHA) to run workflow on

inputs

object

Input parameters defined in workflow dispatch configuration

return_run_details

boolean

Return workflow run ID and URLs in response

Workflow Runs

List Workflow Runs

List all workflow runs for a repository with optional filters.

curl -X GET "https://gitea.example.com/api/v1/repos/{owner}/{repo}/actions/runs?status=success&branch=main" \
  -H "Authorization: token YOUR_TOKEN"

event

string

Filter by workflow event (push, pull_request, schedule, workflow_dispatch)

branch

string

Filter by branch name

status

string

Filter by status: pending, queued, in_progress, failure, success, skipped

actor

string

Filter by username who triggered the run

head_sha

string

Filter by commit SHA that triggered the run

workflow_runs

array

integer

Unique run ID

workflow_id

string

Associated workflow filename

status

string

Current status of the run

event

string

Event that triggered the run

commit_sha

string

Git commit SHA for this run

started_at

string

ISO 8601 timestamp when run started

completed_at

string

ISO 8601 timestamp when run completed

Get Workflow Run

Get details about a specific workflow run.

curl -X GET "https://gitea.example.com/api/v1/repos/{owner}/{repo}/actions/runs/{run}" \
  -H "Authorization: token YOUR_TOKEN"

run

integer

required

Workflow run ID

Rerun Workflow

Rerun an entire workflow run or a specific job.

# Rerun entire workflow
curl -X POST "https://gitea.example.com/api/v1/repos/{owner}/{repo}/actions/runs/{run}/rerun" \
  -H "Authorization: token YOUR_TOKEN"

# Rerun specific job
curl -X POST "https://gitea.example.com/api/v1/repos/{owner}/{repo}/actions/runs/{run}/jobs/{job_id}/rerun" \
  -H "Authorization: token YOUR_TOKEN"

Delete Workflow Run

Delete a completed workflow run and its associated data.

curl -X DELETE "https://gitea.example.com/api/v1/repos/{owner}/{repo}/actions/runs/{run}" \
  -H "Authorization: token YOUR_TOKEN"

Jobs

List Workflow Jobs

List all jobs in a workflow run.

curl -X GET "https://gitea.example.com/api/v1/repos/{owner}/{repo}/actions/runs/{run}/jobs" \
  -H "Authorization: token YOUR_TOKEN"

jobs

array

integer

Job ID

name

string

Job name from workflow definition

status

string

Job status

started_at

string

When job started executing

completed_at

string

When job finished

steps

array

Individual steps within the job

Get Job

Get details about a specific job.

curl -X GET "https://gitea.example.com/api/v1/repos/{owner}/{repo}/actions/jobs/{job_id}" \
  -H "Authorization: token YOUR_TOKEN"

Download Job Logs

Download the log output from a job.

curl -X GET "https://gitea.example.com/api/v1/repos/{owner}/{repo}/actions/jobs/{job_id}/logs" \
  -H "Authorization: token YOUR_TOKEN" \
  -o job-logs.txt

Runners

List Runners

List all runners available to a repository.

curl -X GET "https://gitea.example.com/api/v1/repos/{owner}/{repo}/actions/runners" \
  -H "Authorization: token YOUR_TOKEN"

runners

array

integer

Runner ID

name

string

Runner name

status

string

Runner status (online, offline)

labels

array

Runner labels for job matching

last_active

string

Last time runner was active

Get Runner

Get details about a specific runner.

curl -X GET "https://gitea.example.com/api/v1/repos/{owner}/{repo}/actions/runners/{runner_id}" \
  -H "Authorization: token YOUR_TOKEN"

Delete Runner

Remove a runner from the repository.

curl -X DELETE "https://gitea.example.com/api/v1/repos/{owner}/{repo}/actions/runners/{runner_id}" \
  -H "Authorization: token YOUR_TOKEN"

Create Registration Token

Generate a token to register a new runner.

curl -X POST "https://gitea.example.com/api/v1/repos/{owner}/{repo}/actions/runners/registration-token" \
  -H "Authorization: token YOUR_TOKEN"

token

string

Registration token for runner setup

expires_at

string

Token expiration time

Secrets

List Secrets

List all action secrets (without exposing values).

curl -X GET "https://gitea.example.com/api/v1/repos/{owner}/{repo}/actions/secrets" \
  -H "Authorization: token YOUR_TOKEN"

secrets

array

name

string

Secret name

description

string

Secret description

created

string

Creation timestamp

Create or Update Secret

Create a new secret or update an existing one.

curl -X PUT "https://gitea.example.com/api/v1/repos/{owner}/{repo}/actions/secrets/{secretname}" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": "base64_encoded_secret_value",
    "description": "Database password for production"
  }'

secretname

string

required

Name of the secret (uppercase with underscores recommended)

data

string

required

Base64-encoded secret value

description

string

Description of what the secret is used for

Delete Secret

Delete a secret from the repository.

curl -X DELETE "https://gitea.example.com/api/v1/repos/{owner}/{repo}/actions/secrets/{secretname}" \
  -H "Authorization: token YOUR_TOKEN"

Variables

List Variables

List all action variables.

curl -X GET "https://gitea.example.com/api/v1/repos/{owner}/{repo}/actions/variables" \
  -H "Authorization: token YOUR_TOKEN"

variables

array

name

string

Variable name

data

string

Variable value (plaintext)

description

string

Variable description

Get Variable

Get a specific variable by name.

curl -X GET "https://gitea.example.com/api/v1/repos/{owner}/{repo}/actions/variables/{variablename}" \
  -H "Authorization: token YOUR_TOKEN"

Create Variable

Create a new variable.

curl -X POST "https://gitea.example.com/api/v1/repos/{owner}/{repo}/actions/variables/{variablename}" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "production",
    "description": "Deployment environment"
  }'

value

string

required

Variable value

description

string

Description of the variable

Update Variable

Update an existing variable.

curl -X PUT "https://gitea.example.com/api/v1/repos/{owner}/{repo}/actions/variables/{variablename}" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ENVIRONMENT",
    "value": "staging",
    "description": "Updated environment"
  }'

Delete Variable

Delete a variable.

curl -X DELETE "https://gitea.example.com/api/v1/repos/{owner}/{repo}/actions/variables/{variablename}" \
  -H "Authorization: token YOUR_TOKEN"

Artifacts

List Artifacts

List all artifacts for a repository or specific run.

# List all artifacts for repository
curl -X GET "https://gitea.example.com/api/v1/repos/{owner}/{repo}/actions/artifacts" \
  -H "Authorization: token YOUR_TOKEN"

# List artifacts for specific run
curl -X GET "https://gitea.example.com/api/v1/repos/{owner}/{repo}/actions/runs/{run}/artifacts" \
  -H "Authorization: token YOUR_TOKEN"

name

string

Filter artifacts by name

artifacts

array

integer

Artifact ID

name

string

Artifact name

size

integer

Size in bytes

created_at

string

Creation timestamp

expired

boolean

Whether artifact has expired

Get Artifact

Get details about a specific artifact.

curl -X GET "https://gitea.example.com/api/v1/repos/{owner}/{repo}/actions/artifacts/{artifact_id}" \
  -H "Authorization: token YOUR_TOKEN"

Download Artifact

Download an artifact as a zip file.

curl -X GET "https://gitea.example.com/api/v1/repos/{owner}/{repo}/actions/artifacts/{artifact_id}/zip" \
  -H "Authorization: token YOUR_TOKEN" \
  -L -o artifact.zip

The download endpoint returns a redirect (302) to the actual artifact storage location.

Delete Artifact

Delete an artifact.

curl -X DELETE "https://gitea.example.com/api/v1/repos/{owner}/{repo}/actions/artifacts/{artifact_id}" \
  -H "Authorization: token YOUR_TOKEN"

Admin Endpoints

Administrators can access system-wide actions data.

List All Jobs

curl -X GET "https://gitea.example.com/api/v1/admin/actions/jobs?status=in_progress" \
  -H "Authorization: token ADMIN_TOKEN"

List All Runs

curl -X GET "https://gitea.example.com/api/v1/admin/actions/runs" \
  -H "Authorization: token ADMIN_TOKEN"

Status Values

Workflow runs and jobs can have the following status values:

pending: Waiting to be queued
queued: Queued for execution
in_progress: Currently running
success: Completed successfully
failure: Failed with errors
skipped: Skipped due to conditions
cancelled: Manually cancelled

Best Practices

Use secrets for sensitive data like passwords and API keys
Use variables for non-sensitive configuration values
Set appropriate artifact retention periods to manage storage
Use workflow dispatch for manual deployments with controlled inputs
Monitor runner status to ensure adequate capacity

Secrets are encrypted at rest but should never be logged or exposed in workflow output.

Overview

Repositories

Issues & Pull Requests

Organizations & Teams

Users

Actions & Packages

​Overview

​Workflows

​List Repository Workflows

​Get Workflow

​Enable/Disable Workflow

​Dispatch Workflow

​Workflow Runs

​List Workflow Runs

​Get Workflow Run

​Rerun Workflow

​Delete Workflow Run

​Jobs

​List Workflow Jobs

​Get Job

​Download Job Logs

​Runners

​List Runners

​Get Runner

​Delete Runner

​Create Registration Token

​Secrets

​List Secrets

​Create or Update Secret

​Delete Secret

​Variables

​List Variables

​Get Variable

​Create Variable

​Update Variable

​Delete Variable

​Artifacts

​List Artifacts

​Get Artifact

​Download Artifact

​Delete Artifact

​Admin Endpoints

​List All Jobs

​List All Runs

​Status Values

​Best Practices

Build docs developers (and LLMs) love

Overview

Workflows

List Repository Workflows

Get Workflow

Enable/Disable Workflow

Dispatch Workflow

Workflow Runs

List Workflow Runs

Get Workflow Run

Rerun Workflow

Delete Workflow Run

Jobs

List Workflow Jobs

Get Job

Download Job Logs

Runners

List Runners

Get Runner

Delete Runner

Create Registration Token

Secrets

List Secrets

Create or Update Secret

Delete Secret

Variables

List Variables

Get Variable

Create Variable

Update Variable

Delete Variable

Artifacts

List Artifacts

Get Artifact

Download Artifact

Delete Artifact

Admin Endpoints

List All Jobs

List All Runs

Status Values

Best Practices