Actions API

API endpoints for Gitea Actions CI/CD workflows

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

id · 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

id · 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

id · 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

id · 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

id · 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.