## [2.0.0] - 2025-12-09

### Added
- Prebuilt runner image with `aio`
- no CLI installation steps in the workflow.

Author: o-blinnikov

.github/workflows/deploy.yaml

@@ -13,12 +13,28 @@ jobs:
   deploy:
     name: Deploy API Mesh
     runs-on: ${{ matrix.os }}
+    container:
+      image: ghcr.io/comwrap/aio-mesh-runner:latest
+      env:
+        HOME: /root
     strategy:
       max-parallel: 1
       matrix:
         node-version: ["20"]
         os: [ubuntu-latest]
     steps:
+      - name: Ensure AIO CLI available
+        run: |
+          which aio || { echo "aio missing"; exit 1; }
+          aio -h
+      - name: Install API Mesh plugin
+        run: aio plugins:install @adobe/aio-cli-plugin-api-mesh
+      - name: Debug AIO plugins
+        run: |
+          echo "HOME=$HOME"
+          which aio
+          aio -V
+          aio plugins
       - name: Checkout
         uses: actions/checkout@v4
       - name: Use Node.js ${{ matrix.node-version }}
@@ -90,6 +106,7 @@ jobs:
             echo "Warning: MESH_SECRETS not provided; secrets.yaml will not be generated" >&2
           fi
       - name: Materialize mesh secrets file
+        shell: bash
         if: ${{ env.MESH_SECRETS != '' }}
         run: |
           set -euo pipefail
@@ -101,13 +118,6 @@ jobs:
           set -euo pipefail
           printf '%s\n' "$AIO_ENV_FILE" > .env
           chmod 600 .env
-      - name: Setup CLI
-        uses: adobe/aio-cli-setup-action@1.3.0
-        with:
-          os: ${{ matrix.os }}
-          version: 11.x.x
-      - name: api-mesh-plugin install
-        run: aio plugins:install @adobe/aio-cli-plugin-api-mesh
       - name: Auth
         uses: adobe/aio-apps-action@4.0.0
         with:
@@ -142,6 +152,7 @@ jobs:
         continue-on-error: true
         run: echo "Get Mesh Output - ${{ steps.get_mesh.outputs.mesh_output }}"
       - name: Compute Mesh Credential Flags
+        shell: bash
         id: mesh_args
         run: |
           set -euo pipefail
@@ -160,6 +171,7 @@ jobs:
         if: ${{ !contains(steps.get_mesh.outputs.mesh_output, 'No mesh found') }}
         run: aio api-mesh:update ${{ steps.mesh_args.outputs.args }}
       - name: Wait for Mesh Provisioning
+        shell: bash
         run: |
           set -euo pipefail
           max_attempts=60
@@ -175,6 +187,9 @@ jobs:
             elif echo "$status_output" | grep -Eq "Mesh is currently building|Your mesh is being provisioned.|Currently provisioning your mesh|Wait a few minutes and try again.|Unable to get mesh status"; then
               echo "Mesh is currently building. Waiting 10 seconds before next check."
               sleep 10
+            elif echo "$status_output" | grep -F "is not a aio command" >/dev/null; then
+              echo "API Mesh plugin not available. Failing explicitly."
+              exit 1
             else
               echo "Unexpected status output. Treating as failure."
               exit 1
@@ -193,7 +208,7 @@ jobs:
         run: aio api-mesh:status
 
   tests:
-      name: Execute Tests
-      needs: [deploy]
-      # Use the path to the reusable workflow file
-      uses: ./.github/workflows/tests.yaml
+    name: Execute Tests
+    needs: [deploy]
+    # Use the path to the reusable workflow file
+    uses: ./.github/workflows/tests.yaml

.github/workflows/images/aio-mesh-runner/Dockerfile

@@ -0,0 +1,12 @@
+FROM node:20-bullseye-slim
+
+RUN apt-get update && apt-get install -y \
+    git \
+    ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN npm install -g @adobe/aio-cli && \
+    npm cache clean --force && \
+    rm -rf /root/.npm /tmp/*
+
+WORKDIR /workspace

CHANGELOG.md

@@ -20,3 +20,8 @@ All notable changes to this project will be documented in this file. The format
 ## [1.0.0] - 2025-11-19
 ### Added
 - Initial Adobe API Mesh CI/CD template with a GitHub Actions workflow for staging/production deployments, README-based setup guidance, and secret validation.
+
+## [2.0.0] - 2025-12-09
+### Added
+- Prebuilt runner image with `aio`
+- no CLI installation steps in the workflow.

README.md

@@ -69,6 +69,74 @@ If these variables are present, the workflow writes them to `.env` before runnin
 
 ---
 
+### Runner image requirements
+This template is designed to run the deploy workflow inside a lightweight Docker image that already contains Node.js 20.x and the Adobe AIO CLI, but does not bake in the API Mesh plugin. The plugin is installed on each run inside the GitHub Actions job so that it is always available under the correct `$HOME` and CLI config scope.
+
+Dockerfile used by the workflow:
+
+```
+FROM node:20-bullseye-slim
+
+RUN apt-get update && apt-get install -y \
+    git \
+    ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN npm install -g @adobe/aio-cli && \
+    npm cache clean --force && \
+    rm -rf /root/.npm /tmp/*
+
+WORKDIR /workspace
+
+```
+Build and push the AMD64 image:
+```
+docker buildx build \
+  --platform linux/amd64 \
+  -t ghcr.io/<org-or-user>/aio-mesh-runner:latest \
+  --push \
+  -f .github/images/aio-mesh-runner/Dockerfile .
+```
+
+Reference it in `deploy.yaml`:
+```
+jobs:
+  deploy:
+    runs-on: ${{ matrix.os }}
+    container:
+      image: ghcr.io/<org-or-user>/aio-mesh-runner:latest
+    strategy:
+      matrix:
+        node-version: ["20"]
+        os: [ubuntu-latest]
+    # ...
+
+```
+#### Why the API Mesh plugin is installed in the runner
+The API Mesh plugin (`@adobe/aio-cli-plugin-api-mesh`) is not installed in the Docker image. Instead, the workflow installs it inside the job, for example:
+```
+      - name: Install API Mesh plugin
+        run: aio plugins:install @adobe/aio-cli-plugin-api-mesh
+
+```
+This is required because:
+
+- AIO plugins are resolved per user via the CLI config directory under `$HOME` (for example `~/.config/@adobe/aio`), not from a global shared path.
+- In GitHub container jobs, the runner forcibly sets `HOME=/github/home`, which is different from the `HOME` used at image build time (typically `/root`).
+- If the plugin is only installed during `docker build`, it ends up wired to the build-time home and config; when the job runs with `HOME=/github/home`, `aio` does not see those plugins and `aio api-mesh:*` commands fail.
+
+By installing `@adobe/aio-cli-plugin-api-mesh` inside the GitHub Actions job (with the final `$HOME` already set by the runner), the CLI always discovers the plugin correctly, regardless of how the container image was built.
+
+**If you do not have such a runner image, use the 1.x version of this template, where:**
+
+- The job runs directly on `ubuntu-latest` (no `container`: stanza).
+- `aio` and the API Mesh plugin are installed inside the workflow steps (for example using `adobe/aio-cli-setup-action` plus an explicit `aio plugins:install @adobe/aio-cli-plugin-api-mesh`).
+
+In short:
+
+- 2.x template – requires a prebuilt runner image with `aio`; no CLI installation steps in the workflow.
+- 1.x template – no custom image required; CLI and plugin are installed at runtime in the job, which is slower but does not depend on Docker image management.
+
 ## Quick Start
 
 1. **Fork this repo** or use it as a template inside your organization.