# Forgejo Actions (CI/CD)

Forgejo Actions is a built-in CI/CD system that is **compatible with GitHub Actions**. Workflows defined in `.forgejo/workflows/` (or `.github/workflows/`) are automatically picked up by Forgejo runners.

## Architecture

### Workflows

A **workflow** is a YAML file defining an automated process. Workflows are stored in the repository under `.forgejo/workflows/` or `.github/workflows/`. Each workflow is triggered by events (push, pull_request, workflow_dispatch, etc.).

### Runs

A **workflow run** is a single execution of a workflow. Each run is triggered by an event and has a unique `run_id`. Runs have statuses: `waiting`, `running`, `success`, `failure`, `cancelled`.

### Jobs

A **job** is a set of steps within a workflow run that execute on the same runner. Jobs can run in parallel or have dependencies via `needs`. In the Forgejo API, jobs are referred to as **tasks**.

### Steps

A **step** is an individual command or action within a job. Steps run sequentially within their job. Each step can be a shell command (`run:`) or a reusable action (`uses:`).

## API Coverage

| Area | File |
|------|------|
| Workflow runs and tasks | [runs.md](runs.md) |
| Secrets management | [secrets.md](secrets.md) |
| Variables management | [variables.md](variables.md) |
| Workflow dispatch and runners | [workflows.md](workflows.md) |

## Key Concepts

- **Events**: `push`, `pull_request`, `pull_request_target`, `workflow_dispatch`, `schedule`, `release`, `issues`, `issue_comment`, `create`, `delete`, `fork`, `tag`
- **Runners**: Forgejo-compatible runners (e.g., `forgejo-runner`) that pick up and execute jobs
- **Contexts**: Workflows can access `github.*`, `secrets.*`, `vars.*`, `env.*`, `runner.*` contexts (using GitHub-compatible naming)
- **Status checks**: Workflow runs create commit statuses that can be used with branch protection rules. See [commit-statuses](../commit-statuses/README.md) for checking CI results via the API.

## Checking CI Status for a PR

To check whether CI has passed for a pull request, use **commit statuses** rather than filtering workflow runs:

```bash
# Get the PR to find the head SHA
curl -s -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/pulls/{index}" | jq '.head.sha'

# Then check combined status for that SHA
curl -s -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/commits/{sha}/status"
```
