Gitea Actions CI/CD

Gitea Actions brings GitHub Actions-compatible CI/CD to your self-hosted Gitea instance. Using the same YAML workflow syntax, you can run automated builds, tests, and deployments without relying on external CI services. This guide covers setting up Gitea Actions with runners on your VPS.

Enabling Actions in Gitea

# Edit Gitea configuration
# /etc/gitea/app.ini (or custom/conf/app.ini)
[actions]
ENABLED = true

# Restart Gitea
sudo systemctl restart gitea

Installing act_runner

# Download act_runner (Gitea Actions runner)
wget https://gitea.com/gitea/act_runner/releases/download/v0.2.10/act_runner-0.2.10-linux-amd64
chmod +x act_runner-0.2.10-linux-amd64
sudo mv act_runner-0.2.10-linux-amd64 /usr/local/bin/act_runner

# Generate registration token in Gitea:
# Site Administration > Runners > Create new runner
# Or Repository > Settings > Actions > Runners

# Register runner
act_runner register \
    --instance https://gitea.example.com \
    --token YOUR_REGISTRATION_TOKEN \
    --name "vps-runner" \
    --labels "ubuntu-latest:docker://node:20-bookworm,self-hosted"

# Start runner
act_runner daemon

Runner as Systemd Service

# /etc/systemd/system/act-runner.service
[Unit]
Description=Gitea Actions Runner
After=docker.service

[Service]
Type=simple
User=gitea-runner
ExecStart=/usr/local/bin/act_runner daemon
WorkingDirectory=/home/gitea-runner
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo useradd -r -m -s /bin/bash gitea-runner
sudo usermod -aG docker gitea-runner
sudo systemctl enable --now act-runner

Workflow Examples

# .gitea/workflows/ci.yaml
name: CI Pipeline
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Run linter
        run: npm run lint

      - name: Run tests
        run: npm test

      - name: Build
        run: npm run build

  deploy:
    needs: test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4

      - name: Deploy to production
        env:
          SSH_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
        run: |
          mkdir -p ~/.ssh
          echo "$SSH_KEY" > ~/.ssh/deploy_key
          chmod 600 ~/.ssh/deploy_key
          ssh -i ~/.ssh/deploy_key -o StrictHostKeyChecking=no \
              deploy@production.example.com "cd /opt/app && git pull && npm ci && npm run build && pm2 restart app"

Docker Build Workflow

# .gitea/workflows/docker.yaml
name: Docker Build and Push
on:
  push:
    tags: ["v*"]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Login to Registry
        uses: docker/login-action@v3
        with:
          registry: gitea.example.com
          username: ${{ github.actor }}
          password: ${{ secrets.REGISTRY_TOKEN }}

      - name: Build and Push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: |
            gitea.example.com/${{ github.repository }}:${{ github.ref_name }}
            gitea.example.com/${{ github.repository }}:latest

Secrets Management

# Add secrets in Gitea:
# Repository > Settings > Actions > Secrets
# Or Organization level secrets

# Use in workflows:
# ${{ secrets.MY_SECRET }}

# Common secrets:
# DEPLOY_SSH_KEY - SSH private key for deployment
# REGISTRY_TOKEN - Container registry access token
# DATABASE_URL - Test database connection string

GitHub Actions Compatibility

# Most GitHub Actions work with Gitea Actions:
# - actions/checkout@v4 ✓
# - actions/setup-node@v4 ✓
# - actions/setup-python@v5 ✓
# - actions/setup-go@v5 ✓
# - docker/build-push-action@v5 ✓
# - actions/cache@v4 ✓

# Some Actions need Gitea-specific alternatives:
# - GitHub-specific APIs may not work
# - GitHub Packages references need updating
# - Some marketplace actions are GitHub-only

Summary

Gitea Actions provides GitHub Actions-compatible CI/CD for self-hosted Git repositories. The act_runner executes workflows in Docker containers with the same YAML syntax as GitHub Actions. This gives you unlimited CI/CD minutes on your own infrastructure, data privacy, and the ability to access internal resources during builds. For teams already using Gitea, Actions eliminates the need for external CI services like Jenkins or GitHub Actions.