Getting Started with Forgejo Actions: Build CI/CD Right Inside Your Self‑Hosted Git Server

Problem

Teams that host their own Forgejo instance often want a lightweight CI/CD solution that doesn’t require a separate service. Traditionally, they would spin up an external runner, configure webhooks, or maintain ad‑hoc scripts that run on a VPS. This extra infrastructure adds operational overhead and can become a single point of failure.

Thesis

Forgejo Actions provides a native, Gitea‑compatible workflow engine that runs directly on the Forgejo server. By enabling Actions, you can define YAML pipelines inside your repositories, trigger them on pushes or pull‑request merges, and keep all CI/CD artifacts within the same environment.

Enabling Actions on a 1.21+ Forgejo Instance

Actions are only available in Forgejo 1.21 and newer. If your instance is older, upgrade first. Once you have a compatible version, follow these steps:

1. Admin Panel Toggle
   Log in as an administrator, navigate to Admin → Actions, and switch ENABLE_ACTIONS to true. This writes to app.ini under the [actions] section.
2. Install the Act Runner
   Forgejo uses the open‑source act runner. Download the binary for your OS, place it in /usr/local/bin/act, and set executable permissions.

   curl -L https://github.com/forgejo/act/releases/download/v0.1.0/act_linux_amd64 -o /usr/local/bin/act
   chmod +x /usr/local/bin/act
   

3. Configure the Runner Service
   Create a systemd unit that starts the runner when the Forgejo service starts. Example /etc/systemd/system/forgejo-act.service:

   [Unit]
   Description=Forgejo Actions Runner
   After=forgejo.service
   
   [Service]
   User=forgejo
   Group=forgejo
   ExecStart=/usr/local/bin/act --repo /var/lib/forgejo/repositories --config /etc/forgejo/act.yaml
   Restart=on-failure
   
   [Install]
   WantedBy=multi-user.target
   

   Enable and start it:

   systemctl enable --now forgejo-act
   

4. Verify Runner Status
   Check the logs for startup messages:

   journalctl -u forgejo-act -f
   

   You should see a line indicating the runner is listening on the Actions API endpoint.

Example Workflow: Run Go Tests and Publish an Artifact

Create a file named .forgejo/workflows/ci.yml in the root of your repository:

name: Go CI
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Set up Go
        uses: actions/setup-go@v3
        with:
          go-version: '1.22'
      - name: Run Tests
        run: go test ./...
      - name: Upload Artifact
        uses: actions/upload-artifact@v3
        with:
          name: test-results
          path: ./test-results.xml

Commit and push this file to main. Open the repository page, click the Actions tab, and you should see a queued job that runs to completion. The artifact will appear in the job summary.

Limitations & Trade‑offs

• No Matrix Builds: The current runner implementation doesn’t support parallel matrix jobs. For complex test matrices, you’ll need an external runner or custom scripts.
• Resource Contention: Workflows run on the same machine as the Git service. Heavy builds can spike CPU or memory usage, potentially slowing down repository operations. Monitor top or htop during peak times.
• Scaling Challenges: The built‑in runner starts a single container per job. Scaling to dozens of concurrent runs requires manual configuration of multiple runner instances or integrating with Kubernetes.
• Limited Runner Features: Features like self‑hosted labels, caching, and secret management are still under development. Check the official docs for the latest capabilities.

Actionable Next Steps

1. Enable Actions on your Forgejo instance as described above.
2. Start with a simple workflow (like the Go CI example) to confirm the pipeline runs.
3. Monitor resource usage during the first few runs. If you notice performance degradation, consider allocating more CPU/memory to the runner or moving it to a dedicated VM.
4. Explore adding secrets via the admin panel (Admin → Secrets) and reference them in your workflow with env: or secrets:.
5. When you need matrix builds or advanced caching, evaluate external runners (e.g., GitHub Actions self‑hosted runners or Jenkins) and configure them to listen to the same repository via webhooks.
6. Document the workflow in your README so new contributors know the CI flow and can trigger local runs with act CLI.

By following this guide, you’ll have a fully self‑hosted CI/CD pipeline that keeps code, tests, and artifacts within your Forgejo ecosystem. While the native Actions feature is still evolving, it’s a powerful starting point for teams that value operational simplicity and data locality.