Migration of Downstream Repositories to New Workflows

[DanielRadlAMR]

#1881

🧭 Overview

@Rocket-Quack has recently reworked our GitHub Actions workflows in this repository to standardize and centralize CI/CD logic. These workflows are now intended to be reused across multiple dependent repositories.

As a result, all downstream repositories that previously relied on the old workflow implementations must be migrated to use the new reusable workflows.

Only after all dependent repositories have been migrated can we safely remove the legacy workflow implementation.

🎯 Goal

• Migrate all dependent repositories to use the new centralized/reusable workflows
• Ensure feature parity and CI/CD stability during migration
• Fully deprecate and remove old workflow implementations once migration is complete

📊 Tracking

We will maintain a list of repositories and their migration status:

Repository	Status	PR	Notes
frappe	🟡 In progress	frappe/frappe#38814	@DanielRadlAMR
erpnext	🟡 In progress	frappe/erpnext#54498	@DanielRadlAMR
charts	⬜ Not started
hrms	⬜ Not started
gantt	⬜ Not started
books	✅ Done	---	Does not use Frappe Docker
helpdesk	🟡 In progress	frappe/hrms#4434	@Rocket-Quack
lms	⬜ Not started
crm	🟡 In progress	frappe/crm#2107	@Rocket-Quack
builder	⬜ Not started
bench	⬜ Not started
insights	⬜ Not started
drive	⬜ Not started
press	✅ Done	---	Does not use Frappe Docker
education	⬜ Not started
gameplan	⬜ Not started
print_designer	⬜ Not started
wiki	⬜ Not started
lending	⬜ Not started
mail	⬜ Not started
helm	⬜ Not started
meet	⬜ Not started
studio	⬜ Not started
webshop	⬜ Not started
blog	⬜ Not started
writer	⬜ Not started

✅ Done 🟡 In progress ⬜ Not started 🆘 Help needed

If a PR already exists for a repository, please feel free to support it and help move it forward.

[DanielRadlAMR]

@Rocket-Quack can you check if you are able to edit the issue text?

[Rocket-Quack]

@Rocket-Quack can you check if you are able to edit the issue text?

Yes it works
I added a column for links to the PRs. Maybe that will help with the overview.

[DanielRadlAMR]

Issue Template to create issues in the affected repos:

Title:

chore: migrate to new docker publish workflow

### 🔄 Migration Required: Update Docker Publish Workflow Reference

This repository is currently using the **legacy Docker publish workflow**, which has been replaced with a new standardized workflow.

---

### 📦 What changed

A new workflow is now used for publishing Docker images:

* **New workflow:**
  https://github.com/frappe/frappe_docker/blob/main/.github/workflows/core-build-stable.yml

The previous workflow is still functional for now but is considered **legacy** and will be removed once all dependent repositories have been migrated.

---

### ⚠️ Required change

Please update all references in this repository from the old workflow to the new workflow.

* **Old workflow:**
  https://github.com/frappe/frappe_docker/blob/main/.github/workflows/build_stable.yml

* **New workflow:**
  https://github.com/frappe/frappe_docker/blob/main/.github/workflows/core-build-stable.yml

---

### 🧪 Backward compatibility

* The old workflow remains temporarily supported
* No immediate breaking changes
* Migration can be performed safely at any time

---

### 🚀 Action required

* [ ] Identify references to the old workflow in this repository
* [ ] Replace them with the new workflow
* [ ] Verify Docker publishing still works as expected

---

### 🗓️ Deprecation note

The old workflow will be removed once all repositories have been migrated.

Migration progress is tracked here:
https://github.com/frappe/frappe_docker/issues/1884

---

### 🙌 Thanks

This migration helps unify and simplify our CI/CD pipeline across repositories.

[Rocket-Quack]

@DanielRadlAMR Currently only people who have previously contributed to ERPNext can create new issues so someone who has already done so would need to do this for ERPNext.

Otherwise, I would have posted asked for help in the forum if you also can't create issues or PRs on ERPNext

[Rocket-Quack]

Possible workflow reference and how it can be used for Frappe Apps:

Docker Workflow Reference

This is a temporary reference file for issue comments and PR discussions.

It shows a commented example of migrating a Frappe app repository away from a legacy custom Docker build path to the reusable app-build-image.yml workflow from frappe_docker.

This reference is intentionally app-neutral. It can be adapted for any single-app Frappe repository by replacing the placeholder values shown below.

If an app image must include multiple additional apps, this single-app workflow is only a reference and the reusable workflow likely needs to be extended to accept multiple app definitions.

Placeholders used in this reference

Replace these placeholders when adapting the workflow:

• <app_name>
  The Bench app/module name, for example erpnext, crm, or helpdesk
• <ghcr_image_name>
  The image name in GHCR, for example erpnext, crm, or helpdesk
• <dockerhub_image>
  The image name in Docker Hub, for example frappe/erpnext
• <release_tag_example>
  A release tag used by the app repository, for example v16.15.0
• <frappe_ref_example>
  The corresponding base Frappe image line, for example version-16

What is automatic vs. what must be configured

Values that come automatically from GitHub

These values are provided automatically by GitHub Actions:

• github.event_name
  Used to detect whether the workflow was started by a release or manually.
• github.event.release.tag_name
  Used on release builds, for example <release_tag_example>.
• github.event.inputs.*
  Used only for manual workflow_dispatch runs.
• github.repository
  The current repository, for example org/repo.
• github.repository_owner
  The current owner, for example frappe.
• GITHUB_REF_NAME
  Automatically available in the runner environment and used as a fallback ref.
• GITHUB_TOKEN
  Automatically provided by GitHub for publishing to GHCR from the current repo context.

Values that must be configured in the repository settings

These are not hardcoded in the file. Maintainers must create them in the GitHub
repository settings.

Repository variable:

• DOCKERHUB_IMAGE
  Example: <dockerhub_image>
  If this variable is empty or missing, the Docker Hub publish job is skipped.

Repository secrets:

• DOCKERHUB_USERNAME
  Docker Hub username used for publishing.
• DOCKERHUB_TOKEN
  Docker Hub access token used for publishing.

Values that are hardcoded in the workflow and must be edited

These are the lines implementers change when copying this workflow into another app repository

• app_name: <app_name>
  This must match the app module name that Bench installs.
• ghcr.io/$owner_lower/<ghcr_image_name>
  This defines the GHCR target image name.
• Documentation comments or examples that still mention placeholder values
  These should be updated for the target app repository.

What implementers need to do

If this workflow is copied to another app repository the implementer needs to:

1. Replace the placeholder values with real app-specific names
2. Add the repository variable DOCKERHUB_IMAGE if Docker Hub publishing is desired
3. Add the repository secrets DOCKERHUB_USERNAME and DOCKERHUB_TOKEN if Docker Hub publishing is desired
4. Verify that the release tags map cleanly to the desired Frappe base image line
5. If the app does not derive frappe_ref cleanly from its own release tag, either:
   • adjust the derivation logic or
   • provide frappe_ref explicitly through workflow_dispatch or
   • hardcode a different mapping strategy appropriate for that app

Where each env value in the prepare job comes from

The env: block in the prepare job is only mapping GitHub context into shell variables so the bash script is easier to read.

• EVENT_NAME
  Comes from github.event_name
• RELEASE_TAG
  Comes from github.event.release.tag_name
• INPUT_APP_REF
  Comes from github.event.inputs.app_ref
• INPUT_IMAGE_TAG
  Comes from github.event.inputs.image_tag
• INPUT_FRAPPE_REF
  Comes from github.event.inputs.frappe_ref
• INPUT_PUSH
  Comes from github.event.inputs.push
• REPOSITORY
  Comes from github.repository
• REPOSITORY_OWNER
  Comes from github.repository_owner
• DOCKERHUB_IMAGE
  Comes from the repository variable vars.DOCKERHUB_IMAGE

Rule of thumb:

• github.* values are automatic
• runner environment values like GITHUB_REF_NAME are automatic
• vars.* values must be created as repository variables
• secrets.* values must be created as repository secrets
• hardcoded placeholder strings must be replaced when adapting the workflow

Important note about version derivation

This reference assumes that the app's release version can be mapped to the Frappe base image line.

Example:

• app release tag: <release_tag_example>
• derived frappe_ref: <frappe_ref_example>

That mapping is app-specific.
If an app does not follow a version scheme that maps directly to the desired Frappe base image line, then the frappe_ref derivation logic must be changed.

Commented reference workflow

# Reference workflow for migrating a Frappe app repo away from a legacy
# curl/repository_dispatch or custom docker/build-push path.
#
# This workflow uses frappe_docker only as shared build logic.
# The app repo itself owns publishing.
#
# Replace these placeholders before using it:
# - <app_name>
# - <ghcr_image_name>
# - <dockerhub_image>
#
# This reference is best suited for single-app repositories.
# Multi-app repositories may require extending the reusable workflow.

name: Build and Publish Docker Images

on:
  release:
    types: [released]
  workflow_dispatch:
    inputs:
      app_ref:
        description: Git tag or branch to build
        required: false
        type: string
      image_tag:
        description: Override the published image tag
        required: false
        type: string
      frappe_ref:
        description: Override the base Frappe image tag, for example <frappe_ref_example>
        required: false
        type: string
      push:
        description: Push the built images to registries
        required: true
        default: true
        type: boolean

permissions:
  contents: read
  packages: write

concurrency:
  group: docker-image-${{ github.event.release.tag_name || github.event.inputs.app_ref || github.ref_name }}
  cancel-in-progress: false

jobs:
  prepare:
    name: Resolve Build Metadata
    runs-on: ubuntu-latest
    outputs:
      app_ref: ${{ steps.meta.outputs.app_ref }}
      app_repo: ${{ steps.meta.outputs.app_repo }}
      frappe_ref: ${{ steps.meta.outputs.frappe_ref }}
      ghcr_image: ${{ steps.meta.outputs.ghcr_image }}
      dockerhub_image: ${{ steps.meta.outputs.dockerhub_image }}
      image_tags: ${{ steps.meta.outputs.image_tags }}
      push: ${{ steps.meta.outputs.push }}
    steps:
      - name: Resolve metadata
        id: meta
        shell: bash
        env:
          EVENT_NAME: ${{ github.event_name }}
          RELEASE_TAG: ${{ github.event.release.tag_name }}
          INPUT_APP_REF: ${{ github.event.inputs.app_ref }}
          INPUT_IMAGE_TAG: ${{ github.event.inputs.image_tag }}
          INPUT_FRAPPE_REF: ${{ github.event.inputs.frappe_ref }}
          INPUT_PUSH: ${{ github.event.inputs.push }}
          REPOSITORY: ${{ github.repository }}
          REPOSITORY_OWNER: ${{ github.repository_owner }}

          # This comes from the repository variable "DOCKERHUB_IMAGE".
          # If it is not set, Docker Hub publishing is skipped.
          DOCKERHUB_IMAGE: ${{ vars.DOCKERHUB_IMAGE }}
        run: |
          set -euo pipefail

          # Resolve the app repo ref to build.
          # Priority:
          # 1. manual workflow input
          # 2. release tag
          # 3. current ref name
          app_ref="${INPUT_APP_REF:-}"
          if [ -z "$app_ref" ]; then
            if [ "$EVENT_NAME" = "release" ] && [ -n "${RELEASE_TAG:-}" ]; then
              app_ref="$RELEASE_TAG"
            else
              app_ref="${GITHUB_REF_NAME}"
            fi
          fi

          # Release events always push.
          # Manual runs may choose push=false.
          push="${INPUT_PUSH:-true}"
          if [ "$EVENT_NAME" = "release" ]; then
            push="true"
          fi

          # Resolve the Frappe base image line.
          #
          # This logic assumes release tags can be mapped to the correct
          # Frappe base image line.
          #
          # Example:
          # <release_tag_example> -> <frappe_ref_example>
          #
          # If that assumption is not valid for a given app repo,
          # this logic must be adjusted.
          frappe_ref="${INPUT_FRAPPE_REF:-}"
          major=""
          if [ -z "$frappe_ref" ]; then
            if [[ "$app_ref" =~ ^v([0-9]+)([.].*)?$ ]]; then
              major="${BASH_REMATCH[1]}"
              frappe_ref="version-${major}"
            elif [[ "$app_ref" =~ ^version-([0-9]+)$ ]]; then
              major="${BASH_REMATCH[1]}"
              frappe_ref="$app_ref"
            elif [ "$app_ref" = "develop" ]; then
              frappe_ref="develop"
            else
              echo "::error::Unable to derive frappe_ref from app_ref '$app_ref'. Provide the workflow_dispatch input 'frappe_ref' or adjust the derivation logic."
              exit 1
            fi
          elif [[ "$frappe_ref" =~ ^version-([0-9]+)$ ]]; then
            major="${BASH_REMATCH[1]}"
          fi

          # Resolve published image tags.
          #
          # Example:
          # v16.15.0 -> v16.15.0, v16, version-16
          # develop -> develop, latest
          #
          # Adjust this logic if the app repository uses a different tagging scheme.
          declare -a tags
          if [ -n "${INPUT_IMAGE_TAG:-}" ]; then
            tags=("$INPUT_IMAGE_TAG")
          elif [[ "$app_ref" =~ ^v([0-9]+)([.].*)?$ ]]; then
            major="${BASH_REMATCH[1]}"
            tags=("$app_ref" "v${major}" "version-${major}")
          elif [ "$app_ref" = "develop" ]; then
            tags=("develop" "latest")
          else
            tags=("$app_ref")
          fi

          # Deduplicate tags and serialize them to JSON so the publish jobs
          # can consume them via a matrix.
          declare -A seen
          image_tags="["
          for tag in "${tags[@]}"; do
            if [ -z "$tag" ] || [ -n "${seen[$tag]+x}" ]; then
              continue
            fi
            seen[$tag]=1
            image_tags="${image_tags}\"${tag}\","
          done
          image_tags="${image_tags%,}]"

          if [ "$image_tags" = "]" ]; then
            echo "::error::No image tags were resolved."
            exit 1
          fi

          # Build the GHCR image name from the current repository owner.
          # Example:
          # github.repository_owner=frappe -> ghcr.io/frappe/<ghcr_image_name>
          owner_lower="$(echo "$REPOSITORY_OWNER" | tr '[:upper:]' '[:lower:]')"

          # Docker Hub image comes from the repository variable DOCKERHUB_IMAGE.
          dockerhub_image="$(echo "${DOCKERHUB_IMAGE:-}" | tr '[:upper:]' '[:lower:]')"

          {
            echo "app_ref=$app_ref"
            echo "app_repo=https://github.com/$REPOSITORY"
            echo "frappe_ref=$frappe_ref"
            echo "ghcr_image=ghcr.io/$owner_lower/<ghcr_image_name>"
            echo "dockerhub_image=$dockerhub_image"
            echo "image_tags=$image_tags"
            echo "push=$push"
          } >> "$GITHUB_OUTPUT"

  validate-dockerhub:
    name: Validate Docker Hub Configuration
    needs: prepare
    if: ${{ needs.prepare.outputs.push == 'true' && needs.prepare.outputs.dockerhub_image != '' }}
    runs-on: ubuntu-latest
    steps:
      - name: Check required secrets
        shell: bash
        env:
          DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
          DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
        run: |
          set -euo pipefail
          test -n "${DOCKERHUB_USERNAME:-}" || { echo "::error::Missing secret DOCKERHUB_USERNAME."; exit 1; }
          test -n "${DOCKERHUB_TOKEN:-}" || { echo "::error::Missing secret DOCKERHUB_TOKEN."; exit 1; }

  publish-ghcr:
    name: Publish GHCR
    needs: prepare
    strategy:
      fail-fast: false
      matrix:
        image_tag: ${{ fromJSON(needs.prepare.outputs.image_tags) }}

    # Key migration point:
    # use the reusable app image workflow from frappe_docker
    # instead of a custom build or a curl-based dispatch flow.
    uses: frappe/frappe_docker/.github/workflows/app-build-image.yml@main
    with:
      # This must match the app name that Bench installs.
      app_name: <app_name>

      # Build source: the current app repository and ref.
      app_repo: ${{ needs.prepare.outputs.app_repo }}
      app_ref: ${{ needs.prepare.outputs.app_ref }}

      # Base Frappe image line to build on.
      frappe_ref: ${{ needs.prepare.outputs.frappe_ref }}

      # Final image target in GHCR.
      image_name: ${{ needs.prepare.outputs.ghcr_image }}
      image_tag: ${{ matrix.image_tag }}

      # Manual runs may choose not to push.
      push: ${{ needs.prepare.outputs.push == 'true' }}

      registry: ghcr.io
      platforms: linux/amd64,linux/arm64

  publish-dockerhub:
    name: Publish Docker Hub
    needs:
      - prepare
      - validate-dockerhub
    if: ${{ needs.prepare.outputs.push == 'true' && needs.prepare.outputs.dockerhub_image != '' }}
    strategy:
      fail-fast: false
      matrix:
        image_tag: ${{ fromJSON(needs.prepare.outputs.image_tags) }}
    uses: frappe/frappe_docker/.github/workflows/app-build-image.yml@main
    with:
      app_name: <app_name>
      app_repo: ${{ needs.prepare.outputs.app_repo }}
      app_ref: ${{ needs.prepare.outputs.app_ref }}
      frappe_ref: ${{ needs.prepare.outputs.frappe_ref }}
      image_name: ${{ needs.prepare.outputs.dockerhub_image }}
      image_tag: ${{ matrix.image_tag }}
      push: true
      platforms: linux/amd64,linux/arm64
    secrets:
      REGISTRY_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
      REGISTRY_PASSWORD: ${{ secrets.DOCKERHUB_TOKEN }}