> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/go-gitea/gitea/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

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

<ParamField path="owner" type="string" required>
  Owner of the repository
</ParamField>

<ParamField path="repo" type="string" required>
  Name of the repository
</ParamField>

<ResponseField name="workflows" type="array">
  List of workflow definitions

  <ResponseField name="id" type="string">
    Workflow identifier (filename)
  </ResponseField>

  <ResponseField name="name" type="string">
    Display name of the workflow
  </ResponseField>

  <ResponseField name="path" type="string">
    Path to workflow file in repository
  </ResponseField>

  <ResponseField name="state" type="string">
    Workflow state (active, disabled)
  </ResponseField>
</ResponseField>

### Get Workflow

Retrieve details about a specific workflow.

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

<ParamField path="workflow_id" type="string" required>
  Workflow identifier (filename or ID)
</ParamField>

### Enable/Disable Workflow

Enable or disable a workflow from running.

```bash theme={null}
# 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.

```bash theme={null}
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"
    }
  }'
```

<ParamField body="ref" type="string" required>
  Git reference (branch, tag, or commit SHA) to run workflow on
</ParamField>

<ParamField body="inputs" type="object">
  Input parameters defined in workflow dispatch configuration
</ParamField>

<ParamField query="return_run_details" type="boolean">
  Return workflow run ID and URLs in response
</ParamField>

## Workflow Runs

### List Workflow Runs

List all workflow runs for a repository with optional filters.

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

<ParamField query="event" type="string">
  Filter by workflow event (push, pull\_request, schedule, workflow\_dispatch)
</ParamField>

<ParamField query="branch" type="string">
  Filter by branch name
</ParamField>

<ParamField query="status" type="string">
  Filter by status: pending, queued, in\_progress, failure, success, skipped
</ParamField>

<ParamField query="actor" type="string">
  Filter by username who triggered the run
</ParamField>

<ParamField query="head_sha" type="string">
  Filter by commit SHA that triggered the run
</ParamField>

<ResponseField name="workflow_runs" type="array">
  <ResponseField name="id" type="integer">
    Unique run ID
  </ResponseField>

  <ResponseField name="workflow_id" type="string">
    Associated workflow filename
  </ResponseField>

  <ResponseField name="status" type="string">
    Current status of the run
  </ResponseField>

  <ResponseField name="event" type="string">
    Event that triggered the run
  </ResponseField>

  <ResponseField name="commit_sha" type="string">
    Git commit SHA for this run
  </ResponseField>

  <ResponseField name="started_at" type="string">
    ISO 8601 timestamp when run started
  </ResponseField>

  <ResponseField name="completed_at" type="string">
    ISO 8601 timestamp when run completed
  </ResponseField>
</ResponseField>

### Get Workflow Run

Get details about a specific workflow run.

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

<ParamField path="run" type="integer" required>
  Workflow run ID
</ParamField>

### Rerun Workflow

Rerun an entire workflow run or a specific job.

```bash theme={null}
# 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.

```bash theme={null}
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.

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

<ResponseField name="jobs" type="array">
  <ResponseField name="id" type="integer">
    Job ID
  </ResponseField>

  <ResponseField name="name" type="string">
    Job name from workflow definition
  </ResponseField>

  <ResponseField name="status" type="string">
    Job status
  </ResponseField>

  <ResponseField name="started_at" type="string">
    When job started executing
  </ResponseField>

  <ResponseField name="completed_at" type="string">
    When job finished
  </ResponseField>

  <ResponseField name="steps" type="array">
    Individual steps within the job
  </ResponseField>
</ResponseField>

### Get Job

Get details about a specific job.

```bash theme={null}
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.

```bash theme={null}
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.

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

<ResponseField name="runners" type="array">
  <ResponseField name="id" type="integer">
    Runner ID
  </ResponseField>

  <ResponseField name="name" type="string">
    Runner name
  </ResponseField>

  <ResponseField name="status" type="string">
    Runner status (online, offline)
  </ResponseField>

  <ResponseField name="labels" type="array">
    Runner labels for job matching
  </ResponseField>

  <ResponseField name="last_active" type="string">
    Last time runner was active
  </ResponseField>
</ResponseField>

### Get Runner

Get details about a specific runner.

```bash theme={null}
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.

```bash theme={null}
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.

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

<ResponseField name="token" type="string">
  Registration token for runner setup
</ResponseField>

<ResponseField name="expires_at" type="string">
  Token expiration time
</ResponseField>

## Secrets

### List Secrets

List all action secrets (without exposing values).

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

<ResponseField name="secrets" type="array">
  <ResponseField name="name" type="string">
    Secret name
  </ResponseField>

  <ResponseField name="description" type="string">
    Secret description
  </ResponseField>

  <ResponseField name="created" type="string">
    Creation timestamp
  </ResponseField>
</ResponseField>

### Create or Update Secret

Create a new secret or update an existing one.

```bash theme={null}
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"
  }'
```

<ParamField path="secretname" type="string" required>
  Name of the secret (uppercase with underscores recommended)
</ParamField>

<ParamField body="data" type="string" required>
  Base64-encoded secret value
</ParamField>

<ParamField body="description" type="string">
  Description of what the secret is used for
</ParamField>

### Delete Secret

Delete a secret from the repository.

```bash theme={null}
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.

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

<ResponseField name="variables" type="array">
  <ResponseField name="name" type="string">
    Variable name
  </ResponseField>

  <ResponseField name="data" type="string">
    Variable value (plaintext)
  </ResponseField>

  <ResponseField name="description" type="string">
    Variable description
  </ResponseField>
</ResponseField>

### Get Variable

Get a specific variable by name.

```bash theme={null}
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.

```bash theme={null}
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"
  }'
```

<ParamField body="value" type="string" required>
  Variable value
</ParamField>

<ParamField body="description" type="string">
  Description of the variable
</ParamField>

### Update Variable

Update an existing variable.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
# 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"
```

<ParamField query="name" type="string">
  Filter artifacts by name
</ParamField>

<ResponseField name="artifacts" type="array">
  <ResponseField name="id" type="integer">
    Artifact ID
  </ResponseField>

  <ResponseField name="name" type="string">
    Artifact name
  </ResponseField>

  <ResponseField name="size" type="integer">
    Size in bytes
  </ResponseField>

  <ResponseField name="created_at" type="string">
    Creation timestamp
  </ResponseField>

  <ResponseField name="expired" type="boolean">
    Whether artifact has expired
  </ResponseField>
</ResponseField>

### Get Artifact

Get details about a specific artifact.

```bash theme={null}
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.

```bash theme={null}
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
```

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

### Delete Artifact

Delete an artifact.

```bash theme={null}
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

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

### List All Runs

```bash theme={null}
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

<Tip>
  * 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
</Tip>

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