metabuilder/frontends/codegen/docs/DOCKER_BUILD_COMPLETE_SUMMARY.md

GitHub Actions Docker Build Fix - Complete Summary

Issue Overview

Your GitHub Actions workflow was failing during the Docker build step with:

npm error code EUNSUPPORTEDPROTOCOL
npm error Unsupported URL Type "workspace:": workspace:*

This occurred in the docker-build-action@v5 step when trying to install dependencies.

Root Cause

The project uses npm workspaces with the workspace:* protocol to reference the local @github/spark package. The Dockerfile was not properly configured to handle this monorepo structure, causing npm to fail when trying to resolve the workspace dependency.

Changes Made

1. Fixed Dockerfile (/workspaces/spark-template/Dockerfile)

Before:

COPY package*.json ./
COPY packages/spark/package.json ./packages/spark/package.json
COPY packages/spark/src ./packages/spark/src
RUN npm install

After:

# Copy workspace configuration and all package files
COPY package*.json ./

# Copy spark-tools package (the actual @github/spark implementation)
COPY packages/spark-tools/package.json ./packages/spark-tools/package.json
COPY packages/spark-tools/dist ./packages/spark-tools/dist

# Copy spark wrapper package
COPY packages/spark/package.json ./packages/spark/package.json
COPY packages/spark/src ./packages/spark/src
COPY packages/spark/tsconfig.json ./packages/spark/tsconfig.json

# Install dependencies using npm workspaces
RUN npm install --workspaces --include-workspace-root

Key improvements:

• Copies both workspace packages (spark and spark-tools)
• Includes the pre-built dist folder from spark-tools
• Uses --workspaces --include-workspace-root flags for proper resolution

2. Updated .dockerignore

Modified to preserve essential build artifacts:

# Keep the dist folder in packages/spark-tools (needed for build)
!packages/spark-tools/dist

3. Updated All GitHub Actions Workflows

Changed all npm install commands to use workspace-aware syntax:

Files updated:

• .github/workflows/ci.yml (5 jobs updated)
• .github/workflows/e2e-tests.yml
• .github/workflows/release.yml

Command used:

npm install --workspaces --legacy-peer-deps

4. Created Documentation

Added comprehensive documentation:

• DOCKER_BUILD_FIX.md - Detailed technical explanation
• docs/CI_CD_QUICK_REFERENCE.md - Quick reference for developers
• scripts/verify-docker-build.sh - Build verification script

Testing the Fix

Local Testing

1. Verify prerequisites:

   chmod +x scripts/verify-docker-build.sh
   ./scripts/verify-docker-build.sh
   

2. Build Docker image:

   docker build -t codeforge:test .
   

3. Run container:

   docker run -p 8080:80 codeforge:test
   

GitHub Actions Testing

The fix will automatically apply when you:

1. Push changes to main or develop branches
2. Create a pull request
3. Create a release tag

Monitor the workflow at: https://github.com/johndoe6345789/low-code-react-app-b/actions

Expected Workflow Behavior

Successful Build Output

You should now see:

#8 [builder 6/8] RUN npm install --workspaces --include-workspace-root
#8 1.234 npm info using npm@10.8.2
#8 1.567 npm info using node@v20.x.x
#8 15.234 added 2547 packages in 14s
#8 DONE 15.5s

Docker Image Tags

Successful builds will push images with these tags:

• ghcr.io/johndoe6345789/low-code-react-app-b:main (from main branch)
• ghcr.io/johndoe6345789/low-code-react-app-b:main-<sha> (commit-specific)
• ghcr.io/johndoe6345789/low-code-react-app-b:develop (from develop branch)

Why This Works

1. Workspace Structure: npm workspaces require the complete package structure to be present during installation
2. Pre-built Assets: The spark-tools/dist folder contains the compiled @github/spark package
3. Proper Flags: The --workspaces flag tells npm to resolve workspace dependencies correctly
4. Consistency: All environments (local, CI, Docker) now use the same installation method

Preventing Future Issues

When Adding Dependencies

npm install <package> --workspaces --legacy-peer-deps

When Modifying Workspace Packages

1. Build spark-tools: cd packages/spark-tools && npm run build
2. Commit the updated dist folder
3. Update any dependent code

When Updating CI/CD

Always include --workspaces flag with npm install commands

Rollback Plan

If issues persist, you can temporarily:

1. Replace workspace protocol in package.json:

   "@github/spark": "file:./packages/spark-tools"
   

2. Update Dockerfile to copy node_modules:

   COPY packages/spark-tools/node_modules ./packages/spark-tools/node_modules
   

However, these are workarounds and not recommended for long-term use.

Additional Notes

Build Time

• Expected Docker build time: 2-3 minutes
• Can be improved with layer caching (already configured with cache-from: type=gha)

Security

• All workflows use GitHub's GITHUB_TOKEN for registry authentication
• Container images are scanned with Trivy during CI
• npm audit runs on all dependency installs

Deployment

• Staging deployments trigger on develop branch pushes
• Production deployments trigger on main branch pushes
• Both use the Docker images built in this workflow

Related Files Changed

modified: Dockerfile
modified: .dockerignore
modified: .github/workflows/ci.yml
modified: .github/workflows/e2e-tests.yml
modified: .github/workflows/release.yml
created:  DOCKER_BUILD_FIX.md
created:  docs/CI_CD_QUICK_REFERENCE.md
created:  scripts/verify-docker-build.sh
created:  DOCKER_BUILD_COMPLETE_SUMMARY.md

Next Steps

1. ✅ Review and commit these changes
2. ✅ Push to your repository
3. ⏳ Monitor the GitHub Actions workflow
4. ⏳ Verify Docker image is published to ghcr.io
5. ⏳ Test deployed application

Support

If you encounter any issues:

1. Check the verification script output: ./scripts/verify-docker-build.sh
2. Review workflow logs in GitHub Actions
3. Consult the CI/CD Quick Reference
4. Check the detailed technical docs

---

Fix implemented: January 17, 2026
Status: Ready for testing
Estimated resolution time: < 5 minutes after push