name: Build and Publish MCP Docs Docker Image
# ============================================================================
# This workflow builds and publishes the MCP Docs Docker image to Google Artifact Registry,
# and redeploys the service using Terraform via ops/run_terraform.sh.
#
# Deephaven MCP Docs: Docker Build & Deploy Workflow
#
# This GitHub Actions workflow builds and deploys the MCP Docs server Docker image to Google Cloud.
#
# ---
#
# Directory Structure:
# - Dockerfile and Compose file for the docs server: ops/docker/mcp-docs/
# * [`ops/docker/mcp-docs/Dockerfile`](../../ops/docker/mcp-docs/Dockerfile)
# * [`ops/docker/mcp-docs/docker-compose.yml`](../../ops/docker/mcp-docs/docker-compose.yml)
# - Terraform and supporting scripts: ops/ (e.g., ops/run_terraform.sh, ops/terraform/)
# - .env is expected at the project root for local runs; in CI/CD, INKEEP_API_KEY is set via a GitHub secret.
#
# Build Context:
# - The Docker build context is the repo root (.), so all code/assets are accessible to the Dockerfile.
# - The workflow uses ops/docker/mcp-docs/Dockerfile for building the image.
#
# Service Account & Secrets Requirements:
# - A Google Cloud service account with the following roles (principle of least privilege):
# * Artifact Registry Writer - Push Docker images
# * Artifact Registry Reader - Pull Docker images
# * Cloud Run Admin - Deploy/update Cloud Run services
# * Service Account User - Use service account for deployments
# * Storage Admin - Manage GCS buckets for state/artifacts
# - Service account key JSON must be stored as the GitHub secret: GH_ACTION_GCLOUD_JSON
# - INKEEP_API_KEY must be stored as the GitHub secret: INKEEP_API_KEY
#
# ---
#
# Service Account Setup:
#
# 1. Go to https://console.cloud.google.com/iam-admin/serviceaccounts
# 2. Create a new service account or select an existing one (e.g., deephaven-mcp-github-actions)
# 3. Click the three dots > Manage permissions
# 4. Go to "Keys" > "Add key" > "Create new key" > JSON
# 5. Download the JSON key file
# **This file is highly sensitive. After uploading it as a GitHub secret, delete it from your local machine to prevent accidental exposure.**
# 6. Add the JSON file as the GitHub secret: GH_ACTION_GCLOUD_JSON
# 7. Go to https://console.cloud.google.com/iam-admin/iam
# 8. Click "Grant access", add the service account as "New principals", and assign the roles listed above.
#
# Note: If you rotate the key, update the GitHub secret immediately. Remove unused or old keys in the Google Cloud Console.
#
# ---
#
# Security Warning:
# - Never commit the service account key JSON to version control.
# - Store the key securely and rotate it regularly.
# - If you rotate the key, update the GitHub secret `GH_ACTION_GCLOUD_JSON` immediately.
# - Remove unused keys in the Google Cloud Console.
#
# References:
# - Terraform module: ops/terraform/service-account/README.md
# - GCP IAM docs: https://cloud.google.com/iam/docs/creating-managing-service-accounts
# - GitHub Actions secrets: https://docs.github.com/en/actions/security-guides/encrypted-secrets
#
# Triggers:
# - On push or PR to main, or manual dispatch.
#
# IMAGE LOCATION:
# Artifact Registry: us-central1-docker.pkg.dev/deephaven-oss/deephaven-mcp/mcp-docs
# Tags: 'prod' for main branch, 'dev' otherwise
# ============================================================================
on:
push:
branches:
- main
pull_request:
branches:
- main
workflow_dispatch:
env:
# The Artifact Registry repository path (update as needed)
DOCKER_REPO: us-central1-docker.pkg.dev/deephaven-oss/deephaven-mcp
jobs:
mcp-docs:
runs-on: ubuntu-latest
steps:
# Checkout the repository code
- name: Checkout repository
uses: actions/checkout@v2
# Set up Docker Buildx for advanced build capabilities
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v1
# Authenticate to Google Cloud using the service account key from secrets
- name: Authorize GCloud Credentials
uses: google-github-actions/auth@v2
with:
credentials_json: ${{ secrets.GH_ACTION_GCLOUD_JSON }}
# Configure Docker to use gcloud as a credential helper for Artifact Registry
# Configure Docker to use gcloud as a credential helper for Artifact Registry
- name: Configure Docker to use gcloud as a credential helper
run: |
gcloud auth configure-docker
gcloud auth configure-docker us-central1-docker.pkg.dev
# Set the Docker image tag based on branch
# - 'prod' for main branch
# - 'dev' for all other branches/PRs
- name: Set Docker image tag
id: set_image_tag
run: |
if [ "${{ github.ref }}" == "refs/heads/main" ]; then
echo "tag=prod" >> $GITHUB_OUTPUT
else
echo "tag=dev" >> $GITHUB_OUTPUT
fi
# Build and push the Docker image to Artifact Registry
# Uses the Dockerfile in mcp-docs and tags as prod/dev accordingly
- name: Build and push Docker image
uses: docker/build-push-action@v2
with:
context: .
file: ops/docker/mcp-docs/Dockerfile
push: true
tags: ${{ env.DOCKER_REPO }}/mcp-docs:${{ steps.set_image_tag.outputs.tag }}
# ---------------------------------------------------------------------------
# Redeploy job: triggers after image build/push, runs Terraform deployment
# ---------------------------------------------------------------------------
redeploy:
runs-on: ubuntu-latest
needs: [mcp-docs]
steps:
# Checkout the repository (required for deployment scripts)
- name: Checkout repository
uses: actions/checkout@v2
# Set WORKSPACE environment variable based on branch
# - 'prod' for main branch
# - 'dev' for all other branches/PRs
- name: Set Workspace
id: set_workspace
run: |
if [ "${{ github.ref }}" == "refs/heads/main" ]; then
echo "ws=prod" >> $GITHUB_OUTPUT
else
echo "ws=dev" >> $GITHUB_OUTPUT
fi
# Authenticate to Google Cloud for deployment permissions
- name: Authorize GCloud Credentials
uses: google-github-actions/auth@v2
with:
credentials_json: ${{ secrets.GH_ACTION_GCLOUD_JSON }}
# Set up the Google Cloud SDK for Terraform/Cloud Run commands
- name: Set up Cloud SDK
uses: google-github-actions/setup-gcloud@v2.1.4
# Run the deployment script to redeploy the latest image
# Expects run_terraform.sh to handle the actual redeploy logic
- name: Create .env file for deployment
run: |
echo "INKEEP_API_KEY=${{ secrets.INKEEP_API_KEY }}" > .env
- name: Deploy to Cloud Run
run: |
./ops/run_terraform.sh ${{ steps.set_workspace.outputs.ws }} redeploy-image
