chore(.github): Document and explain CI override directives

.github/PULL_REQUEST_TEMPLATE.md

@@ -2,11 +2,20 @@
 v                               ✰  Thanks for creating a PR! ✰
 ☺ > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >  -->
 
-<!-- Most PRs should close a specific Issue. All PRs should at least reference one or more Issues. Edit and/or delete the following lines as appropriate (note: you don't need both `refs` and `closes` for the same one): -->
+<!-- Most PRs should close a specific issue. All PRs should at least reference one or more issues. Edit and/or delete the following lines as appropriate (note: you don't need both `refs` and `closes` for the same one): -->
 
 closes: #XXXX
 refs: #XXXX
 
+<!-- Integration testing generally doesn't run until a PR is labeled for merge, but can be opted into for every push by adding label 'force:integration', and can be customized to use non-default external targets by including lines here that **start** with leading-`#` directives:
+* (https://github.com/Agoric/documentation) #documentation-branch: $BRANCH_NAME
+* (https://github.com/endojs/endo) #endo-branch: $BRANCH_NAME
+* (https://github.com/Agoric/dapp-offer-up) #getting-started-branch: $BRANCH_NAME
+* (https://github.com/Agoric/testnet-load-generator) #loadgen-branch: $BRANCH_NAME
+
+These directives should be removed before adding a merge label, so final integration tests run against default targets.
+-->
+
 ## Description
 <!-- Add a description of the changes that this PR introduces and the files that are the most critical to review. -->
 

.github/actions/restore-node/action.yml

@@ -41,10 +41,11 @@ runs:
         persist-credentials: false
         path: ${{ inputs.path }}
 
-    # Select a branch on Endo to test against by adding text to the body of the
-    # pull request. For example: #endo-branch: some-pr-branch
-    # The default is 'NOPE' to indicate not to check out Endo, just use
-    # the published NPM packages.
+    # Select an Endo target against which to test, defaulting to 'NOPE' for use
+    # of internally-referenced NPM packages but allowing overrides in the pull
+    # request description for referencing a branch of the
+    # [endo repository](https://github.com/endojs/endo) using lines like
+    # `#endo-branch: rank-strings-by-codepoint`
     - name: Get the appropriate Endo branch
       id: endo-branch
       uses: actions/github-script@v7
@@ -53,8 +54,8 @@ runs:
         script: |-
           let branch = 'NOPE';
           if (${{ inputs.ignore-endo-branch }}) {
-            // Skip endo branch
-          } else  if (context.eventName === 'schedule') {
+            // Skip any override directive.
+          } else if (context.eventName === 'schedule') {
             branch = 'master';
           } else if (context.payload.pull_request) {
             const { body } = context.payload.pull_request;
@@ -85,7 +86,7 @@ runs:
       if: steps.endo-branch.outputs.result != 'NOPE'
       uses: actions/checkout@v4
       with:
-        repository: agoric/endo
+        repository: endojs/endo
         path: ./replacement-endo
         ref: ${{ steps.endo-branch.outputs.result }}
         clean: 'false'

.github/workflows/integration.yml

@@ -35,8 +35,10 @@ jobs:
   pre_check:
     uses: ./.github/workflows/pre-check-integration.yml
 
-  # This job is meant to emulate what developers working with the Agoric platform will experience
-  # It should be kept in sync with https://agoric.com/documentation/getting-started/
+  # This job is meant to emulate what developers working with the Agoric
+  # platform will experience.
+  # It should be kept in sync with the "getting started" workflow at
+  # https://docs.agoric.com/guides/getting-started/
   getting-started:
     needs: pre_check
     if: needs.pre_check.outputs.should_run == 'true'
@@ -60,9 +62,11 @@ jobs:
           node-version: 18.18
           keep-endo: 'true'
 
-      # Select a branch on dapp to test against by adding text to the body of the
-      # pull request. For example: #getting-started-branch: zoe-release-0.7.0
-      # The default is 'main'
+      # Select a branch of the
+      # [default dapp repository](https://github.com/Agoric/dapp-offer-up) (cf.
+      # packages/agoric-cli/src/main.js) against which to test, defaulting to
+      # 'main' but allowing overrides in the pull request description using
+      # lines like `#getting-started-branch: zoe-release-0.7.0`
       - name: Get the appropriate dapp branch
         id: get-branch
         uses: actions/github-script@v7
@@ -138,9 +142,10 @@ jobs:
           # the chances the content of snapshots may deviate between validators
           xsnap-random-init: '1'
 
-      # Select a branch on loadgen to test against by adding text to the body of the
-      # pull request. For example: #loadgen-branch: user-123-update-foo
-      # The default is 'main'
+      # Select a branch of the
+      # [load generator dapp repository](https://github.com/Agoric/testnet-load-generator)
+      # to use, defaulting to 'main' but allowing overrides in the pull request
+      # description using lines like `#loadgen-branch: ceelab`
       - name: Get the appropriate loadgen branch
         id: get-loadgen-branch
         uses: actions/github-script@v7

.github/workflows/test-documentation.yml

@@ -26,9 +26,11 @@ jobs:
           node-version: ${{ matrix.node-version }}
           path: ./agoric-sdk
 
-      # Select a branch on dapp to test against by adding text to the body of the
-      # pull request. For example: #dapp-encouragement-branch: zoe-release-0.7.0
-      # The default is 'main'
+      # Select a branch of the
+      # [documentation repository](https://github.com/Agoric/documentation)
+      # against which to test, defaulting to 'main' but allowing overrides in
+      # the pull request description using lines like
+      # `#documentation-branch: node-22`
       - name: Get the appropriate dapp branch
         id: get-branch
         uses: actions/github-script@v7
@@ -44,7 +46,7 @@ jobs:
                 branch = result[1];
               }
             }
-            console.log(branch);
+            console.log('documentation branch: ' + branch);
             return branch;
 
       - name: Check out dapp