Forgejo Workflows

Reusable Forgejo Actions workflows for shared CI and multi-runner pipelines.

Workflows

Build: Container

Required Inputs & Secrets

For secrets, navigate to Repository → Settings → Actions → Secrets

Type	Name	Required	Description
Input	job-name	❌	Build job display name. Defaults to Build: Container.
Input	context	❌	Docker build context path. Defaults to ..
Input	file	❌	Dockerfile path. Defaults to Dockerfile.
Input	images	❌	Docker metadata image names. Defaults to ${{ secrets.REGISTRY }}/${{ env.FORGEJO_REPOSITORY }}.
Input	platforms	❌	Comma-separated Docker platforms to build for. Defaults to linux/amd64.
Input	tags	❌	Docker metadata tag rules. Defaults to type=sha.
Input	build-args	❌	Docker build arguments. Defaults to none.
Input	push	❌	Push the built Docker image. Defaults to true.
Secret	REGISTRY	❌	Container registry hostname or URL. Required when pushing.
Secret	REGISTRY_USERNAME	❌	Username used to authenticate with the registry. Required when pushing.
Secret	REGISTRY_TOKEN	❌	Token or password used to authenticate with the registry. Required when pushing.

Example

Build Edge:

name: build-container

on:
  push:
    branches:
      - main

jobs:
  setup-build-container:
    name: "Setup Build: Container"
    uses: forgejo/workflows/.forgejo/workflows/build-container.yaml@main
    with:
      job-name: "Build: Container"
      context: .
      file: Dockerfile
      platforms: linux/amd64,linux/arm64
      tags: |
        type=raw,value=edge
      build-args: APP_VERSION=edge-${{ forgejo.sha }}
      push: true
    secrets:
      REGISTRY: ${{ secrets.REGISTRY }}
      REGISTRY_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
      REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}

Build Release:

name: build-container

on:
  push:
    tags:
      - "*.*.*"

jobs:
  setup-build-container:
    name: "Setup Build: Container"
    uses: forgejo/workflows/.forgejo/workflows/build-container.yaml@main
    with:
      job-name: "Build: Container"
      context: .
      file: Dockerfile
      platforms: linux/amd64,linux/arm64
      tags: |
        type=semver,pattern={{version}}
        type=semver,pattern={{major}}.{{minor}}
        type=semver,pattern={{major}}
        latest
      build-args: APP_VERSION=${{ forgejo.ref_name }}
      push: true
    secrets:
      REGISTRY: ${{ secrets.REGISTRY }}
      REGISTRY_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
      REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}

Build PR:

name: build-container

on:
  pull_request:
    types:
      - opened
      - synchronize
      - reopened

jobs:
  setup-build-container:
    name: "Setup Build: Container"
    uses: forgejo/workflows/.forgejo/workflows/build-container.yaml@main
    with:
      job-name: "Build: Container"
      context: .
      file: Dockerfile
      tags: |
        type=ref,event=pr
      build-args: APP_VERSION=pr-${{ forgejo.event.pull_request.number }}-${{ forgejo.sha }}
      push: true
    secrets:
      REGISTRY: ${{ secrets.REGISTRY }}
      REGISTRY_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
      REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}

Build Branch:

name: build-container

on:
  push:
    branches:
      - main
      - develop
      - feature/**
      - fix/**

jobs:
  setup-build-container:
    name: "Setup Build: Container"
    uses: forgejo/workflows/.forgejo/workflows/build-container.yaml@main
    with:
      job-name: "Build: Container"
      context: .
      file: Dockerfile
      platforms: linux/amd64,linux/arm64
      tags: |
        type=ref,event=branch
      build-args: APP_VERSION=${{ forgejo.ref_name }}-${{ forgejo.sha }}
      push: true
    secrets:
      REGISTRY: ${{ secrets.REGISTRY }}
      REGISTRY_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
      REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}

Build Smoke:

name: build-container

on:
  workflow_dispatch:

jobs:
  setup-build-container:
    name: "Setup Build: Container"
    uses: forgejo/workflows/.forgejo/workflows/build-container.yaml@main
    with:
      job-name: "Build: Container"
      context: .
      file: Dockerfile
      build-args: APP_VERSION=${{ forgejo.sha }}
      push: true
    secrets:
      REGISTRY: ${{ secrets.REGISTRY }}
      REGISTRY_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
      REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}

Build Nightly:

name: build-container

on:
  schedule:
    - cron: "0 3 * * *"

jobs:
  setup-build-container:
    name: "Setup Build: Container"
    uses: forgejo/workflows/.forgejo/workflows/build-container.yaml@main
    with:
      job-name: "Build: Container"
      context: .
      file: Dockerfile
      platforms: linux/amd64,linux/arm64
      tags: |
        type=raw,value=nightly
      build-args: APP_VERSION=nightly-${{ forgejo.sha }}
      push: true
    secrets:
      REGISTRY: ${{ secrets.REGISTRY }}
      REGISTRY_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
      REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}

Build: BYOND Version

Required Inputs & Secrets

For secrets, navigate to Repository → Settings → Actions → Secrets

Type	Name	Required	Description
Input	version	✔️	Full BYOND version to build, such as 516.1683.
Input	job-name	❌	Build job display name. Defaults to Build: BYOND Version.
Input	context	❌	Docker build context path. Defaults to ..
Input	file	❌	Dockerfile path. Defaults to Dockerfile.
Input	images	❌	Docker metadata image names. Defaults to ${{ secrets.REGISTRY }}/${{ env.FORGEJO_REPOSITORY }}.
Input	platforms	❌	Comma-separated Docker platforms to build for. Defaults to linux/amd64.
Input	existing-tag-behavior	❌	Behavior when the exact image tag already exists: fail, skip, or overwrite. Defaults to fail.
Input	push	❌	Push the built Docker image. Defaults to true.
Secret	REGISTRY	❌	Container registry hostname or URL. Required when pushing.
Secret	REGISTRY_USERNAME	❌	Username used to authenticate with the registry. Required when pushing.
Secret	REGISTRY_TOKEN	❌	Token or password used to authenticate with the registry. Required when pushing.

Example

name: build-byond-version

on:
  workflow_dispatch:
    inputs:
      version:
        description: Full BYOND version to build.
        required: true
        type: string
      force_overwrite:
        description: Overwrite existing image tags.
        required: false
        default: false
        type: boolean

jobs:
  setup-build-byond-version:
    name: "Setup Build: BYOND Version"
    uses: forgejo/workflows/.forgejo/workflows/build-byond-version.yaml@main
    with:
      version: ${{ inputs.version }}
      context: .
      file: Dockerfile
      platforms: linux/amd64
      existing-tag-behavior: ${{ inputs.force_overwrite && 'overwrite' || 'fail' }}
      push: true
    secrets:
      REGISTRY: ${{ secrets.REGISTRY }}
      REGISTRY_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
      REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}

Backport: BYOND Major

Required Inputs & Secrets

For secrets, navigate to Repository → Settings → Actions → Secrets

Type	Name	Required	Description
Input	major	✔️	BYOND major version to backport, such as 516.
Input	job-name	❌	Build job display name for each version. Defaults to Build: BYOND Version.
Input	context	❌	Docker build context path. Defaults to ..
Input	file	❌	Dockerfile path. Defaults to Dockerfile.
Input	images	❌	Docker metadata image names. Defaults to ${{ secrets.REGISTRY }}/${{ env.FORGEJO_REPOSITORY }}.
Input	platforms	❌	Comma-separated Docker platforms to build for. Defaults to linux/amd64.
Input	existing-tag-behavior	❌	Behavior when an exact image tag already exists: fail, skip, or overwrite. Defaults to skip.
Input	push	❌	Push the built Docker images. Defaults to true.
Secret	REGISTRY	❌	Container registry hostname or URL. Required when pushing.
Secret	REGISTRY_USERNAME	❌	Username used to authenticate with the registry. Required when pushing.
Secret	REGISTRY_TOKEN	❌	Token or password used to authenticate with the registry. Required when pushing.

Example

name: backport-byond-major

on:
  workflow_dispatch:
    inputs:
      major:
        description: BYOND major version to backport.
        required: true
        type: string
      force_overwrite:
        description: Overwrite existing image tags.
        required: false
        default: false
        type: boolean

jobs:
  setup-backport-byond-major:
    name: "Setup Backport: BYOND Major"
    uses: forgejo/workflows/.forgejo/workflows/backport-byond-major.yaml@main
    with:
      major: ${{ inputs.major }}
      context: .
      file: Dockerfile
      platforms: linux/amd64
      existing-tag-behavior: ${{ inputs.force_overwrite && 'overwrite' || 'skip' }}
      push: true
    secrets:
      REGISTRY: ${{ secrets.REGISTRY }}
      REGISTRY_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
      REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}

Build: Dotnet

Required Inputs & Secrets

For secrets, navigate to Repository → Settings → Actions → Secrets

Type	Name	Required	Description
Input	job-name	❌	Build job display name. Defaults to Build: Dotnet.
Input	dotnet-version	❌	Optional .NET SDK version or versions to use.
Input	cache	❌	Enable NuGet package caching. Defaults to false.
Input	architecture	❌	Optional .NET SDK architecture to install.
Input	project	❌	Project, solution, or directory to build. Defaults to ..
Input	configuration	❌	.NET build configuration. Defaults to Release.
Input	build-args	❌	Additional arguments passed to dotnet build.
Input	artifact-name	❌	Artifact name to create when artifact-upload-path is set. Defaults to build-dotnet.
Input	artifact-upload-path	❌	File, directory, or glob path to upload as an artifact. When empty, no artifact is uploaded.
Input	artifact-retention-days	❌	Number of days to retain the uploaded artifact. Defaults to repository policy.
Input	artifact-if-no-files-found	❌	Behavior when artifact-upload-path does not match files. Defaults to error.

Example

Build:

name: build-dotnet

on:
  push:
    branches:
      - main

jobs:
  setup-build-dotnet:
    name: "Setup Build: Dotnet"
    uses: forgejo/workflows/.forgejo/workflows/build-dotnet.yaml@main
    with:
      job-name: "Build: Dotnet"
      dotnet-version: 8.0.x
      project: .
      configuration: Release

Create: Release

Required Inputs & Secrets

For secrets, navigate to Repository → Settings → Actions → Secrets

Type	Name	Required	Description
Input	release-artifacts	❌	Newline-separated file paths or glob patterns to attach. Overrides downloaded artifact defaults.
Input	artifact-name	❌	Artifact name to download before attaching release files.
Input	artifact-download-path	❌	Download destination for artifact-name and default release attachment source. Defaults to artifacts.
File	CHANGELOG.md	✔️	Keep a Changelog file containing a released Semantic Versioning section, such as ## [1.0.0] - YYYY-MM-DD.

Example

Release Files:

name: create-release

on:
  push:
    tags:
      - "*.*.*"

jobs:
  setup-create-release:
    name: "Setup Create: Release"
    uses: forgejo/workflows/.forgejo/workflows/create-release.yaml@main
    with:
      release-artifacts: |
        dist/*.tar.gz
        checksums.txt

Build Then Release:

name: create-release

on:
  push:
    tags:
      - "*.*.*"

jobs:
  setup-build-dotnet:
    name: "Setup Build: Dotnet"
    uses: forgejo/workflows/.forgejo/workflows/build-dotnet.yaml@main
    with:
      dotnet-version: 8.0.x
      project: src/App/App.csproj
      build-args: --output dist
      artifact-name: app-dist
      artifact-upload-path: dist

  setup-create-release:
    name: "Setup Create: Release"
    needs: setup-build-dotnet
    uses: forgejo/workflows/.forgejo/workflows/create-release.yaml@main
    with:
      artifact-name: ${{ needs.setup-build-dotnet.outputs.artifact-name }}

Release: Jellyfin Plugin

Required Inputs & Secrets

For secrets, navigate to Repository → Settings → Actions → Secrets

Type	Name	Required	Description
Input	dotnet-version	❌	.NET SDK version to use. Defaults to 9.0.x.
Input	dotnet-configuration	❌	.NET build configuration. Defaults to Release.
Input	dotnet-framework	❌	Optional target framework passed to JPRM.
Input	plugin-path	❌	Jellyfin plugin project root containing build.yaml. Defaults to ..
Input	manifest-path	❌	Jellyfin plugin repository manifest path. Defaults to manifest.json.
Input	manifest-branch	❌	Branch where the manifest is committed. Defaults to master.
Input	test-command	❌	Optional test command to run before packaging.
Input	git-author-name	❌	Git author name for manifest commits. Defaults to forgejo-actions.
Input	git-author-email	❌	Git author email for manifest commits. Defaults to actions@forgejo.local.
Input	manifest-commit-message	❌	Commit message for manifest updates. Defaults to Update Jellyfin plugin manifest.
File	CHANGELOG.md	✔️	Keep a Changelog file containing a released Semantic Versioning section for the pushed tag.
File	build.yaml	✔️	JPRM plugin metadata file used to package the Jellyfin plugin.
File	manifest.json	❌	Jellyfin plugin repository manifest. Created if it does not exist on manifest-branch.

Example

name: release-jellyfin-plugin

on:
  push:
    tags:
      - "*.*.*"

jobs:
  setup-release-jellyfin-plugin:
    name: "Setup Release: Jellyfin Plugin"
    uses: forgejo/workflows/.forgejo/workflows/release-jellyfin-plugin.yaml@main
    with:
      dotnet-version: 9.0.x
      dotnet-framework: net9.0
      test-command: dotnet test App.sln --configuration Release --verbosity normal

Deploy

Required Inputs & Secrets

For secrets, navigate to Repository → Settings → Actions → Secrets

Type	Name	Required	Description
Input	SSH_HOST	✔️	SSH host or server address used for deployment.
Input	SSH_PORT	✔️	SSH port used to connect to the deployment server.
Input	SSH_USER	✔️	SSH username used to authenticate with the deployment server.
Secret	SSH_KEY	✔️	Private SSH key used to authenticate with the deployment server.
Input	SSH_DEPLOY_PATH	✔️	Remote directory path where the application is deployed.

Example

name: deploy

on:
  workflow_dispatch:

jobs:
  setup-deploy:
    name: Setup Deploy
    uses: forgejo/workflows/.forgejo/workflows/deploy.yaml@main
    secrets:
      SSH_HOST: ${{ secrets.SSH_HOST }}
      SSH_PORT: ${{ secrets.SSH_PORT }}
      SSH_USER: ${{ secrets.SSH_USER }}
      SSH_KEY: ${{ secrets.SSH_KEY }}
      SSH_DEPLOY_PATH: ${{ secrets.SSH_DEPLOY_PATH }}