Forgejo Actions Compatibility

Forgejo Actions Compatibility

Forgejo (and GitHub Enterprise Server / GHES) ships with an older version of the GitHub Actions runner that does not support the GitHub Actions Artifact API v2. Using actions/upload-artifact@v4 or actions/download-artifact@v4 in workflows running on Forgejo 14.x will fail at runtime.

Why This Happens

The @v4 versions of the artifact actions were rewritten to use GitHub’s new Artifact API v2 (also called the “Actions Artifact Service” or “Blob Storage” API). This API is only available on github.com and GHES ≥ 3.12 / Forgejo (future release).

Forgejo 14.x and GHES ≤ 3.11 still use the legacy Artifact API v1, which is served by the Actions runner cache service. The @v3 actions communicate with this older API — they work correctly on self-hosted Forgejo instances.

Compatibility Table

Action version	GitHub.com	GHES ≥ 3.12	Forgejo 14.x	GHES ≤ 3.11
actions/upload-artifact@v4	✅	✅	❌	❌
actions/download-artifact@v4	✅	✅	❌	❌
actions/upload-artifact@v3	✅	✅	✅	✅
actions/download-artifact@v3	✅	✅	✅	✅
actions/cache@v4	✅	✅	✅	✅
actions/checkout@v4	✅	✅	✅	✅
oven-sh/setup-bun@v2	✅	✅	✅	✅

Fix

Replace @v4 with @v3 for upload and download artifact steps:

# ❌ Fails on Forgejo 14.x — uses Artifact API v2
- uses: actions/upload-artifact@v4
  with:
    name: build-output
    path: dist/

- uses: actions/download-artifact@v4
  with:
    name: build-output

# ✅ Works on Forgejo 14.x — uses legacy Artifact API v1
- uses: actions/upload-artifact@v3
  with:
    name: build-output
    path: dist/

- uses: actions/download-artifact@v3
  with:
    name: build-output

Working Example

A complete workflow that builds and tests in separate jobs, passing artifacts between them:

name: CI

on:
  push:
    branches: [main]
  pull_request:

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

      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: "1.3.0"

      - name: Install dependencies
        run: bun install

      - name: Build
        run: bun run build

      - name: Upload build artifacts
        uses: actions/upload-artifact@v3       # @v3 required for Forgejo
        with:
          name: dist
          path: dist/
          retention-days: 7
          if-no-files-found: error

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

      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: "1.3.0"

      - name: Download build artifacts
        uses: actions/download-artifact@v3     # @v3 required for Forgejo
        with:
          name: dist
          path: dist/

      - name: Run tests
        run: bun test

Notes

• retention-days — fully supported in @v3 (range: 1–90 days)
• if-no-files-found — fully supported in @v3 (values: warn, error, ignore)
• The @v3 API has no meaningful feature gap for typical CI use cases
• This restriction applies to all Forgejo instances regardless of the runner being self-hosted or the built-in Forgejo runner (forgejo-runner)

Error Symptoms

If you accidentally use @v4 on Forgejo, the action step fails with an error similar to:

Error: Failed to create a package: 403 Forbidden

or

Error: Unable to upload artifact: 404 Not Found

These errors come from the @v4 action attempting to contact the Artifact API v2 endpoint that does not exist on this Forgejo instance.