feat: add submodule checkout

.github/README.md

@@ -8,6 +8,7 @@ This file documents the **OCI / Docker / Helm** composites and their callable wo
 
 | Kind | Path | Purpose |
 |------|------|---------|
+| Composite | `.github/actions/checkout-repo` | Caller checkout with optional private **recursive submodules** (GitHub App) |
 | Composite | `.github/actions/docker-build-push` | ECR private/public OIDC or registry login; **Buildx** + QEMU, or **Warp** |
 | Composite | `.github/actions/helm-publish-oci` | Non-PR Helm **OCI** publish (lint, push) via registry token or AWS OIDC (ECR) |
 | Composite | `.github/actions/slack-notify-failure` | Small Slack failure step (`ravsamhq/notify-slack-action`) |
@@ -53,6 +54,26 @@ jobs:
       runs-on-arm64: ubuntu-24.04-arm
 ```
 
+**Callable** — Docker with private submodules (set `vars.APP_ID` + `secrets.APP_KEY` on the **caller** repo; the reusable workflow passes `vars.APP_ID` into the checkout composite):
+
+```yaml
+jobs:
+  image:
+    uses: FuelLabs/github-actions/.github/workflows/docker-build-push.yml@v1.0.0
+    secrets: inherit
+    with:
+      auth-mode: ecr-oidc
+      aws-role-arn: ${{ secrets.AWS_ROLE_ARN }}
+      dockerfile: Dockerfile
+      image: 123.dkr.ecr.us-east-1.amazonaws.com/myapp-service
+      build-backend: native
+      checkout-submodules: true
+      checkout-app-repositories: |
+        fuel-o2
+        my-app
+        my-submodule-repo
+```
+
 **Callable** — Docker to ECR Public (OIDC):
 
 ```yaml

.github/actions/checkout-repo/action.yml

@@ -0,0 +1,37 @@
+name: Checkout caller repository
+description: >
+  Checkout the consumer repository. When submodules is true, mints a GitHub App token
+  (app-id input + APP_KEY env) and checks out submodules recursively for private deps.
+
+inputs:
+  submodules:
+    description: 'true | false — recursive submodule checkout with GitHub App auth'
+    required: false
+    default: 'false'
+  app-id:
+    description: GitHub App ID (pass vars.APP_ID from the calling workflow)
+    required: false
+    default: ''
+  app-repositories:
+    description: Multiline repository names for create-github-app-token
+    required: false
+    default: ''
+
+runs:
+  using: composite
+  steps:
+    - name: Create GitHub App token
+      if: inputs.submodules == 'true'
+      uses: actions/create-github-app-token@v2
+      id: app-token
+      with:
+        app-id: ${{ inputs.app-id }}
+        private-key: ${{ env.APP_KEY }}
+        owner: ${{ github.repository_owner }}
+        repositories: ${{ inputs.app-repositories }}
+
+    - name: Checkout
+      uses: actions/checkout@v4
+      with:
+        submodules: ${{ inputs.submodules == 'true' && 'recursive' || 'false' }}
+        token: ${{ inputs.submodules == 'true' && steps.app-token.outputs.token || github.token }}

.github/workflows/docker-build-push.yml

@@ -110,6 +110,18 @@ on:
           If empty, a 16-char hash of inputs.image is used.
         required: false
         default: ''
+      checkout-submodules:
+        type: boolean
+        description: >
+          Checkout private git submodules before build (GitHub App: caller repo vars.APP_ID + secrets.APP_KEY).
+        default: false
+      checkout-app-repositories:
+        type: string
+        description: >
+          Multiline repo names for create-github-app-token (include caller + submodule repos).
+          Required when checkout-submodules is true.
+        required: false
+        default: ''
     secrets:
       REGISTRY_USERNAME:
         description: Username for registry-login (omit for pure ECR OIDC)
@@ -122,6 +134,9 @@ on:
           Optional. WarpBuild API key for Docker Builders when runs-on is not a WarpBuild runner
           (see https://www.warpbuild.com/docs/ci/docker-builders).
         required: false
+      APP_KEY:
+        description: GitHub App private key (required when checkout-submodules is true)
+        required: false
     outputs:
       image:
         description: Repository/image name without tag (inputs.image — stable across native-merge and Warp)
@@ -219,7 +234,14 @@ jobs:
       fail-fast: false
       matrix: ${{ fromJSON(needs.native-plan.outputs.matrix) }}
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout repository
+        uses: FuelLabs/github-actions/.github/actions/checkout-repo@master
+        env:
+          APP_KEY: ${{ secrets.APP_KEY }}
+        with:
+          submodules: ${{ inputs.checkout-submodules && 'true' || 'false' }}
+          app-id: ${{ vars.APP_ID }}
+          app-repositories: ${{ inputs.checkout-app-repositories }}
 
       - name: Derive platform pair
         id: platform
@@ -461,7 +483,14 @@ jobs:
       fail-fast: false
       matrix: ${{ fromJSON(needs.warp-multi-plan.outputs.matrix) }}
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout repository
+        uses: FuelLabs/github-actions/.github/actions/checkout-repo@master
+        env:
+          APP_KEY: ${{ secrets.APP_KEY }}
+        with:
+          submodules: ${{ inputs.checkout-submodules && 'true' || 'false' }}
+          app-id: ${{ vars.APP_ID }}
+          app-repositories: ${{ inputs.checkout-app-repositories }}
 
       - name: Derive platform pair
         id: platform
@@ -643,7 +672,14 @@ jobs:
       digest: ${{ steps.warp-push.outputs.digest }}
       metadata: ${{ steps.docker-meta.outputs.metadata }}
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout repository
+        uses: FuelLabs/github-actions/.github/actions/checkout-repo@master
+        env:
+          APP_KEY: ${{ secrets.APP_KEY }}
+        with:
+          submodules: ${{ inputs.checkout-submodules && 'true' || 'false' }}
+          app-id: ${{ vars.APP_ID }}
+          app-repositories: ${{ inputs.checkout-app-repositories }}
 
       - name: Login and Docker metadata
         id: docker-meta