tendril/kb/02_systems/2025-11-11--gitea-actions-guide--howto.md

---
title: "Gitea Actions Guide"
date: "2025-11-11"
captured_at: "2025-11-11"
author: ["datawarrior"]
source: { kind: doc, ref: "docs/GITEA/Gitea-Actions-Guide.md" }
source_type: personal_note
project: ["tendril"]
related_projects: ["tendril"]
topics: ["gitea", "actions", "ci-cd", "workflows", "automation"]
tags: ["gitea", "actions", "ci-cd", "workflows", "automation", "github-compatible"]
type: howto
status: active
phase_relevance: ["phase-03"]
routing_hint: "Gitea Actions CI/CD guide - infrastructure/tooling documentation"
proposed_path: "kb/02_systems/"
routing_confidence: 0.95
related: ["docs/GITEA/Gitea-Actions-Guide.md", ".github/workflows/"]
summary: "Comprehensive guide to Gitea Actions (CI/CD system compatible with GitHub Actions). Covers compatibility, workflow creation, common patterns, troubleshooting, and LLM documentation guidelines."
key_takeaways: []
action_candidates: []
---

# Gitea Actions Guide

## Overview

**Gitea Actions** is Gitea's CI/CD system that is **compatible with GitHub Actions**. This means:
- Same YAML workflow format
- Same `.github/workflows/` directory structure
- Same triggers and syntax
- Existing GitHub Actions workflows work with minimal or no modifications
- Actions plugins can be downloaded from any Git website

## Key Compatibility Points

### 1. Directory Structure
**Same as GitHub**:
```
.github/
└── workflows/
    ├── workflow1.yml
    ├── workflow2.yml
    └── ...
```

### 2. YAML Format
**Identical to GitHub Actions** - Same workflow syntax, triggers, jobs, steps

### 3. Triggers
**Same triggers as GitHub Actions**:
- `push` - On push to repository
- `pull_request` - On pull request events
- `workflow_dispatch` - Manual trigger
- `schedule` - Scheduled runs (cron syntax)
- `repository_dispatch` - External events

### 4. Runners
- **Gitea Runners** (similar to GitHub Runners)
- Self-hosted runners
- Can run on various platforms
- Register runners with Gitea instance

## Differences from GitHub Actions

1. **Actions Marketplace**
   - GitHub: Centralized marketplace
   - Gitea: Actions can be downloaded from any Git website

2. **Runner Registration**
   - GitHub: Runners managed by GitHub (or self-hosted)
   - Gitea: All runners are self-hosted

3. **Some GitHub-Specific Features**
   - Some GitHub Actions features may not be available
   - Check Gitea Actions documentation for specific limitations
   - Most common workflows work identically

## Common Workflow Patterns

### Linting Workflow
```yaml
name: Lint

on:
  push:
    paths:
      - 'src/**/*.rs'
  pull_request:
    paths:
      - 'src/**/*.rs'

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run linter
        run: cargo clippy
```

### Testing Workflow
```yaml
name: Test

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: cargo test
```

### Index Update Workflow
```yaml
name: Update Index

on:
  push:
    branches: [ main ]
    paths:
      - 'kb/**/*.md'

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Generate index
        run: ./kb/scripts/generate-index.sh
      - name: Commit changes
        run: |
          git config user.name "Gitea Actions"
          git config user.email "actions@gitea.io"
          git add kb/_index.md
          git commit -m "chore: update KB index" || exit 0
          git push
```

## For LLMs: Documentation Guidelines

### When Creating Workflow Documentation

1. **Reference as "Gitea Actions"**:
   - "This workflow runs in Gitea Actions"
   - "Gitea Actions will execute this workflow on push"

2. **Note Compatibility**:
   - "Gitea Actions is compatible with GitHub Actions"
   - "This workflow uses the same YAML format as GitHub Actions"

3. **Use Correct Terminology**:
   - "Gitea Actions workflows" (not "GitHub Actions workflows")
   - "Gitea Runners" (not "GitHub Runners")
   - But note: "Same format as GitHub Actions"

## Troubleshooting

### Workflow Not Running
1. Check runner registration
2. Check workflow syntax
3. Check triggers
4. Check permissions

### Actions Not Found
1. Check action source
2. Check network access
3. Use full URL for custom actions

### Runner Issues
1. Check runner status
2. Check runner labels
3. Check runner logs

## References

- **Gitea Actions Docs**: https://docs.gitea.com/usage/actions/
- **Gitea Runner**: https://docs.gitea.com/usage/actions/runner/
- **Workflow Syntax**: https://docs.gitea.com/usage/actions/usage/

---

**Original Location**: `docs/GITEA/Gitea-Actions-Guide.md`  
**Last Updated**: 2025-01-27  
**Related**: 
- `.github/workflows/` - Workflow files
- `docs/GITEA/Gitea-Basics.md`
- `docs/GITEA/Gitea-Workflows.md`