tendril/docs/GITEA/Gitea-Actions-Guide.md

Gitea Actions Guide for LLMs

Purpose: Guide for LLMs working with Gitea Actions (CI/CD system compatible with GitHub Actions).

Reference: Gitea Actions Documentation

---

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:

name: Workflow Name

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run command
        run: echo "Hello, Gitea Actions!"

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 Actions uses Gitea Runners (similar to GitHub Runners):

• Self-hosted runners
• Can run on various platforms
• Register runners with Gitea instance
• Similar to GitHub Actions runners

---

Differences from GitHub Actions

1. Actions Marketplace

• GitHub: Centralized marketplace at github.com/marketplace
• Gitea: Actions can be downloaded from any Git website
• Impact: Actions plugins can come from GitHub, Gitea, or any Git repository

2. Runner Registration

• GitHub: Runners managed by GitHub (or self-hosted)
• Gitea: All runners are self-hosted
• Impact: Must register and manage your own runners

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

---

Creating Workflows

Basic Workflow Template

name: Workflow Name

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  job-name:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Run command
        run: |
          echo "Running in Gitea Actions"
          # Your commands here

Using Actions from Different Sources

From GitHub:

- uses: actions/checkout@v4

From Gitea:

- uses: gitea.com/owner/action@v1

From Any Git Repository:

- uses: https://git.example.com/owner/action@v1

---

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"

When Creating Workflow Files

1. Use .github/workflows/ directory (same as GitHub)
2. YAML format is identical to GitHub Actions
3. Reference in documentation as "Gitea Actions workflows"
4. Note compatibility when relevant

Example Documentation

## CI/CD Workflows

This repository uses **Gitea Actions** for continuous integration and deployment.

**Note**: Gitea Actions is compatible with GitHub Actions, so workflows use the same YAML format and `.github/workflows/` directory structure.

### Workflows

- **`kb-lint.yml`** - Validates KB file naming and frontmatter
- **`kb-index-update.yml`** - Auto-updates KB index on push

All workflows are located in `.github/workflows/` and use standard GitHub Actions YAML format.

---

Common Workflow Patterns

Linting Workflow

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

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

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

---

Troubleshooting

Workflow Not Running

1. Check runner registration: Ensure runners are registered with Gitea instance
2. Check workflow syntax: Validate YAML syntax
3. Check triggers: Verify on: conditions match events
4. Check permissions: Ensure workflow has necessary permissions

Actions Not Found

1. Check action source: Verify action URL is correct
2. Check network access: Ensure runner can access action repository
3. Use full URL: For custom actions, use full Git URL

Runner Issues

1. Check runner status: Verify runner is online and connected
2. Check runner labels: Ensure runs-on matches runner labels
3. Check runner logs: Review runner logs for errors

---

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/

---

Location: docs/GITEA/Gitea-Actions-Guide.md
Last Updated: 2025-01-27