canonical
diff --git a/‎.github/workflows/checkin.yml
Lines changed: 11 additions & 2 deletions b/‎.github/workflows/checkin.yml
Lines changed: 11 additions & 2 deletions
diff --git a/‎.github/workflows/manual-detached-test.yml
Lines changed: 3 additions & 4 deletions b/‎.github/workflows/manual-detached-test.yml
Lines changed: 3 additions & 4 deletions
diff --git a/‎.github/workflows/manual-test.yml
Lines changed: 61 additions & 31 deletions b/‎.github/workflows/manual-test.yml
Lines changed: 61 additions & 31 deletions
diff --git a/‎.github/workflows/update-manual-test.js
Lines changed: 62 additions & 0 deletions b/‎.github/workflows/update-manual-test.js
Lines changed: 62 additions & 0 deletions
diff --git a/‎README.md
Lines changed: 83 additions & 7 deletions b/‎README.md
Lines changed: 83 additions & 7 deletions
@@ -8,11 +8,19 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Use Node.js
         uses: actions/setup-node@v3
         with:
           node-version: 20
+      - name: Verify that action.yml files are in sync
+        run: |
+          npm run update-detached-action.yml &&
+          if ! git diff --exit-code \*action.yml
+          then
+            echo '::error::action.yml files are not in sync, maybe run `npm run update-detached-action.yml`?'
+            exit 1
+          fi
       - name: Install dependencies
         run: npm ci
       - name: Run tests
@@ -24,7 +32,8 @@ jobs:
       - name: Verify that the project is built
         run: |
           if [[ -n $(git status -s) ]]; then
-            echo "ERROR: generated dist/ differs from the current sources"
+            echo "ERROR: generated lib/ differs from the current sources"
+            git status -s
             git diff
             exit 1
           fi
@@ -5,11 +5,10 @@ jobs:
   test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - uses: ./
+      - uses: actions/checkout@v4
+      - uses: ./detached
         with:
-          limit-access-to-actor: true
-          detached: true
+          connect-timeout-seconds: 60
       - run: |
           echo "A busy loop"
           for value in $(seq 10)
 
@@ -1,43 +1,73 @@
-name: Manual test matrix
-on: workflow_dispatch
+name: Manual test
+on:
+  workflow_dispatch:
+    inputs:
+      runs-on:
+        type: choice
+        description: 'The runner pool to run the job on'
+        required: true
+        default: ubuntu-24.04
+        options:
+          - ubuntu-24.04
+          - ubuntu-22.04
+          - macos-15-large
+          - macos-15
+          - macos-14-large
+          - macos-14
+          - macos-13
+          - macos-13-xlarge
+          - windows-2025
+          - windows-2022
+          - windows-2019
+          - windows-11-arm
+      container-runs-on:
+        type: choice
+        description: 'The Docker container to run the job on (this overrides the `runs-on` input)'
+        required: false
+        default: '(none)'
+        options:
+          - '(none)'
+          - fedora:latest
+          - archlinux:latest
+          - ubuntu:latest
+      limit-access-to-actor:
+        type: choice
+        description: 'Whether to limit access to the actor only'
+        required: true
+        default: 'auto'
+        options:
+          - auto
+          - 'true'
+          - 'false'
 
 jobs:
   test:
-    strategy:
-      fail-fast: false
-      matrix:
-        runs-on:
-          - ubuntu-20.04
-          - ubuntu-22.04
-          - macos-11.0
-          - macos-12.0
-          - windows-2019
-          - windows-2022
-        limit-access-to-actor:
-          - true
-          - false
-    runs-on: ${{ matrix.runs-on }}
+    if: ${{ inputs.container-runs-on == '(none)' }}
+    runs-on: ${{ inputs.runs-on }}
     steps:
-      - uses: actions/checkout@v3
+      - uses: msys2/setup-msys2@v2
+        # The public preview of GitHub-hosted Windows/ARM64 runners lacks
+        # a working MSYS2 installation, so we need to set it up ourselves.
+        if: ${{ inputs.runs-on == 'windows-11-arm' }}
+        with:
+          msystem: 'CLANGARM64'
+          # We cannot use `C:\` because `msys2/setup-msys2` erroneously
+          # believes that an MSYS2 exists at `C:\msys64`, but it doesn't,
+          # which is the entire reason why we need to set it up in this
+          # here step... However, by using `C:\.\` we can fool that
+          # overzealous check.
+          location: C:\.\
+      - uses: actions/checkout@v4
       - uses: ./
         with:
-          limit-access-to-actor: ${{ matrix.limit-access-to-actor }}
+          limit-access-to-actor: ${{ inputs.limit-access-to-actor }}
   test-container:
-    strategy:
-      fail-fast: false
-      matrix:
-        container-runs-on:
-          - fedora:latest
-          - archlinux:latest
-          - ubuntu:latest
-        limit-access-to-actor:
-          - true
-          - false
+    if: ${{ inputs.container-runs-on != '(none)' }}
     runs-on: ubuntu-latest
     container:
-      image: ${{ matrix.container-runs-on }}
+      image: ${{ inputs.container-runs-on }}
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: ./
         with:
-          limit-access-to-actor: ${{ matrix.limit-access-to-actor }}
+          limit-access-to-actor: ${{ inputs.limit-access-to-actor }}
@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+// Update the `runs-on` options of the `manual-test.yml` workflow file with the
+// latest available images from the GitHub Actions runner images README file.
+
+(async () => {
+  const fs = require('fs')
+
+  const readme = await (await fetch("https://github.com/actions/runner-images/raw/HEAD/README.md")).text()
+
+  // This will be the first `ubuntu` one.
+  let defaultOption = ''
+
+  const choices = readme
+    // Get the "Available Images" section
+    .split(/\n## Available Images\n/)[1]
+    .split(/##\s*[^#]/)[0]
+    // Split by lines
+    .split('\n')
+    .map(line => {
+        // The relevant lines are table rows; The first column is the image name,
+        // the second one contains a relatively free-form list of the `runs-on`
+        // options that we are interested in. Those `runs-on` options are
+        // surrounded by backticks.
+        const match = line.match(/^\|\s*([^|]+)\s*\|([^|]*)`([^`|]+)`\s*\|/)
+        if (!match) return false // Skip e.g. the table header and empty lines
+        let runsOn = match[3] // default to the last `runs-on` option
+        const alternatives = match[2]
+          .split(/`([^`]*)`/) // split by backticks
+          .filter((_, i) => (i % 2)) // keep only the text between backticks
+          .sort((a, b) => a.length - b.length) // order by length
+        if (alternatives.length > 0 && alternatives[0].length < runsOn.length) runsOn = alternatives[0]
+        if (!defaultOption && match[3].startsWith('ubuntu-')) defaultOption = runsOn
+        return runsOn
+    })
+    .filter(runsOn => runsOn)
+
+  // The Windows/ARM64 runners are in public preview (and for the time being,
+  // not listed in the `runner-images` README file), so we need to add this
+  // manually.
+  if (!choices.includes('windows-11-arm')) choices.push('windows-11-arm')
+
+  // Now edit the `manual-test` workflow definition
+  const ymlPath = `${__dirname}/manual-test.yml`
+  const yml = fs.readFileSync(ymlPath, 'utf8')
+
+  // We want to replace the `runs-on` options and the `default` value. This
+  // would be easy if there was a built-in YAML parser and renderer in Node.js,
+  // but there is none. Therefore, we use a regular expression to find certain
+  // "needles" near the beginning of the file: first `workflow_dispatch:`,
+  // after that `runs-on:` and then `default:` and `options:`. Then we replace
+  // the `default` value and the `options` values with the new ones.
+  const [, beforeDefault, beforeOptions, optionsIndent, afterOptions] =
+    yml.match(/^([^]*?workflow_dispatch:[^]*?runs-on:[^]*?default:)(?:.*)([^]*?options:)(\n +- )(?:.*)(?:\3.*)*([^]*)/) || []
+  if (!beforeDefault) throw new Error(`The 'manual-test.yml' file does not match the expected format!`)
+  const newYML =
+    `${beforeDefault} ${defaultOption}${[beforeOptions, ...choices].join(optionsIndent)}${afterOptions}`
+  fs.writeFileSync(ymlPath, newYML)
+})().catch(e => {
+  console.error(e)
+  process.exitCode = 1
+})
@@ -33,7 +33,7 @@ jobs:
   build:
     runs-on: self-hosted
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Setup tmate session
       uses: canonical/action-tmate@main
 ```
@@ -91,7 +91,7 @@ jobs:
   build:
     runs-on: self-hosted
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Setup tmate session
       uses: canonical/action-tmate@main
       with:
@@ -100,6 +100,44 @@ jobs:
 
 By default, this mode will wait at the end of the job for a user to connect and then to terminate the tmate session. If no user has connected within 10 minutes after the post-job step started, it will terminate the `tmate` session and quit gracefully.
 
+As this mode has turned out to be so useful as to having the potential for being the default mode once time travel becomes available, it is also available as `mxschmitt/action-tmate/detached` for convenience.
+
+### Using SSH command output in other jobs
+
+When running in detached mode, the action sets the following outputs that can be used in subsequent steps or jobs:
+
+- `ssh-command`: The SSH command to connect to the tmate session
+- `ssh-address`: The raw SSH address without the "ssh" prefix
+- `web-url`: The web URL to connect to the tmate session (if available)
+
+Example workflow using the SSH command in another job:
+
+```yaml
+name: Debug with tmate
+on: [push]
+jobs:
+  setup-tmate:
+    runs-on: ubuntu-latest
+    outputs:
+      ssh-command: ${{ steps.tmate.outputs.ssh-command }}
+      ssh-address: ${{ steps.tmate.outputs.ssh-address }}
+    steps:
+    - uses: actions/checkout@v4
+    - name: Setup tmate session
+      id: tmate
+      uses: mxschmitt/action-tmate@v3
+      with:
+        detached: true
+        
+  use-ssh-command:
+    needs: setup-tmate
+    runs-on: ubuntu-latest
+    steps:
+    - name: Display SSH command
+      run: |
+        # Send a Slack message to someone telling them they can ssh to ${{ needs.setup-tmate.outputs.ssh-address }}
+```
+
 ## Without sudo
 
 By default we run installation commands using sudo on Linux. If you get `sudo: not found` you can use the parameter below to execute the commands directly.
@@ -111,7 +149,7 @@ jobs:
   build:
     runs-on: self-hosted
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Setup tmate session
       uses: canonical/action-tmate@main
       with:
@@ -129,7 +167,7 @@ jobs:
   build:
     runs-on: self-hosted
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Setup tmate session
       uses: canonical/action-tmate@main
       timeout-minutes: 15
@@ -148,7 +186,7 @@ jobs:
   build:
     runs-on: self-hosted
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Setup tmate session
       if: ${{ failure() }}
       uses: canonical/action-tmate@main
@@ -157,6 +195,26 @@ jobs:
 {% endraw %}
 -->
 
+## Use registered public SSH key(s)
+
+If [you have registered one or more public SSH keys with your GitHub profile](https://docs.github.com/en/github/authenticating-to-github/adding-a-new-ssh-key-to-your-github-account), tmate will be started such that only those keys are authorized to connect, otherwise anybody can connect to the tmate session. If you want to require a public SSH key to be installed with the tmate session, no matter whether the user who started the workflow has registered any in their GitHub profile, you will need to configure the setting `limit-access-to-actor` to `true`, like so:
+
+```yaml
+name: CI
+on: [push]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - name: Setup tmate session
+      uses: canonical/action-tmate@v3
+      with:
+        limit-access-to-actor: true
+```
+
+If the registered public SSH key is not your default private SSH key, you will need to specify the path manually, like so: `ssh -i <path-to-key> <tmate-connection-string>`.
+
 ## Use your own tmate servers
 
 By default, this action uses environment variables to pick up tmate ssh configuration settings and
@@ -169,7 +227,7 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Setup tmate session
       uses: canonical/action-tmate@main
       with:
@@ -179,9 +237,27 @@ jobs:
 -        tmate-server-ed25519-fingerprint: SHA256:jfttvoypkHiQYUqUCwKeqd9d1fJj/ZiQlFOHVl6E9sI
 ```
 
+## Use a different MSYS2 location
+
+If you want to integrate with the msys2/setup-msys2 action or otherwise don't have an MSYS2 installation at `C:\msys64`, you can specify a different location for MSYS2:
+
+```yaml
+name: CI
+on: [push]
+jobs:
+  build:
+    runs-on: windows-latest
+    steps:
+    - uses: msys2/setup-msys2@v2
+      id: setup-msys2
+    - uses: mxschmitt/action-tmate@v3
+      with:
+        msys2-location: ${{ steps.setup-msys2.outputs.msys2-location }}
+```
+
 ## Continue a workflow
 
-If you want to continue a workflow and you are inside a tmate session, just create a empty file with the name `continue` either in the root directory or in the project directory by running `touch continue` or `sudo touch /continue`.
+If you want to continue a workflow and you are inside a tmate session, just create a empty file with the name `continue` either in the root directory or in the project directory by running `touch continue` or `sudo touch /continue` (on Linux).
 
 ## Connection string / URL is not visible