feat: refactor Docker build workflow for better maintainability

- Extract Docker operations to reusable scripts/docker.sh
- Move Docker push from push.yml to create-release action
- Add manual Docker targets to make.deploy (docker-build, docker-push)
- Update env.example with Docker configuration variables
- Optimize CI/CD by skipping Docker for dev releases
- Add PR validation for Docker builds without pushing
- Document required GitHub secrets for ECR operations

Author: drernie

.github/actions/create-release/action.yml

@@ -1,5 +1,5 @@
 name: 'Create Release'
-description: 'Build Python package, MCPB package, and create GitHub release'
+description: 'Build Python package, MCPB package, Docker image, and create GitHub release'
 inputs:
   package-version:
     description: 'Version from git tag (e.g., 0.5.9-dev-20250904075318)'
@@ -12,6 +12,10 @@ inputs:
     description: 'Skip existing packages during upload'
     required: false
     default: 'false'
+  build-docker:
+    description: 'Build and push Docker image (true/false)'
+    required: false
+    default: 'true'
 
 outputs:
   release-url:
@@ -49,6 +53,19 @@ runs:
       shell: bash
       run: make release-zip
 
+    - name: Build and push Docker image
+      if: ${{ inputs.build-docker == 'true' }}
+      shell: bash
+      env:
+        VERSION: ${{ inputs.package-version }}
+        ECR_REGISTRY: ${{ env.ECR_REGISTRY }}
+        AWS_ACCOUNT_ID: ${{ env.AWS_ACCOUNT_ID }}
+        AWS_DEFAULT_REGION: ${{ env.AWS_DEFAULT_REGION }}
+      run: |
+        echo "🐳 Building and pushing Docker image with scripts/docker.sh"
+        chmod +x scripts/docker.sh
+        ./scripts/docker.sh push --version "$VERSION"
+
     - name: Create GitHub Release
       id: create-release
       uses: softprops/action-gh-release@v2

.github/workflows/pr.yml

@@ -6,6 +6,7 @@ on:
     branches: ['**']
   push:
     tags: ['v*-dev-*']
+
 jobs:
   test:
     runs-on: ubuntu-latest
@@ -41,6 +42,13 @@ jobs:
         QUILT_TEST_PACKAGE: ${{ secrets.QUILT_TEST_PACKAGE }}
         QUILT_TEST_ENTRY: ${{ secrets.QUILT_TEST_ENTRY }}
 
+    - name: Test Docker build (no push)
+      if: github.event_name == 'pull_request'
+      run: |
+        echo "🐳 Testing Docker build for PR (no push)..."
+        chmod +x scripts/docker.sh
+        ./scripts/docker.sh build
+
     - name: Debug GitHub context for dev-release
       run: |
         echo "=== GitHub Context Debug ==="
@@ -75,6 +83,7 @@ jobs:
       with:
         python-version: '3.11'
         include-nodejs: 'true'
+
     - name: Debug dev-release context
       run: |
         echo "=== Dev-Release Context Debug ==="
@@ -94,9 +103,11 @@ jobs:
         TAG_VERSION=${GITHUB_REF#refs/tags/v}
         echo "tag_version=$TAG_VERSION" >> $GITHUB_OUTPUT
         echo "Dev Tag Version: $TAG_VERSION"
+
     - name: Create dev release
       uses: ./.github/actions/create-release
       with:
         package-version: ${{ steps.version.outputs.tag_version }}
         pypi-repository-url: https://test.pypi.org/legacy/
-        skip-existing: true
+        skip-existing: true
+        build-docker: 'false'  # Skip Docker for development releases

.github/workflows/push.yml

@@ -77,12 +77,6 @@ jobs:
         echo "tag_version=$TAG_VERSION" >> $GITHUB_OUTPUT
         echo "Production Tag Version: $TAG_VERSION"
 
-    - name: Create production release
-      uses: ./.github/actions/create-release
-      with:
-        package-version: ${{ steps.version.outputs.tag_version }}
-        # pypi-repository-url defaults to '' for PyPI
-
     - name: Configure AWS credentials for ECR
       uses: aws-actions/configure-aws-credentials@v4
       with:
@@ -93,36 +87,15 @@ jobs:
     - name: Login to Amazon ECR
       uses: aws-actions/amazon-ecr-login@v2
 
-    - name: Build and publish Docker image
+    - name: Create production release
+      uses: ./.github/actions/create-release
+      with:
+        package-version: ${{ steps.version.outputs.tag_version }}
+        build-docker: 'true'
+        # pypi-repository-url defaults to '' for PyPI
       env:
-        VERSION: ${{ steps.version.outputs.tag_version }}
-        ECR_REGISTRY: ${{ secrets.ECR_REGISTRY }}
-        AWS_ACCOUNT_ID: ${{ secrets.AWS_ACCOUNT_ID }}
-        AWS_DEFAULT_REGION: ${{ secrets.AWS_DEFAULT_REGION || 'us-east-1' }}
-      shell: bash
-      run: |
-        set -euo pipefail
-
-        registry="$ECR_REGISTRY"
-        if [ -z "$registry" ]; then
-          if [ -z "$AWS_ACCOUNT_ID" ]; then
-            echo "ECR registry not configured" >&2
-            exit 1
-          fi
-          registry="$AWS_ACCOUNT_ID.dkr.ecr.${AWS_DEFAULT_REGION:-us-east-1}.amazonaws.com"
-        fi
-
-        image_tags=$(uv run python scripts/docker_image.py --registry "$registry" --version "$VERSION")
-
-        first_tag=$(echo "$image_tags" | head -n 1)
-        docker build --file Dockerfile --tag "$first_tag" .
-
-        echo "$image_tags" | tail -n +2 | while read -r tag; do
-          [ -z "$tag" ] && continue
-          docker tag "$first_tag" "$tag"
-        done
-
-        echo "$image_tags" | while read -r tag; do
-          [ -z "$tag" ] && continue
-          docker push "$tag"
-        done
+        # Docker registry configuration - these secrets are optional
+        # If ECR_REGISTRY is not set, falls back to constructing from AWS_ACCOUNT_ID
+        ECR_REGISTRY: ${{ secrets.ECR_REGISTRY || '' }}
+        AWS_ACCOUNT_ID: ${{ secrets.AWS_ACCOUNT_ID || '' }}
+        AWS_DEFAULT_REGION: ${{ secrets.AWS_DEFAULT_REGION || 'us-east-1' }}

AGENTS.md

@@ -312,6 +312,12 @@ For this repository's specific commands and permissions, see this CLAUDE.md file
 - `make release` - Create and push release tag
 - `make release-dev` - Create and push development tag
 
+**Docker Operations (make.deploy):**
+
+- `make docker-build` - Build Docker image locally
+- `make docker-push` - Build and push Docker image to ECR (requires VERSION)
+- `make docker-push-dev` - Build and push development Docker image
+
 **Coordination & Utilities:**
 
 - `make help` - Show all available targets organized by category
@@ -421,9 +427,53 @@ The following permissions are granted for this repository:
 - When running the integration test locally, Docker must be available and the build takes ~45s on warm caches. Expect the test to leave behind pulled base images but no running containers.
 - Claude Desktop still requires stdio transports; use a FastMCP proxy (`FastMCP.as_proxy(...).run(transport='stdio')`) and pass `--project /path/to/quilt-mcp-server` to `uv run` so `fastmcp` resolves correctly.
 
+### Docker Build and Deployment Refactoring (2025-09-22)
+
+**Script-based Docker Operations:**
+
+- All Docker operations extracted to `scripts/docker.sh` for reusability and local testing
+- Script supports both `build` (local testing) and `push` (ECR deployment) commands
+- Integrates with existing `scripts/docker_image.py` for consistent tag generation
+- Supports dry-run mode via `--dry-run` for testing workflow changes
+
+**GitHub Actions Integration:**
+
+- Production releases (tags matching `v*` but not `v*-dev-*`) build and push Docker images automatically
+- Development releases skip Docker builds to reduce CI/CD time and resource usage
+- PR builds test Docker image building without pushing (build-only validation)
+- Docker operations moved from `push.yml` workflow into `create-release` action for better encapsulation
+
+**Makefile Integration:**
+
+- `make docker-build` - Build locally for development and testing
+- `make docker-push` - Build and push to ECR (requires VERSION environment variable)
+- `make docker-push-dev` - Build and push with timestamp-based development tags
+- All Docker targets include proper dependency checking for Docker daemon and required tools
+
+**GitHub Secrets Configuration:**
+
+Required secrets for Docker operations:
+- `ECR_REGISTRY` - ECR registry URL (preferred)
+- `AWS_ACCOUNT_ID` - AWS account ID (fallback for registry construction)
+- `AWS_DEFAULT_REGION` - AWS region (defaults to us-east-1)
+- Existing AWS credentials (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`) for ECR login
+
+**Environment Variable Support:**
+
+- `scripts/docker.sh` respects all environment variables from `env.example`
+- `ECR_REGISTRY`, `AWS_ACCOUNT_ID`, `AWS_DEFAULT_REGION` for registry configuration
+- `VERSION` for overriding image version tags
+- `DOCKER_IMAGE_NAME` for custom image naming (defaults to `quilt-mcp-server`)
+
 ## important-instruction-reminders
 
 Do what has been asked; nothing more, nothing less.
 NEVER create files unless they're absolutely necessary for achieving your goal.
 ALWAYS prefer editing an existing file to creating a new one.
 NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
+
+# important-instruction-reminders
+Do what has been asked; nothing more, nothing less.
+NEVER create files unless they're absolutely necessary for achieving your goal.
+ALWAYS prefer editing an existing file to creating a new one.
+NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.

Makefile

@@ -1,5 +1,5 @@
 # Quilt MCP Server - Consolidated Build System
-# 
+#
 # This Makefile consolidates all build workflows into organized includes.
 # Development targets are in make.dev, production targets are in make.deploy.
 
@@ -38,6 +38,11 @@ help:
 	@echo "  make release          - Create and push release tag"
 	@echo "  make release-dev      - Create and push development tag"
 	@echo ""
+	@echo "🐳 Docker Operations (make.deploy):"
+	@echo "  make docker-build     - Build Docker image locally"
+	@echo "  make docker-push      - Build and push Docker image to ECR (requires VERSION)"
+	@echo "  make docker-push-dev  - Build and push development Docker image"
+	@echo ""
 	@echo "🔢 Version Management:"
 	@echo "  make bump-patch       - Bump patch version (1.2.3 → 1.2.4)"
 	@echo "  make bump-minor       - Bump minor version (1.2.3 → 1.3.0)"
@@ -130,4 +135,4 @@ release-major: bump-major
 	git commit -m "bump: major version to $$VERSION"; \
 	echo "✅ Committed version bump to $$VERSION"
 	@echo "🏷️  Creating release tag..."
-	@scripts/release.sh release
+	@scripts/release.sh release

env.example

@@ -23,6 +23,14 @@ FASTMCP_TRANSPORT=stdio
 # ngrok Configuration for remote tunneling (optional)
 NGROK_DOMAIN=my-free-domain.ngrok-free.app
 
+# Docker Configuration
+# ECR registry URL (required for Docker push operations)
+# Format: {account_id}.dkr.ecr.{region}.amazonaws.com
+ECR_REGISTRY=123456789.dkr.ecr.us-east-1.amazonaws.com
+
+# Docker image configuration (optional)
+DOCKER_IMAGE_NAME=quilt-mcp-server
+
 # Python packaging (uv)
 # Required for publishing: set either UV_PUBLISH_TOKEN or both UV_PUBLISH_USERNAME/UV_PUBLISH_PASSWORD.
 # Leave unset to build locally without publishing.
@@ -34,4 +42,4 @@ UV_PUBLISH_PASSWORD=testpypi-password
 PYPI_PUBLISH_URL=https://test.pypi.org/legacy/
 
 # Optional: Override dist output directory (defaults to dist/)
-DIST_DIR=dist
+DIST_DIR=dist

make.deploy

@@ -22,7 +22,7 @@ RELEASE_ZIP := $(PACKAGE_ID)-release.zip
 ASSET_FILES := $(wildcard $(ASSETS_DIR)/*)
 APP_FILES := $(shell find $(APP_DIR)/quilt_mcp -name "*.py" 2>/dev/null || true)
 
-.PHONY: deploy-build mcpb mcpb-validate python-dist python-publish release-zip deploy-clean check-tools
+.PHONY: deploy-build mcpb mcpb-validate python-dist python-publish release-zip deploy-clean check-tools docker-build docker-push docker-push-dev check-docker-tools
 
 # Check for required tools
 check-tools:
@@ -31,6 +31,12 @@ check-tools:
 	@command -v mcpb >/dev/null 2>&1 || { echo "❌ mcpb not found - run: npm install -g @anthropic-ai/mcpb"; exit 1; }
 	@echo "✅ All required tools found"
 
+# Check for Docker-specific tools
+check-docker-tools:
+	@command -v docker >/dev/null 2>&1 || { echo "❌ Docker not found - install Docker"; exit 1; }
+	@docker info >/dev/null 2>&1 || { echo "❌ Docker daemon not running or not accessible"; exit 1; }
+	@echo "✅ Docker tools available"
+
 # Build Environment Preparation
 deploy-build: check-tools
 	@echo "Preparing production build environment..."
@@ -120,6 +126,28 @@ $(RELEASE_ZIP): mcpb-validate $(ASSETS_DIR)/README.md $(ASSETS_DIR)/check-mcpb.s
 release-zip: $(RELEASE_ZIP)
 	@echo "✅ Release bundle $(RELEASE_ZIP) ready for distribution"
 
+# Docker Operations
+docker-build: check-docker-tools
+	@echo "🐳 Building Docker image locally..."
+	@./scripts/docker.sh build
+	@echo "✅ Docker build completed"
+
+docker-push: check-docker-tools
+	@echo "🐳 Building and pushing Docker image..."
+	@if [ -z "$(VERSION)" ]; then \
+		echo "❌ VERSION is required for docker-push. Use: make docker-push VERSION=1.2.3"; \
+		exit 1; \
+	fi
+	@VERSION=$(PACKAGE_VERSION) ./scripts/docker.sh push --version $(PACKAGE_VERSION)
+	@echo "✅ Docker push completed"
+
+docker-push-dev: check-docker-tools
+	@echo "🐳 Building and pushing development Docker image..."
+	@DEV_VERSION="$(PACKAGE_VERSION)-dev-$(shell date +%Y%m%d%H%M%S)"
+	@echo "Using development version: $$DEV_VERSION"
+	@VERSION=$$DEV_VERSION ./scripts/docker.sh push --version $$DEV_VERSION --no-latest
+	@echo "✅ Development Docker push completed"
+
 # Release Tagging Targets
 release-tag:
 	@echo "Creating release tag..."
@@ -144,4 +172,4 @@ deploy-clean:
 	@echo "Cleaning build artifacts..."
 	@rm -rf $(BUILD_DIR) $(DIST_DIR)
 	@rm -f *.mcpb  # Clean MCPB packages from root
-	@echo "✅ Deploy cleanup completed"
+	@echo "✅ Deploy cleanup completed"