Running GitHub Actions Workflows on Forgejo: A Practical Migration Guide

The Problem: CI/CD Portability Without GitHub Lock-in

Teams migrating from GitHub to self-hosted Forgejo often face a painful choice: rewrite all their CI/CD workflows or abandon Actions entirely. The good news is that Forgejo's built-in Actions compatibility eliminates this trade-off. Workflows defined in .github/workflows/*.yml execute natively on Forgejo runners, preserving your existing automation while giving you full control over your CI/CD infrastructure.

How Forgejo Actions Compatibility Works

Forgejo implements the Actions API compatible with Gitea Actions (the upstream project that Forgejo forked from). When you push a workflow file to .github/workflows/test.yml, Forgejo automatically detects and schedules it for execution. Built-in runners support Docker containers and shell scripts natively, while self-hosted runners can be registered via the forgejo-admin CLI.

The key difference from GitHub Actions is the runner environment: Forgejo's hosted runners run on the same server as your instance, eliminating network egress costs but requiring adequate local resources. Secrets management integrates with repository settings UI, and webhooks plus scheduled triggers work like GitHub Actions.

Migrating a Simple Test Workflow

Let's migrate a basic CI workflow that tests a Node.js application:

name: CI Pipeline
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [18.x, 20.x]
    steps:
      - uses: actions/checkout@v4
      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'
      - run: npm ci
      - run: npm test

This workflow works unchanged on Forgejo because it uses standard Actions syntax and official actions that are compatible with Gitea Actions v1.0+ features. The ubuntu-latest runner resolves to Forgejo's built-in Docker container with Ubuntu pre-installed.

Verification Steps

1. Check version compatibility: Run forgejo --version on your server. Forgejo 1.21+ includes stable Actions support.
2. Create the workflow file: Add the YAML above to .github/workflows/ci.yml in your repository.
3. Push and verify: Commit and push. Navigate to the 'Actions' tab in Forgejo to confirm the workflow appears and executes successfully.
4. Monitor runner status: Check forgejo admin list-runners to ensure runners are available.

If the workflow doesn't appear, verify that the actions_enabled setting in app.ini is set to true.

Trade-offs and Limitations

While Forgejo Actions compatibility is robust, there are important limitations:

• Marketplace gaps: Actions from GitHub's marketplace may require minor YAML adjustments or may not be available if they depend on GitHub-specific APIs.
• Runner version sync: Self-hosted runners must match your Forgejo server version for full compatibility—upgrading Forgejo requires updating runners.
• Resource constraints: Built-in runners share resources with your Forgejo instance, so resource-intensive workflows may impact Git operations.

Custom actions using JavaScript or Docker work as expected, but composite actions and certain marketplace actions may need testing. The Forgejo community maintains a curated list of verified compatible actions at gitea.io/docs.

Actionable Next Steps

Start by verifying your Forgejo version supports Actions, then migrate one non-critical workflow to test compatibility. Use the Actions tab to monitor execution and adjust any actions that fail. For production workflows, consider setting up dedicated self-hosted runners on powerful machines to isolate CI/CD workloads from your main Forgejo instance.

Once verified, you can confidently migrate your entire CI/CD pipeline while maintaining full control over your automation infrastructure.