picpeak/docs/GITEA_ACTIONS_SETUP.md

Gitea Actions Setup Guide

Prerequisites

1. Gitea Version: Ensure you're running Gitea 1.19.0 or later
2. Gitea Actions Enabled: Check your Gitea configuration

Step 1: Enable Gitea Actions in app.ini

Add or modify these settings in your Gitea app.ini:

[actions]
ENABLED = true
DEFAULT_ACTIONS_URL = https://gitea.com

Step 2: Install Gitea Act Runner

Option A: Using Docker

docker run -d \
  --name gitea-runner \
  --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v gitea-runner-data:/data \
  -e GITEA_INSTANCE_URL=https://gitea.nothaft.cloud \
  -e GITEA_RUNNER_REGISTRATION_TOKEN=<your-registration-token> \
  -e GITEA_RUNNER_NAME=docker-runner \
  gitea/act_runner:latest

Option B: Using Binary

1. Download the act_runner:

wget https://gitea.com/gitea/act_runner/releases/download/v0.2.5/act_runner-0.2.5-linux-amd64
chmod +x act_runner-0.2.5-linux-amd64
sudo mv act_runner-0.2.5-linux-amd64 /usr/local/bin/act_runner

2. Register the runner:

act_runner register \
  --instance https://gitea.nothaft.cloud \
  --token <your-registration-token> \
  --name "my-runner" \
  --labels "ubuntu-latest:docker://node:16-bullseye,ubuntu-22.04:docker://node:16-bullseye"

3. Start the runner:

act_runner daemon

Step 3: Get Registration Token

1. Go to your Gitea instance admin panel
2. Navigate to Site Administration → Actions → Runners
3. Click "Create new Runner"
4. Copy the registration token

Step 4: Repository Settings

1. Go to your repository settings in Gitea
2. Navigate to Settings → Actions → General
3. Ensure Actions are enabled for the repository

Step 5: Convert GitHub Actions to Gitea Actions

While Gitea Actions is mostly compatible with GitHub Actions, there are some differences:

Workflow Location

• GitHub Actions: .github/workflows/
• Gitea Actions: .gitea/workflows/ (preferred) or .github/workflows/

Supported Features

✅ Supported:

• Basic workflow syntax
• Common actions like actions/checkout
• Environment variables
• Secrets
• Artifacts
• Matrix builds

❌ Not Supported:

• Some GitHub-specific actions
• GitHub Packages
• Some advanced features

Step 6: Debug Workflow Issues

If workflows are stuck in "waiting":

1. Check Runner Status:

   # If using Docker
   docker logs gitea-runner
   
   # If using binary
   journalctl -u act_runner -f
   

2. Check Gitea Logs:

   # Check Gitea logs for action-related errors
   tail -f /path/to/gitea/log/gitea.log | grep -i action
   

3. Verify Runner Labels:

   • Ensure your runner has the labels that match your workflow's runs-on
   • Common labels: ubuntu-latest, ubuntu-22.04, ubuntu-20.04

4. Check Repository Permissions:

   • Ensure the repository has Actions enabled
   • Check if there are any branch protection rules blocking Actions

Step 7: Alternative - Use Drone CI

Since you already have Drone CI configured (.drone.yml), you might want to use that instead:

# Your existing .drone.yml is already set up for CI/CD
kind: pipeline
type: docker
name: default
# ... rest of your Drone configuration

Common Issues and Solutions

Issue: Workflows stuck in "waiting"

Solution: No runners available. Register and start a runner.

Issue: Runner can't connect

Solution: Check firewall rules and ensure runner can reach Gitea instance.

Issue: Docker-in-Docker errors

Solution: Mount Docker socket or use privileged mode for runner.

Issue: Actions not showing in UI

Solution: Enable Actions in both Gitea config and repository settings.

Next Steps

1. Check your Gitea version and configuration
2. Install and register a runner
3. Enable Actions for your repository
4. Test with the simple workflow created in .gitea/workflows/test.yml
5. Once working, migrate your GitHub Actions workflows if needed