Skip to main content

Agent Forge Docker Build Integration

Status: 🟢 In-use Category: Integrations Date: October 30, 2025 (consolidated November 5, 2025)

Overview​

The GitHub Action workflow has been configured to use a custom Dockerfile from build/agent-forge/Dockerfile instead of relying on a Dockerfile from the cloned community-plugins repository. This enables automated building and publishing of the Backstage Agent Forge plugin as a Docker image to GitHub Container Registry (ghcr.io).

Why Use a Custom Dockerfile?​

The custom Dockerfile provides several optimizations:

  1. ARM64 Compatibility - Includes specific configurations for ARM64 architecture support
  2. Build Optimization - Better layer caching with strategic COPY commands
  3. Memory Management - Sets NODE_OPTIONS="--max-old-space-size=4096" for large builds
  4. Fallback Handling - Includes retry logic for yarn install failures
  5. Workspace-Specific - Targets the workspaces/agent-forge directory

Dockerfile Analysis​

The Dockerfile at build/agent-forge/Dockerfile:

FROM node:20-bookworm-slim

WORKDIR /app

# Install dependencies for both architectures
RUN apt-get update && apt-get install -y \
    git \
    python3 \
    make \
    g++ \
    && rm -rf /var/lib/apt/lists/*

# Copy package files first for better caching
COPY package.json yarn.lock .yarnrc.yml ./
COPY workspaces/agent-forge/package.json ./workspaces/agent-forge/

# Set yarn configuration for better ARM64 compatibility
ENV YARN_CACHE_FOLDER=/tmp/.yarn-cache
ENV NODE_OPTIONS="--max-old-space-size=4096"

# Install dependencies with ARM64 optimizations
RUN yarn install --frozen-lockfile --network-timeout 600000 || \
    (yarn config set supportedArchitectures.cpu "current" && \
     yarn install --network-timeout 600000)

# Copy the rest of the application
COPY . .

WORKDIR /app/workspaces/agent-forge

EXPOSE 3000

CMD ["yarn", "start"]

Key Features:​

  • Base Image: node:20-bookworm-slim - lightweight Debian-based Node.js 20
  • System Dependencies: Git, Python3, Make, G++ for native module compilation
  • Layer Caching: Copies package files before source code for better caching
  • Memory Allocation: 4GB max old space size for large builds
  • Network Timeout: Extended timeout for slow connections
  • Architecture Fallback: Automatically adjusts for current architecture if needed
  • Port: Exposes port 3000 for the application

How the Workflow Uses It​

Workflow Steps:​

  1. Checkout Both Repositories:

    - name: Checkout current repository
      uses: actions/checkout@v4
      with:
        path: main-repo

    - name: Checkout community-plugins repository
      uses: actions/checkout@v4
      with:
        repository: cnoe-io/community-plugins
        ref: agent-forge-upstream-docker
        path: community-plugins

  2. Copy Custom Dockerfile:

    - name: Copy custom Dockerfile
      run: |
        cp main-repo/build/agent-forge/Dockerfile community-plugins/Dockerfile
        echo "Using custom Dockerfile from build/agent-forge/"

  3. Build with Custom Dockerfile:

    - name: Build and push Docker image
      uses: docker/build-push-action@v5
      with:
        context: community-plugins
        file: community-plugins/Dockerfile
        platforms: linux/amd64,linux/arm64

Advantages of This Approach​

1. Version Control​

  • Dockerfile is tracked in your repository
  • Changes are versioned with your code
  • Easy to review and audit

2. Customization​

  • Full control over build environment
  • Can add custom dependencies
  • Can optimize for specific architectures

3. Consistency​

  • Same Dockerfile used locally and in CI/CD
  • Predictable build behavior
  • Easy to troubleshoot

4. Portability​

  • Don't depend on upstream Dockerfile existence
  • Can switch branches/repos without issues
  • Independent of community-plugins structure

Testing Locally​

The local test script (test-build-locally.sh) also uses your custom Dockerfile:

# Run the local test
./.github/test-build-locally.sh

The script will:

  1. Clone the community-plugins repository
  2. Copy your custom Dockerfile
  3. Build the project
  4. Create the Docker image
  5. Offer to run the container

Modifying the Dockerfile​

If you need to modify the Dockerfile:

  1. Edit the file:

    nano build/agent-forge/Dockerfile

  2. Test locally:

    ./.github/test-build-locally.sh

  3. Commit and push:

    git add build/agent-forge/Dockerfile
    git commit -m "Update agent-forge Dockerfile"
    git push

  4. Workflow will use the updated version automatically on next run

Common Modifications​

Add Environment Variables​

# Add after ENV NODE_OPTIONS line
ENV BACKSTAGE_HOST=0.0.0.0
ENV BACKSTAGE_PORT=3000

Add Additional Dependencies​

# Add to the apt-get install command
RUN apt-get update && apt-get install -y \
    git \
    python3 \
    make \
    g++ \
    curl \
    jq \
    && rm -rf /var/lib/apt/lists/*

Change the Working Directory​

# Change the final WORKDIR if needed
WORKDIR /app/workspaces/your-workspace

Multi-Stage Build​

# Add a build stage
FROM node:20-bookworm-slim AS builder
WORKDIR /app
# ... build steps ...

# Runtime stage
FROM node:20-bookworm-slim AS runtime
WORKDIR /app
COPY --from=builder /app/dist ./dist
# ... runtime configuration ...

Port Configuration​

The Dockerfile exposes port 3000, but you can customize this:

In Dockerfile:​

EXPOSE 7007

In Docker Run:​

docker run -p 7007:3000 ghcr.io/cnoe-io/backstage-plugin-agent-forge:latest

In Workflow (if needed):​

You can also pass build arguments:

- name: Build and push Docker image
  uses: docker/build-push-action@v5
  with:
    context: community-plugins
    file: community-plugins/Dockerfile
    build-args: |
      PORT=7007

Troubleshooting​

Build Fails on ARM64​

If builds fail on ARM64:

  1. Check the yarn install fallback is working
  2. Consider adding more memory: NODE_OPTIONS="--max-old-space-size=8192"
  3. Test locally on ARM64 machine or use Docker buildx

Build is Slow​

To speed up builds:

  1. Ensure layer caching is working (COPY package files first)
  2. Use .dockerignore to exclude unnecessary files
  3. Consider using a more powerful runner in GitHub Actions
  4. Use the build cache: cache-from: type=gha

Image is Too Large​

To reduce image size:

  1. Use multi-stage builds
  2. Remove build dependencies in final stage
  3. Use .dockerignore to exclude test files, docs, etc.
  4. Clean yarn cache: RUN yarn cache clean

Best Practices​

  1. Keep it Simple: Don't add unnecessary dependencies
  2. Use Multi-Stage: Separate build and runtime stages
  3. Cache Layers: Order commands from least to most frequently changing
  4. Security: Use official base images and keep them updated
  5. Document: Comment complex commands in the Dockerfile
  6. Test: Always test changes locally before pushing

Integration with CI/CD​

The workflow automatically:

  • ✅ Uses the latest version of your Dockerfile
  • ✅ Builds for multiple architectures (amd64, arm64)
  • ✅ Caches layers for faster subsequent builds
  • ✅ Tags images appropriately
  • ✅ Pushes to GitHub Container Registry

No additional configuration needed!

Docker Image Details​

Registry: GitHub Container Registry (ghcr.io)

Image Name: ghcr.io/cnoe-io/backstage-plugin-agent-forge

Available Tags:

  • latest - Latest stable build
  • <branch> - Branch-specific builds
  • <branch>-<sha> - Commit-specific builds
  • <version> - Semantic version tags

Pull the Image​

docker pull ghcr.io/cnoe-io/backstage-plugin-agent-forge:latest

Run the Container​

docker run -d \
  -p 7007:3000 \
  --name agent-forge-plugin \
  ghcr.io/cnoe-io/backstage-plugin-agent-forge:latest

Files Created​

GitHub Action Workflow​

  • .github/workflows/build-agent-forge-plugin.yml - Main workflow
  • .github/workflows/README.md - Workflow documentation
  • .github/WORKFLOW_SETUP.md - Setup guide
  • .github/test-build-locally.sh - Local testing script
  • .github/verify-setup.sh - Setup verification script

Next Steps​

  1. Review the Dockerfile to ensure it meets your needs
  2. Test locally using the test script
  3. Commit the workflow files
  4. Push to GitHub to trigger the workflow
  5. Monitor the build in the Actions tab

Date Added: October 30, 2025 Dockerfile Location: build/agent-forge/Dockerfile Workflow: .github/workflows/build-agent-forge-plugin.yml Related Documentation: .github/workflows/README.md, .github/WORKFLOW_SETUP.md

Agent Forge GitHub Action Workflow Setup

Overview​

A GitHub Action workflow has been created to automatically build and push the Backstage Agent Forge plugin Docker image to GitHub Container Registry.

Files Created​

1. .github/workflows/build-agent-forge-plugin.yml​

The main workflow file that orchestrates the build and push process.

Key Features:

  • ✅ Uses custom Dockerfile from build/agent-forge/Dockerfile
  • ✅ Clones https://github.com/cnoe-io/community-plugins.git (branch: agent-forge-upstream-docker)
  • ✅ Sets up Node.js 20 environment with Yarn
  • ✅ Installs dependencies and builds the project
  • ✅ Builds multi-platform Docker image (amd64 & arm64)
  • ✅ Pushes to ghcr.io/cnoe-io/backstage-plugin-agent-forge
  • ✅ Automatic tagging (latest, branch name, SHA, semantic versions)
  • ✅ Build caching for faster subsequent runs
  • ✅ Supply chain security with attestations

2. .github/workflows/README.md​

Comprehensive documentation including:

  • Workflow triggers and behavior
  • Usage instructions
  • Troubleshooting guide
  • Customization options
  • Security considerations

Docker Image Details​

Registry: GitHub Container Registry (ghcr.io)

Image Name: ghcr.io/cnoe-io/backstage-plugin-agent-forge

Available Tags:

  • latest - Latest stable build
  • <branch> - Branch-specific builds
  • <branch>-<sha> - Commit-specific builds
  • <version> - Semantic version tags

Quick Start​

Pull the Image​

docker pull ghcr.io/cnoe-io/backstage-plugin-agent-forge:latest

Run the Container​

docker run -d \
  -p 7007:7007 \
  --name agent-forge-plugin \
  ghcr.io/cnoe-io/backstage-plugin-agent-forge:latest

Triggering the Workflow​

The workflow can be triggered in three ways:

1. Automatic (Push)​

Push to main or develop branch:

git push origin main

2. Pull Request​

Open a PR targeting the main branch

3. Manual Trigger​

  1. Navigate to Actions tab in GitHub
  2. Select Build and Push Agent Forge Plugin
  3. Click Run workflow
  4. Choose branch and click Run workflow button

Prerequisites Checklist​

Before running the workflow, ensure:

  • Custom Dockerfile exists at build/agent-forge/Dockerfile (✓ already present)
  • Repository has GitHub Actions enabled
  • GITHUB_TOKEN has package write permissions (Settings → Actions → General → Workflow permissions)
  • The cnoe-io/community-plugins repository is accessible
  • Branch agent-forge-upstream-docker exists in community-plugins
  • Repository settings allow package publishing

Configuration Settings​

GitHub Repository Settings​

  1. Enable Package Publishing:

    • Go to Settings → Actions → General
    • Under "Workflow permissions", select "Read and write permissions"
    • Check "Allow GitHub Actions to create and approve pull requests"

  2. Package Visibility:

    • Go to the package settings after first build
    • Set visibility to "Public" if needed

Workflow Customization​

To customize the workflow, edit .github/workflows/build-agent-forge-plugin.yml:

# Change trigger branches
on:
  push:
    branches:
      - main
      - your-branch

# Change source repository/branch
- uses: actions/checkout@v4
  with:
    repository: cnoe-io/community-plugins
    ref: your-branch-name

# Change Docker build settings
platforms: linux/amd64,linux/arm64

Monitoring and Logs​

View Workflow Status​

  1. Go to your repository on GitHub
  2. Click the Actions tab
  3. Select the workflow run to view logs

Check Published Packages​

  1. Navigate to your repository homepage
  2. Click Packages in the right sidebar
  3. View backstage-plugin-agent-forge package

Download Artifacts​

The workflow creates attestations for supply chain security:

  • Available in the workflow run under "Artifacts"
  • Automatically pushed to the registry

Advanced Usage​

Building for Specific Platforms​

Edit the workflow to build for specific platforms:

platforms: linux/amd64  # Only amd64
# or
platforms: linux/arm64  # Only arm64

Custom Build Arguments​

Add build arguments:

- name: Build and push Docker image
  uses: docker/build-push-action@v5
  with:
    build-args: |
      NODE_ENV=production
      VERSION=${{ github.sha }}

Conditional Execution​

Run only on specific conditions:

- name: Build and push Docker image
  if: github.event_name == 'push' && github.ref == 'refs/heads/main'

Troubleshooting​

Common Issues​

Problem: Workflow fails at checkout step

Solution: Verify the repository URL and branch name are correct

Problem: Build fails with "command not found"

Solution: Check that the build commands in package.json are correct
          Update Node.js version if needed

Problem: Cannot push to ghcr.io

Solution: Enable write permissions for GITHUB_TOKEN in repository settings
          Path: Settings → Actions → General → Workflow permissions

Problem: Custom Dockerfile not found

Solution: Ensure build/agent-forge/Dockerfile exists in your repository
          The workflow copies this file to the community-plugins directory

Next Steps​

  1. Commit and push the workflow files to your repository
  2. Configure repository permissions for package publishing
  3. Trigger the workflow manually or via push
  4. Monitor the build in the Actions tab
  5. Verify the image is available at ghcr.io/cnoe-io/backstage-plugin-agent-forge:latest

Support​

For issues or questions:

Date Added: October 30, 2025 Workflow Version: 1.0 Maintainer: Platform Engineering Team Related Documentation: Agent Forge Docker Build Integration