Give CI a GitHub App token so it can read the private instrument submodules

.github/workflows/docs.yml

@@ -21,10 +21,21 @@ jobs:
     timeout-minutes: 30
 
     steps:
+      # Two instrument submodules are private, and GITHUB_TOKEN cannot read
+      # another repository, so checkout needs a token scoped by the app install
+      - name: Mint a submodule read token
+        id: app-token
+        uses: actions/create-github-app-token@v3
+        with:
+          app-id: ${{ secrets.SUBMODULE_APP_ID }}
+          private-key: ${{ secrets.SUBMODULE_APP_PRIVATE_KEY }}
+          owner: ${{ github.repository_owner }}
+
       - name: Checkout repository
         uses: actions/checkout@v4
         with:
           submodules: recursive
+          token: ${{ steps.app-token.outputs.token }}
 
       - name: Set up Python
         uses: actions/setup-python@v5

.github/workflows/emulator-integration.yml

@@ -12,9 +12,20 @@ jobs:
     timeout-minutes: 10
 
     steps:
+    # Two instrument submodules are private, and GITHUB_TOKEN cannot read
+    # another repository, so checkout needs a token scoped by the app install
+    - name: Mint a submodule read token
+      id: app-token
+      uses: actions/create-github-app-token@v3
+      with:
+        app-id: ${{ secrets.SUBMODULE_APP_ID }}
+        private-key: ${{ secrets.SUBMODULE_APP_PRIVATE_KEY }}
+        owner: ${{ github.repository_owner }}
+
     - uses: actions/checkout@v4
       with:
         submodules: true
+        token: ${{ steps.app-token.outputs.token }}
 
     - name: Install dependencies
       run: |
@@ -121,9 +132,20 @@ jobs:
     timeout-minutes: 15
 
     steps:
+    # Two instrument submodules are private, and GITHUB_TOKEN cannot read
+    # another repository, so checkout needs a token scoped by the app install
+    - name: Mint a submodule read token
+      id: app-token
+      uses: actions/create-github-app-token@v3
+      with:
+        app-id: ${{ secrets.SUBMODULE_APP_ID }}
+        private-key: ${{ secrets.SUBMODULE_APP_PRIVATE_KEY }}
+        owner: ${{ github.repository_owner }}
+
     - uses: actions/checkout@v4
       with:
         submodules: true
+        token: ${{ steps.app-token.outputs.token }}
 
     - name: Install dependencies
       run: |
@@ -202,9 +224,20 @@ jobs:
     timeout-minutes: 10
 
     steps:
+    # Two instrument submodules are private, and GITHUB_TOKEN cannot read
+    # another repository, so checkout needs a token scoped by the app install
+    - name: Mint a submodule read token
+      id: app-token
+      uses: actions/create-github-app-token@v3
+      with:
+        app-id: ${{ secrets.SUBMODULE_APP_ID }}
+        private-key: ${{ secrets.SUBMODULE_APP_PRIVATE_KEY }}
+        owner: ${{ github.repository_owner }}
+
     - uses: actions/checkout@v4
       with:
         submodules: true
+        token: ${{ steps.app-token.outputs.token }}
 
     - name: Install dependencies
       run: |

.github/workflows/update-submodules.yml

@@ -11,12 +11,22 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
+      # Two instrument submodules are private, and GITHUB_TOKEN cannot read
+      # another repository, so checkout needs a token scoped by the app install
+      - name: Mint a submodule read token
+        id: app-token
+        uses: actions/create-github-app-token@v3
+        with:
+          app-id: ${{ secrets.SUBMODULE_APP_ID }}
+          private-key: ${{ secrets.SUBMODULE_APP_PRIVATE_KEY }}
+          owner: ${{ github.repository_owner }}
+
       - name: Checkout repository
         uses: actions/checkout@v4
         with:
           submodules: true
           fetch-depth: 0
-          token: ${{ secrets.GITHUB_TOKEN }}
+          token: ${{ steps.app-token.outputs.token }}
 
       - name: Configure git
         run: |

docs/development/index.md

@@ -97,3 +97,17 @@ behind changes to the core without CI noticing.
 Instrument modules are pinned submodules. Updating one is a commit to `camera-interface` that moves
 the pin, which `.github/workflows/update-submodules.yml` automates. Documentation for an instrument
 lives here, in this repository, while each instrument repository keeps its own README.
+
+Some instrument repositories are private. A workflow's built-in `GITHUB_TOKEN` is scoped to this
+repository alone and cannot read another one, so any job checking out submodules first mints a token
+from a GitHub App and passes it to `actions/checkout`. That needs two repository secrets:
+
+| Secret | Holds |
+|---|---|
+| `SUBMODULE_APP_ID` | The App's numeric ID |
+| `SUBMODULE_APP_PRIVATE_KEY` | The App's private key, in PEM form |
+
+The App needs `Contents: read` and must be installed on every instrument repository, public ones
+included, because the token authenticates all submodule fetches and a repository outside the
+installation is rejected even when it is public. Adding a new private instrument therefore means
+adding it to the App installation, not changing any workflow.