mirror of
https://github.com/frappe/frappe_docker.git
synced 2026-06-17 13:55:08 +00:00
docs(ci): document current image workflow setup
This commit is contained in:
RocketQuack
parent
01af0df21d
commit
fec3af20cd
1 changed files with 312 additions and 0 deletions
312
docs/08-reference/06-github-actions-image-workflows.md
Normal file
312
docs/08-reference/06-github-actions-image-workflows.md
Normal file
|
|
@ -0,0 +1,312 @@
|
|||
---
|
||||
title: GitHub Actions Image Workflows
|
||||
---
|
||||
|
||||
This document describes the current workflow setup for shared core images and reusable downstream app images.
|
||||
|
||||
# Workflow roles
|
||||
|
||||
The current workflow layout is:
|
||||
|
||||
- `.github/workflows/core-build-develop.yml`
|
||||
- `.github/workflows/core-build-stable.yml`
|
||||
- `.github/workflows/core-build-test-images.yml`
|
||||
- `.github/workflows/core-publish-images.yml`
|
||||
- `.github/workflows/app-build-image.yml`
|
||||
|
||||
`core-build-develop.yml` and `core-build-stable.yml` are orchestration workflows.
|
||||
They decide when the core image pipeline runs.
|
||||
|
||||
`core-build-test-images.yml` is the reusable workflow that:
|
||||
|
||||
- resolves the image versions for the requested release line
|
||||
- builds the shared core images into a local registry
|
||||
- runs the test suite against those images
|
||||
|
||||
`core-publish-images.yml` is the reusable workflow that:
|
||||
|
||||
- publishes the tested images to Docker Hub
|
||||
- publishes `base` and `build` to GHCR
|
||||
|
||||
`app-build-image.yml` is the reusable workflow that downstream repositories call to:
|
||||
|
||||
- create an `apps.json` file from the caller's app repository and ref
|
||||
- build `images/layered/Containerfile`
|
||||
- consume existing `base` and `build` images
|
||||
- install the requested app into the final image
|
||||
- optionally push the final app image to the caller's registry
|
||||
|
||||
# Current flow
|
||||
|
||||
The current structure is:
|
||||
|
||||
```text
|
||||
core orchestration
|
||||
-> core build and test
|
||||
-> core publish
|
||||
|
||||
downstream app workflow
|
||||
-> consume published base and build
|
||||
-> install app
|
||||
-> publish final app image
|
||||
```
|
||||
|
||||
Current Mermaid overview:
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
subgraph Core["Core image flow"]
|
||||
A[core-build-develop.yml or core-build-stable.yml]
|
||||
B[core-build-test-images.yml]
|
||||
C[Resolve versions]
|
||||
D[Build local test images]
|
||||
E[Run pytest]
|
||||
F[core-publish-images.yml]
|
||||
G[Push Docker Hub: erpnext, base, build]
|
||||
H[Push GHCR: base, build]
|
||||
|
||||
A --> B
|
||||
B --> C
|
||||
C --> D
|
||||
D --> E
|
||||
E --> F
|
||||
F --> G
|
||||
F --> H
|
||||
end
|
||||
|
||||
subgraph App["Downstream app flow"]
|
||||
I[Downstream repo workflow]
|
||||
J[app-build-image.yml]
|
||||
K[Create apps.json]
|
||||
L[Build images/layered/Containerfile]
|
||||
M[Install app]
|
||||
N[Push final app image]
|
||||
|
||||
I --> J
|
||||
J --> K
|
||||
K --> L
|
||||
L --> M
|
||||
M --> N
|
||||
end
|
||||
|
||||
G --> J
|
||||
H --> J
|
||||
```
|
||||
|
||||
More concretely:
|
||||
|
||||
```text
|
||||
core-build-test-images.yml
|
||||
-> resolves frappe and erpnext tags
|
||||
-> builds images into a local CI registry
|
||||
-> runs tests
|
||||
|
||||
core-publish-images.yml
|
||||
-> pushes Docker Hub: erpnext, base, build
|
||||
-> pushes GHCR: base, build
|
||||
|
||||
app-build-image.yml
|
||||
-> pulls:
|
||||
- <prefix>/base:<frappe_ref>
|
||||
- <prefix>/build:<frappe_ref>
|
||||
-> installs app from app_repo + app_ref
|
||||
-> pushes final image_name:image_tag
|
||||
```
|
||||
|
||||
# Naming convention
|
||||
|
||||
GitHub Actions requires workflow files to stay directly inside `.github/workflows`.
|
||||
Subdirectories are not supported for workflow files, so structure should come from file names and `name:` values.
|
||||
|
||||
Recommended file naming convention:
|
||||
|
||||
```text
|
||||
<area>-<action>-<subject>.yml
|
||||
```
|
||||
|
||||
Current examples:
|
||||
|
||||
- `core-build-bench.yml`
|
||||
- `core-build-develop.yml`
|
||||
- `core-build-stable.yml`
|
||||
- `core-build-test-images.yml`
|
||||
- `core-publish-images.yml`
|
||||
- `app-build-image.yml`
|
||||
- `docs-publish-site.yml`
|
||||
|
||||
Recommended visible workflow names:
|
||||
|
||||
- `Core / Build Bench`
|
||||
- `Core / Build Develop`
|
||||
- `Core / Build Stable`
|
||||
- `Core / Build and Test Images`
|
||||
- `Core / Publish Images`
|
||||
- `App / Build Image`
|
||||
- `Docs / Publish Site`
|
||||
|
||||
# Style rules
|
||||
|
||||
To keep workflows predictable, use one convention per category instead of mixing styles.
|
||||
|
||||
Workflow file names should use kebab-case:
|
||||
|
||||
```text
|
||||
core-build-test-images.yml
|
||||
app-build-image.yml
|
||||
```
|
||||
|
||||
Workflow display names should use short title-style groups:
|
||||
|
||||
```text
|
||||
Core / Build and Test Images
|
||||
App / Build Image
|
||||
```
|
||||
|
||||
Workflow inputs should use snake_case:
|
||||
|
||||
```yaml
|
||||
app_name:
|
||||
frappe_ref:
|
||||
image_name:
|
||||
```
|
||||
|
||||
Environment variables should use upper snake case:
|
||||
|
||||
```text
|
||||
FRAPPE_IMAGE_PREFIX
|
||||
PYTHON_VERSION
|
||||
NODE_VERSION
|
||||
```
|
||||
|
||||
The recommended rule set is:
|
||||
|
||||
- workflow file names: kebab-case
|
||||
- workflow `name:` values: grouped title case
|
||||
- workflow inputs: snake_case
|
||||
- job ids and step ids: snake_case where practical
|
||||
- environment variables: UPPER_SNAKE_CASE
|
||||
|
||||
This means `-` is preferred for file names, while `_` remains appropriate for YAML keys, inputs, and environment variables.
|
||||
|
||||
# Important inputs in `app-build-image.yml`
|
||||
|
||||
The reusable app workflow is controlled mainly by these inputs:
|
||||
|
||||
- `app_name`
|
||||
The application directory name, for example `crm`
|
||||
- `app_repo`
|
||||
The Git repository to install, for example `frappe/crm`
|
||||
- `app_ref`
|
||||
The branch or tag to install, for example `develop`
|
||||
- `frappe_ref`
|
||||
The tag of the existing `base` and `build` images, for example `version-16`
|
||||
- `frappe_image_prefix`
|
||||
Where the shared `base` and `build` images come from, for example `frappe` or `ghcr.io/frappe`
|
||||
- `image_name`
|
||||
The final target image name, for example `ghcr.io/acme/crm`
|
||||
- `image_tag`
|
||||
The final target image tag, for example `develop`
|
||||
- `registry`
|
||||
The registry for the final push, for example `ghcr.io` or `docker.io`
|
||||
|
||||
The key distinction is:
|
||||
|
||||
```text
|
||||
frappe_image_prefix = source of shared base/build images
|
||||
image_name = destination of the final app image
|
||||
```
|
||||
|
||||
# Example: caller repository publishes to GHCR
|
||||
|
||||
This example assumes:
|
||||
|
||||
- shared base images exist in `ghcr.io/frappe/base` and `ghcr.io/frappe/build`
|
||||
- the caller repository wants to publish its own app image to `ghcr.io/acme/crm`
|
||||
|
||||
```yaml
|
||||
name: App / Build CRM Image
|
||||
|
||||
on:
|
||||
workflow_dispatch:
|
||||
push:
|
||||
branches:
|
||||
- develop
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
packages: write
|
||||
|
||||
jobs:
|
||||
build-image:
|
||||
uses: frappe/frappe_docker/.github/workflows/app-build-image.yml@main
|
||||
with:
|
||||
app_name: crm
|
||||
app_repo: acme/crm
|
||||
app_ref: develop
|
||||
frappe_ref: version-16
|
||||
frappe_image_prefix: ghcr.io/frappe
|
||||
image_name: ghcr.io/acme/crm
|
||||
image_tag: develop
|
||||
registry: ghcr.io
|
||||
push: true
|
||||
platforms: linux/amd64
|
||||
```
|
||||
|
||||
What happens:
|
||||
|
||||
```text
|
||||
1. app-build-image.yml is called
|
||||
2. apps.json is generated from acme/crm + develop
|
||||
3. the workflow builds images/layered/Containerfile
|
||||
4. layered uses:
|
||||
- ghcr.io/frappe/build:version-16
|
||||
- ghcr.io/frappe/base:version-16
|
||||
5. CRM is installed
|
||||
6. the final image is pushed to ghcr.io/acme/crm:develop
|
||||
```
|
||||
|
||||
For GHCR, the caller workflow should grant:
|
||||
|
||||
- `permissions: packages: write`
|
||||
|
||||
The reusable workflow then logs in with the workflow token.
|
||||
|
||||
# Example: caller repository publishes to Docker Hub
|
||||
|
||||
This example assumes:
|
||||
|
||||
- shared base images come from Docker Hub under `frappe`
|
||||
- the caller repository wants to publish its app image to Docker Hub as `acme/crm`
|
||||
|
||||
```yaml
|
||||
name: App / Build CRM Image
|
||||
|
||||
on:
|
||||
workflow_dispatch:
|
||||
push:
|
||||
branches:
|
||||
- develop
|
||||
|
||||
jobs:
|
||||
build-image:
|
||||
uses: frappe/frappe_docker/.github/workflows/app-build-image.yml@main
|
||||
with:
|
||||
app_name: crm
|
||||
app_repo: acme/crm
|
||||
app_ref: develop
|
||||
frappe_ref: version-16
|
||||
frappe_image_prefix: frappe
|
||||
image_name: acme/crm
|
||||
image_tag: develop
|
||||
registry: docker.io
|
||||
push: true
|
||||
platforms: linux/amd64
|
||||
secrets:
|
||||
REGISTRY_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
|
||||
REGISTRY_PASSWORD: ${{ secrets.DOCKERHUB_TOKEN }}
|
||||
```
|
||||
|
||||
In this case:
|
||||
|
||||
- shared images are pulled from `frappe/base:version-16` and `frappe/build:version-16`
|
||||
- the final image is pushed to Docker Hub as `acme/crm:develop`
|
||||
Loading…
Reference in a new issue