Docker Image Publishing#
Dify publishes multi-platform Docker images for four services via a single GitHub Actions workflow: .github/workflows/build-push.yml. Images are built separately for linux/amd64 and linux/arm64, then combined into a manifest list so Docker can auto-select the right platform at pull time.
Trigger Conditions#
The workflow fires on pushes to :
main,deploy/**,build/**,hotfix/**release/e-*- Any git tag (
*)
Concurrent runs for the same ref are cancelled (cancel-in-progress: true) . The entire build and create-manifest job chain only runs on the canonical langgenius/dify repository — forks get a lightweight AMD64-only validation build instead .
Images Published#
Four images are published, each overridable via a repository variable :
| Image | Default name | Dockerfile |
|---|---|---|
| API backend | langgenius/dify-api | api/Dockerfile |
| Web frontend | langgenius/dify-web | web/Dockerfile |
| Agent backend | langgenius/dify-agent-backend | dify-agent/Dockerfile |
| Agent local sandbox | langgenius/dify-agent-local-sandbox | dify-agent-runtime/docker/Dockerfile |
Build Strategy#
Each image is built in a parallel matrix — one job per service per platform (8 build jobs total) — using Depot runners (depot-ubuntu-24.04-4) for faster layer caching .
Key build details:
- Build context: All images use
{{defaultContext}}(repo root) exceptdify-agent-local-sandbox, which scopes to{{defaultContext}}:dify-agent-runtime. - Commit SHA baked in:
COMMIT_SHAis passed as a build arg from the OCI revision label . - Push by digest: Each platform image is pushed without a tag (
push-by-digest=true) and its digest is saved as a GitHub Actions artifact (digests-<context>-<platform>) for the merge step .
Tag Strategy#
Tags are applied only at the manifest creation stage, not during the per-platform build. The docker/metadata-action generates four tag types :
| Tag | When applied |
|---|---|
latest | On git tags that do not contain - (stable releases only) |
<branch-name> | On branch pushes |
<full-commit-SHA> | Always (40-char hex, no prefix/suffix) |
<tag-name> | On git tag pushes (e.g. 1.5.0) |
Manifest Creation#
After all 8 platform builds succeed, the create-manifest job runs once per image :
- Downloads the platform digests uploaded by the build jobs.
- Calls
docker buildx imagetools createwith all generated tags and all digest references — this creates and pushes the multi-platform manifest list in one command . - Runs
docker buildx imagetools inspectto verify the manifest .
The resulting manifest references both linux/amd64 and linux/arm64 layers under each tag, so a plain docker pull langgenius/dify-api:main will automatically pull the correct platform image.
Fork Builds#
On forks, a separate fork-build-validate job runs a local linux/amd64-only build (no push) for each service to validate the Dockerfiles without requiring Docker Hub credentials .
