GitHub Action Authoring — setup-boxlang

When to Use

• Adding or fixing Windows, Linux, or macOS support in action.yml
• Writing or debugging PowerShell (shell: powershell) steps
• Adding new inputs, outputs, or conditional steps
• Updating tests.yml with new platform/feature coverage
• Debugging PATH issues on GitHub Actions Windows runners
• Installing third-party tools (BoxLang, CommandBox) in CI

Architecture

action.yml is a composite action with platform-specific parallel step pairs:

Every step pair uses if: runner.os != 'Windows' / if: runner.os == 'Windows' conditions.

Critical Rules

Platform conditionals

Always use both sides for every platform-specific step:

- name: My Step (Unix/Linux/macOS)
  if: runner.os != 'Windows'
  shell: bash
  run: |
    ...

- name: My Step (Windows)
  if: runner.os == 'Windows'
  shell: powershell
  run: |
    ...

Environment variables in PowerShell steps

${{ env.SOMEVAR }} does NOT expand inside composite action PowerShell step bodies — it resolves to an empty string. Always use $env:SOMEVAR to read runner environment variables at runtime:

# WRONG — ${{ env.GITHUB_WORKSPACE }} expands to empty in PS steps
$dir = "${{ env.GITHUB_WORKSPACE }}\.boxlang"

# CORRECT
$dir = "$env:GITHUB_WORKSPACE\.boxlang"

${{ inputs.xxx }} and ${{ runner.os }} DO expand correctly (they are template substitutions, not env reads).

Writing to GITHUBENV and GITHUBOUTPUT in PowerShell

# Set env var for subsequent steps
Add-Content -Path $env:GITHUB_ENV -Value "MY_VAR=value"

# Set step output
Add-Content -Path $env:GITHUB_OUTPUT -Value "my-output=value"

# Update PATH for subsequent steps
$env:PATH = "C:\my\bin;$env:PATH"
Add-Content -Path $env:GITHUB_ENV -Value "PATH=$env:PATH"

Invoke-WebRequest Content is byte[] in PS7+

On windows-latest (PowerShell 7), .Content from Invoke-WebRequest is System.Byte[], not a string. Invoke-Expression fails on it. Always save to a file first:

# WRONG — fails on PS7+ runners
$script = Invoke-WebRequest -Uri $url -UseBasicParsing
Invoke-Expression $script.Content

# CORRECT
$tmpScript = [System.IO.Path]::Combine([System.IO.Path]::GetTempPath(), "script.ps1")
Invoke-WebRequest -Uri $url -OutFile $tmpScript -UseBasicParsing -ErrorAction Stop
& $tmpScript <arguments>
Remove-Item $tmpScript -Force -ErrorAction SilentlyContinue

Installer flag ordering matters

The install-boxlang.ps1 installer parses flags sequentially. --yes sets INSTALL_COMMANDBOX=true internally. If --without-commandbox comes before --yes, that later --yes overrides it. Always put --yes first:

# WRONG — --yes overrides --without-commandbox
& $tmpScript --without-commandbox --yes

# CORRECT — --without-commandbox processed last, wins
& $tmpScript --yes --without-commandbox

Windows PATH after installer

Third-party installers on Windows write to the Machine registry PATH (requires admin). Even if the registry write succeeds, the current PowerShell session does not pick it up automatically. Always explicitly rebuild PATH and push it to GITHUB_ENV:

# Explicitly prepend known install paths — don't rely on the installer having done it
$env:PATH = "C:\known\install\bin;" +
            [System.Environment]::GetEnvironmentVariable("PATH", "Machine") + ";" +
            [System.Environment]::GetEnvironmentVariable("PATH", "User")
Add-Content -Path $env:GITHUB_ENV -Value "PATH=$env:PATH"

Never delegate CommandBox installation to the BoxLang PS1 installer on Windows

The BoxLang installer places box.exe at c:\boxlang\bin\box.exe but its PATH update is unreliable on CI. Use the dedicated "Install CommandBox (Windows)" step instead, which:

1. Downloads type/windows from Ortus (not type/bin — that is the Linux binary)
2. Extracts to a controlled path (C:\ProgramData\CommandBox)
3. Verifies with the full path & "$boxDir\box.exe" version — no PATH trust needed
4. Explicitly prepends $boxDir to PATH + GITHUB_ENV

Composite action outputs when steps are conditional

Each platform step must have its own id. Outputs must pick the right step per platform:

outputs:
  boxlang-version:
    value: ${{ runner.os == 'Windows' && steps.install-boxlang-windows.outputs.version || steps.install-boxlang.outputs.version }}

BoxLang Installer Reference

Unix installer flags: <version> --without-commandbox Windows installer flags: --yes --without-commandbox (or --yes --with-commandbox)

CommandBox Download URLs

Bash → PowerShell Conversion Quick Reference

tests.yml Conventions

• Each new feature gets its own job (e.g. testwithmodules)
• Each new platform gets its own named job (e.g. testwindowsdefault_home)
• Platform matrix jobs use strategy.matrix.os and runs-on: ${{ matrix.os }}
• Windows verification steps use shell: powershell and check env vars with $env:VAR
• Unix verification steps use inline bash run: blocks
• All Windows jobs verify BOXLANG_HOME is set and contains the expected path

# Windows env var verification pattern
- name: Verify BOXLANG_HOME (Windows)
  shell: powershell
  run: |
    if ($env:BOXLANG_HOME -ne "expected\path") {
      Write-Host "Expected: expected\path  Got: $env:BOXLANG_HOME"
      exit 1
    }
    Write-Host "BOXLANG_HOME is correct: $env:BOXLANG_HOME"