Using GitHub Actions in Self-Hosted Forgejo

If you’re running a self-hosted Forgejo instance and want to use GitHub Actions, you might have noticed that Forgejo defaults to using data.forgejo.org for action resolution instead of GitHub or your local mirrors. Here’s how to configure it properly.

The Problem

Out of the box, Forgejo tries to resolve actions like actions/checkout@v4 from its own registry at data.forgejo.org. This can cause issues when you want to:

• Use actions directly from GitHub
• Use locally mirrored actions
• Have more control over action resolution

The Solution: Configure DEFAULT_ACTIONS_URL

The key is adding proper actions configuration to your app.ini file. Forgejo resolves actions in a specific order, and you can control this behavior.

Option 1: Direct GitHub Access

Add this to your app.ini:

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

With this configuration, uses: actions/checkout@v4 will fetch directly from https://github.com/actions/checkout.

If your reason for self-hosting Forgejo is to become less dependent on services like Github, this option might not be for you.

Option 2: Use Local Mirrors

If you prefer to mirror actions locally:

[actions]
ENABLED = true
DEFAULT_ACTIONS_URL = self

Important: For this to work, you need to mirror actions with the exact same organization/repository structure. For example:

• Create an organization called actions in your Forgejo instance
• Mirror https://github.com/actions/checkout to actions/checkout
• Now uses: actions/checkout@v4 will use your local mirror

Option 3: Explicit URLs in Workflows

Without changing configuration, you can specify full paths in your workflows:

steps:
  # For GitHub directly
  - uses: https://github.com/actions/checkout@v4
  
  # For your local mirror
  - uses: https://your-forgejo.com/mirrors/checkout@v4

Action Resolution Order

Forgejo resolves actions in this priority:

1. Absolute URLs: uses: https://github.com/actions/checkout@v4
2. Local references (when DEFAULT_ACTIONS_URL = self): Searches your Forgejo instance
3. Default URL: Uses the DEFAULT_ACTIONS_URL setting
4. Forgejo registry: Falls back to data.forgejo.org if nothing else is configured

Testing Your Configuration

Create a simple workflow to verify everything works:

name: Test Actions Configuration
on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
      - name: Print environment
        run: echo "Actions configured successfully!"

Troubleshooting

If actions are still being fetched from data.forgejo.org:

1. Verify restart: Ensure Forgejo fully restarted after configuration changes
2. Check Forgejo version: Older versions might have different configuration options
3. Clear runner cache: Restart your action runners to clear cached definitions
4. Review logs: Check job logs to see where actions are actually being fetched from

Runner Setup

Don’t forget you’ll also need at least one runner configured:

1. Install the Forgejo Runner (act_runner)
2. Register it with your instance using a registration token
3. Start the runner service

Security Considerations

As with using Actions on Github, the same security disclaimers apply here:

• Review third-party actions before using them on your infrastructure
• Consider mirroring frequently-used actions for better performance and reliability
• Ensure your runners have appropriate network access based on your chosen configuration

With these configurations in place, you should have full control over how your Forgejo instance resolves and uses GitHub Actions, whether you prefer direct GitHub access or local mirrors.