michaelschiemer/docs/gitea-actions-setup.md

Gitea Actions Setup Guide

Quick setup guide for enabling Gitea Actions on your self-hosted Gitea instance.

Prerequisites

• Gitea 1.19+ (Actions support)
• Gitea Runner installed and configured
• Repository with .gitea/workflows/ directory

1. Enable Gitea Actions

Check if Actions are enabled

Visit your Gitea repository and check if you see an "Actions" tab. If not, Actions need to be enabled.

Enable Actions in Gitea Configuration

Edit app.ini (usually in /etc/gitea/app.ini or custom/conf/app.ini):

[actions]
ENABLED = true
# Do NOT set DEFAULT_ACTIONS_URL - Gitea will automatically use its own instance
# Setting DEFAULT_ACTIONS_URL to a custom URL is no longer supported

Restart Gitea:

sudo systemctl restart gitea

2. Install Gitea Runner

Download and Install

# Download latest runner
wget https://dl.gitea.com/act_runner/latest/act_runner-latest-linux-amd64

# Make executable
chmod +x act_runner-latest-linux-amd64
sudo mv act_runner-latest-linux-amd64 /usr/local/bin/act_runner

Register Runner

1. Generate registration token in Gitea:

   • Site Admin → Actions → Runners → Create new Runner
   • Copy the registration token

2. Register the runner:

act_runner register \
  --instance https://your-gitea-instance.com \
  --token YOUR_REGISTRATION_TOKEN \
  --name runner-01

3. Start the runner:

# Test run
act_runner daemon

# Or as systemd service
sudo systemctl enable gitea-runner
sudo systemctl start gitea-runner

Systemd Service (Optional)

Create /etc/systemd/system/gitea-runner.service:

[Unit]
Description=Gitea Actions Runner
After=network.target

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

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable gitea-runner
sudo systemctl start gitea-runner
sudo systemctl status gitea-runner

3. Configure Repository Secrets

For automated Gitea issue creation, configure a GITEA_TOKEN secret:

Generate Access Token

1. Navigate to: User Settings → Applications → Manage Access Tokens
2. Click "Generate New Token"
3. Token name: CI_SECURITY_SCANNER
4. Select scopes:
   • write:issue (required for creating issues)
   • read:repository (recommended)
5. Generate and copy the token immediately (it won't be shown again)

Add Repository Secret

1. Navigate to: Repository → Settings → Secrets
2. Click "Add Secret"
3. Name: GITEA_TOKEN
4. Value: Paste the access token from above
5. Save

4. Verify Workflow Configuration

Your repository should have:

.gitea/
└── workflows/
    └── security-scan.yml

Check workflow syntax:

cat .gitea/workflows/security-scan.yml

5. Test the Workflow

Manual Trigger

1. Navigate to repository → Actions
2. Select "Security Vulnerability Scan" workflow
3. Click "Run workflow"
4. Select branch (e.g., main)
5. Click "Run"

Monitor Execution

1. Click on the running workflow
2. View real-time logs
3. Check job status (success/failure)
4. Download artifacts if needed

Expected Output

Successful scan:

✓ Checkout code
✓ Setup PHP
✓ Validate composer.json
✓ Install dependencies
✓ Run Composer Security Audit
✓ Parse audit results
✓ Upload audit results
✓ Summary

Status: ✅ No security vulnerabilities detected

Failed scan (vulnerabilities found):

✓ Checkout code
✓ Setup PHP
✓ Validate composer.json
✓ Install dependencies
✓ Run Composer Security Audit
✗ Parse audit results

Status: ❌ Security vulnerabilities detected

6. Troubleshooting

Actions Tab Not Visible

Problem: Actions tab not showing in repository

Solution:

1. Verify Actions enabled in app.ini
2. Restart Gitea: sudo systemctl restart gitea
3. Clear browser cache
4. Check Gitea version >= 1.19

Runner Not Executing Workflows

Problem: Workflows stay in "waiting" status

Solution:

1. Check runner status: systemctl status gitea-runner
2. Verify runner registration: Check Gitea Admin → Runners
3. Check runner logs: journalctl -u gitea-runner -f
4. Restart runner: systemctl restart gitea-runner

GITEA_TOKEN Not Working

Problem: "GITEA_TOKEN not configured" warning in logs

Solution:

1. Verify secret exists: Repository → Settings → Secrets
2. Check secret name is exactly GITEA_TOKEN (case-sensitive)
3. Regenerate token with correct permissions
4. Re-add secret to repository

Workflow Syntax Errors

Problem: Workflow fails with syntax errors

Solution:

1. Validate YAML syntax: yamllint .gitea/workflows/security-scan.yml
2. Check indentation (use spaces, not tabs)
3. Verify action references use https:// URLs for Gitea
4. Compare with working example workflows

PHP Setup Fails

Problem: Setup PHP step fails

Solution:

1. Verify runner has network access
2. Check if setup-php action is accessible
3. Try using specific PHP version: php-version: '8.4.0'
4. Check runner logs for detailed error messages

7. Gitea Runner Configuration

Custom Runner Configuration

Edit .runner config file:

log:
  level: info

runner:
  # Number of concurrent jobs
  capacity: 1

  # Timeout for a single job
  timeout: 3h

  # Environment variables
  envs:
    COMPOSER_ALLOW_SUPERUSER: "1"
    COMPOSER_HOME: "/tmp/composer"

cache:
  enabled: true
  dir: "/var/cache/gitea-runner"

container:
  network: "bridge"
  privileged: false

Resource Limits

For security scanning workloads, recommended runner specs:

• CPU: 2 cores minimum
• RAM: 2GB minimum
• Disk: 10GB available
• Network: Stable internet connection

8. Monitoring and Maintenance

View Runner Status

# Via Gitea UI
Site Admin → Actions → Runners

# Via systemd
systemctl status gitea-runner

# View logs
journalctl -u gitea-runner -f --since "1 hour ago"

Workflow Execution History

Navigate to: Repository → Actions

• View all workflow runs
• Filter by status (success/failure)
• Download artifacts
• Re-run failed workflows

Cleanup Old Artifacts

Artifacts are retained for 30 days by default. To manually clean up:

1. Repository → Actions → Artifacts
2. Select old artifacts
3. Delete

Or configure automatic cleanup in workflow:

retention-days: 7  # Keep for 1 week only

9. Advanced Configuration

Matrix Builds (Multiple PHP Versions)

jobs:
  security-audit:
    strategy:
      matrix:
        php-version: ['8.2', '8.3', '8.4']

    steps:
      - name: Setup PHP ${{ matrix.php-version }}
        uses: https://github.com/shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php-version }}

Conditional Execution

# Only run on production branch
jobs:
  security-audit:
    if: github.ref == 'refs/heads/main'

Notifications

Add notification step for critical failures:

- name: Send notification on failure
  if: failure() && github.event_name == 'schedule'
  run: |
    curl -X POST https://your-webhook-url.com/alert \
      -H "Content-Type: application/json" \
      -d '{"status":"failure","workflow":"security-scan"}'

10. Security Best Practices

Runner Security

1. Isolate runners: Use dedicated VM/container for runners
2. Network security: Restrict runner network access
3. User permissions: Run as non-root user
4. Update regularly: Keep runner and Gitea updated

Token Security

1. Minimal permissions: Only grant required scopes
2. Token rotation: Rotate tokens every 90 days
3. Secret storage: Never commit secrets to repository
4. Access audit: Regularly review token usage logs

Workflow Security

1. Action pinning: Pin actions to specific versions
2. Input validation: Validate all workflow inputs
3. Artifact encryption: Encrypt sensitive artifacts
4. Log sanitization: Avoid logging secrets

Resources

• Gitea Actions Documentation
• Act Runner Repository
• Workflow Syntax Reference
• Security Best Practices

Support

For issues with:

• Gitea Actions: Check Gitea Discourse
• Runner Issues: File issue on act_runner repo
• Workflow Syntax: Refer to GitHub Actions syntax (mostly compatible)