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"

string

required

Owner of the repository

string

required

Name of the repository

array

List of workflow definitions

string

Workflow identifier (filename)

string

Display name of the workflow

string

Path to workflow file in repository

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"

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"
    }
  }'

string

required

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

object

Input parameters defined in workflow dispatch configuration

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"

string

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

string

Filter by branch name

string

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

string

Filter by username who triggered the run

string

Filter by commit SHA that triggered the run

array

integer

Unique run ID

string

Associated workflow filename

string

Current status of the run

string

Event that triggered the run

string

Git commit SHA for this run

string

ISO 8601 timestamp when run started

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"

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"

array

integer

Job ID

string

Job name from workflow definition

string

Job status

string

When job started executing

string

When job finished

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"

array

integer

Runner ID

string

Runner name

string

Runner status (online, offline)

array

Runner labels for job matching

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"

string

Registration token for runner setup

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"

array

string

Secret name

string

Secret description

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"
  }'

string

required

Name of the secret (uppercase with underscores recommended)

string

required

Base64-encoded secret value

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"

array

string

Variable name

string

Variable value (plaintext)

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"
  }'

string

required

Variable value

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"

string

Filter artifacts by name

array

integer

Artifact ID

string

Artifact name

integer

Size in bytes

string

Creation timestamp

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

​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

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