Files

Jeffrey Smeets 9109e5724d Reset git history for making manifests public

2026-06-01 11:06:25 +02:00

13 KiB

Raw Blame History

Gitea Actions Reference

Based on Gitea 1.21+ and act_runner v0.2.x Gitea Actions is compatible with GitHub Actions syntax. Both github.* and gitea.* context namespaces work; prefer gitea.* for Gitea-specific deployments.

Workflow File Location
Trigger Events (on:)
Context Variables
Secrets
Variables (vars)
Built-in Environment Variables
Expression Syntax & Functions
Runner Labels
Differences from GitHub Actions
Unsupported Features
Badge URLs

Workflow File Location

.gitea/workflows/<name>.yaml

Basic structure:

name: My Workflow
run-name: ${{ gitea.actor }} triggered ${{ gitea.event_name }}

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run something
        run: echo "Hello from ${{ gitea.actor }}"

Trigger Events (`on:`)

Supported Events

Event	Activity Types
`push`	—
`pull_request`	`opened`, `edited`, `closed`, `reopened`, `assigned`, `unassigned`, `synchronize`, `labeled`, `unlabeled`
`pull_request_review`	`submitted`, `edited`
`pull_request_review_comment`	`created`, `edited`
`issues`	`opened`, `edited`, `closed`, `reopened`, `assigned`, `unassigned`, `milestoned`, `demilestoned`, `labeled`, `unlabeled`
`issue_comment`	`created`, `edited`, `deleted`
`release`	`published`, `edited`
`registry_package`	`published`
`create`	—
`delete`	—
`fork`	—
`gollum`	—
`workflow_dispatch`	—
`workflow_run`	`requested`, `completed`
`schedule`	—

on:
  push:
    branches:
      - main
      - 'feature/**'
    tags:
      - 'v*'
    paths:
      - 'src/**'
  pull_request:
    types: [opened, synchronize]
    branches:
      - main
  schedule:
    - cron: '0 1 * * *'
    - cron: '@daily'      # Gitea extension (not available in GitHub Actions)
    - cron: '@hourly'     # Gitea extension
    - cron: '@weekly'     # Gitea extension
    - cron: '@monthly'    # Gitea extension
    - cron: '@yearly'     # Gitea extension

`workflow_dispatch` with Inputs

Adds a "Run workflow" button in the Gitea UI. The workflow must be on the default branch to appear.

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Target environment'
        required: true
        type: choice
        options:
          - staging
          - production
      dry_run:
        description: 'Dry run'
        required: false
        type: boolean
        default: false
      version:
        description: 'Version number'
        type: string

Supported input types: string, boolean, choice, number, environment

Access inputs via: ${{ inputs.environment }} or ${{ gitea.event.inputs.environment }}

Context Variables

`gitea.` / `github.`

Both namespaces are identical. Prefer gitea.*.

Variable	Description
`gitea.actor`	Username that triggered the workflow
`gitea.event_name`	Triggering event name (`push`, `pull_request`, etc.)
`gitea.event`	Full event payload object
`gitea.ref`	Full ref (`refs/heads/main`, `refs/pull/1/head`)
`gitea.ref_name`	Short ref name (`main`, `v1.0`)
`gitea.ref_type`	`branch` or `tag`
`gitea.sha`	Full commit SHA
`gitea.repository`	`owner/repo`
`gitea.repository_owner`	Repository owner (user or org name)
`gitea.workspace`	Workspace path on the runner
`gitea.run_id`	Unique ID for this workflow run
`gitea.run_number`	Sequential run number for this workflow
`gitea.server_url`	Gitea instance base URL
`gitea.api_url`	Gitea API URL
`gitea.head_ref`	PR source branch name
`gitea.base_ref`	PR target branch name
`gitea.token`	Auto-generated short-lived job token
`gitea.workflow`	Workflow name
`gitea.job`	Current job ID

Note

: gitea.repository_owner preserves original casing. Use tr '[:upper:]' '[:lower:]' when used in Docker image tags.

`runner.*`

Variable	Description
`runner.os`	`Linux`, `Windows`, or `macOS`
`runner.arch`	`X64`, `ARM64`, etc.
`runner.name`	Runner name
`runner.tool_cache`	Tool cache directory
`runner.temp`	Temp directory

`steps.*`

steps.<step_id>.outputs.<output_name>
steps.<step_id>.conclusion    # success, failure, cancelled, skipped
steps.<step_id>.outcome       # success, failure, cancelled, skipped

`needs.*`

needs.<job_id>.outputs.<output_name>
needs.<job_id>.result         # success, failure, cancelled, skipped

`secrets.*`

secrets.GITEA_TOKEN           # auto-generated job token (cannot push to package registry)
secrets.GITHUB_TOKEN          # alias for the same token
secrets.<SECRET_NAME>         # user-defined secrets

`vars.*`

vars.<VARIABLE_NAME>          # non-sensitive config variables (stored in UPPERCASE)

`inputs.*`

inputs.<input_name>           # for workflow_dispatch and workflow_call

`matrix.` / `strategy.`

matrix.<dimension>            # current matrix combination value
strategy.fail-fast
strategy.max-parallel

Secrets

Scope (highest to lowest priority)

Repository secrets
Organization secrets
User secrets

Rules

Allowed characters: [a-zA-Z0-9_]
Cannot start with GITHUB_, GITEA_, or a number
Case-insensitive

Usage

steps:
  - name: Use secret
    env:
      API_KEY: ${{ secrets.API_KEY }}
    run: ./deploy.sh $API_KEY

Auto Token (`GITEA_TOKEN`)

Automatically injected into every job. Short-lived — invalidated when the job completes.

Known limitation: GITEA_TOKEN / GITHUB_TOKEN cannot push to the Gitea package/container registry. Use a Personal Access Token (PAT) with package scope stored as a manual secret instead.

Variables (`vars`)

Non-sensitive configuration values, visible in logs.

Scope (highest to lowest priority)

Repository variables
Organization variables
User variables

Rules

Allowed characters: [a-zA-Z0-9_]
Cannot start with GITHUB_, GITEA_, CI, or a number
Keys are stored and accessed in UPPERCASE

Usage

steps:
  - run: echo "Deploying to ${{ vars.ENVIRONMENT }}"

Inline `env` (workflow/job/step level)

env:
  GLOBAL_VAR: "value"         # available to all jobs

jobs:
  build:
    env:
      JOB_VAR: "value"        # available to all steps in this job
    steps:
      - env:
          STEP_VAR: "value"   # only this step
        run: echo $STEP_VAR

Built-in Environment Variables

Automatically injected into every step:

Variable	Description
`CI`	Always `true`
`GITHUB_WORKFLOW` / `GITEA_WORKFLOW`	Workflow name
`GITHUB_RUN_ID` / `GITEA_RUN_ID`	Unique run ID
`GITHUB_RUN_NUMBER` / `GITEA_RUN_NUMBER`	Sequential run number
`GITHUB_ACTOR` / `GITEA_ACTOR`	Triggering username
`GITHUB_REPOSITORY`	`owner/repo`
`GITHUB_EVENT_NAME`	Event name
`GITHUB_SHA`	Commit SHA
`GITHUB_REF`	Full ref
`GITHUB_REF_NAME`	Short ref name
`GITHUB_REF_TYPE`	`branch` or `tag`
`GITHUB_HEAD_REF`	PR source branch
`GITHUB_BASE_REF`	PR target branch
`GITHUB_WORKSPACE`	Workspace directory
`GITHUB_SERVER_URL`	Gitea instance URL
`GITHUB_API_URL`	Gitea API URL
`GITHUB_TOKEN` / `GITEA_TOKEN`	Auto job token
`RUNNER_OS`	Runner OS
`RUNNER_ARCH`	Runner architecture
`RUNNER_NAME`	Runner name
`RUNNER_TEMP`	Temp directory
`RUNNER_TOOL_CACHE`	Tool cache directory

Expression Syntax & Functions

Syntax

${{ <expression> }}

# In `if:` blocks, the ${{ }} wrapper is optional:
if: github.ref == 'refs/heads/main'
if: ${{ github.ref == 'refs/heads/main' }}

Operators

Operator	Description
`( )`	Grouping
`[ ]`	Index
`.`	Property access
`!`	Not
`<` `>` `<=` `>=`	Comparison
`==` `!=`	Equality
`&&` `\|\|`	Logical AND / OR

Functions

Function	Description
`contains(search, item)`	True if string/array contains item
`startsWith(str, prefix)`	Case-insensitive prefix check
`endsWith(str, suffix)`	Case-insensitive suffix check
`format(str, val0, val1, ...)`	String formatting with `{0}`, `{1}` placeholders
`join(array, separator)`	Join array with delimiter
`toJSON(value)`	Serialize to JSON string
`fromJSON(value)`	Parse JSON string to object
`hashFiles(path)`	SHA-256 hash of file(s) matching glob
`success()`	True if all previous steps succeeded
`failure()`	True if any previous step failed
`cancelled()`	True if workflow was cancelled
`always()`	Always true; forces step execution

Examples

if: contains(gitea.ref, 'main')
if: startsWith(gitea.ref, 'refs/tags/')
if: always()
if: failure()
if: success() && gitea.ref == 'refs/heads/main'
run: echo ${{ format('Hello {0}', gitea.actor) }}

Runner Labels

Labels map runs-on: values in workflows to runner execution environments.

Label Format

<label>:<schema>:<image>

docker://<image> — run the job in a Docker container
host — run directly on the runner host machine

Examples

# In act_runner config.yaml
runner:
  labels:
    - "ubuntu-latest:docker://gitea/runner-images:ubuntu-latest"
    - "ubuntu-22.04:docker://gitea/runner-images:ubuntu-22.04"
    - "node18:docker://node:18-bullseye"
    - "python311:docker://python:3.11-slim"
    - "native:host"

Runner Scope

Scope	Picks up jobs from
Instance-level	All repos on the Gitea instance
Organization-level	All repos in that organization
Repository-level	That specific repo only

Registering a Runner

# Interactive
./act_runner register

# Non-interactive
./act_runner register \
  --instance https://gitea.example.com \
  --token <registration-token> \
  --name my-runner \
  --labels ubuntu-latest:docker://gitea/runner-images:ubuntu-latest

Get tokens from:

Instance-level: Admin Panel → Actions → Runners
Org-level: Org Settings → Actions → Runners
Repo-level: Repo Settings → Actions → Runners

Differences from GitHub Actions

Gitea Additions

Feature	Details
Absolute action URLs	`uses: https://github.com/actions/checkout@v4` or any git URL
Go-based actions	Actions can be written in Go
Extended cron syntax	`@daily`, `@hourly`, `@weekly`, `@monthly`, `@yearly`
`gitea.*` context	Recommended namespace alias for `github.*`
Permissive context	`env` context usable in more places than GitHub allows
`DEFAULT_ACTIONS_URL`	Server config to pull actions from own Gitea instance instead of GitHub

Behavioral Differences

Behavior	GitHub Actions	Gitea Actions
PR ref	`refs/pull/:n/merge` (merge preview)	`refs/pull/:n/head` (PR head)
Unqualified action source	Always GitHub.com	Configurable via `DEFAULT_ACTIONS_URL`
`GITHUB_TOKEN` for packages	Works	Does not work — use PAT
`permissions:` keyword	Enforced	Ignored
`continue-on-error:`	Supported	Ignored
`timeout-minutes:`	Supported	Ignored

Unsupported Features

Feature	Status
`permissions:` keyword	Ignored
`jobs.<id>.timeout-minutes`	Ignored
`jobs.<id>.continue-on-error`	Ignored
`jobs.<id>.environment`	Ignored
Problem Matchers	Not supported
Log annotations (`::error::`, `::warning::`)	Not supported
`GITEA_TOKEN` for container registry	Does not work — use PAT with `package` scope

Badge URLs

https://<gitea-instance>/<owner>/<repo>/actions/workflows/<workflow-file>/badge.svg

Query Parameters

Parameter	Values	Default
`branch`	Any branch name	Default branch
`event`	Event name (`push`, `pull_request`, etc.)	None
`style`	`flat`, `flat-square`	`flat`

Example

[![Build](https://gitea.jsme.be/Jeffrey/azure-ddns-python/actions/workflows/build-push.yaml/badge.svg?branch=main)](https://gitea.jsme.be/Jeffrey/azure-ddns-python/actions)

13 KiB Raw Blame History

Gitea Actions Reference

Table of Contents

Workflow File Location

Trigger Events (on:)

Supported Events

Filter Options

workflow_dispatch with Inputs

Context Variables

gitea.* / github.*

runner.*

steps.*

needs.*

secrets.*

vars.*

inputs.*

matrix.* / strategy.*

Secrets

Scope (highest to lowest priority)

Rules

Usage

Auto Token (GITEA_TOKEN)

Variables (vars)

Scope (highest to lowest priority)

Rules

Usage

Inline env (workflow/job/step level)

Built-in Environment Variables

Expression Syntax & Functions

Syntax

Operators

Functions

Examples

Runner Labels

Label Format

Examples

Runner Scope

Registering a Runner

Differences from GitHub Actions

Gitea Additions

Behavioral Differences

Unsupported Features

Badge URLs

Query Parameters

Example

Sources

13 KiB

Raw Blame History

Trigger Events (`on:`)

`workflow_dispatch` with Inputs

`gitea.` / `github.`

`runner.*`

`steps.*`

`needs.*`

`secrets.*`

`vars.*`

`inputs.*`

`matrix.` / `strategy.`

Auto Token (`GITEA_TOKEN`)

Variables (`vars`)

Inline `env` (workflow/job/step level)