xonsh/actions

GitHub Actions for the xonsh shell.

xonsh/actions — setup-xonsh

Composite action that installs xonsh on the runner. Subsequent steps run as xonsh by setting either shell: xonsh {0} on a single step or defaults.run.shell: xonsh {0} on the whole job.

Usage

Per-step shell

Set shell: xonsh {0} on the individual step(s) that should run as xonsh — the rest of the job keeps its normal shell:

jobs:
  my-job:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: xonsh/actions@v1

      - name: Run xonsh
        shell: xonsh {0}
        run: |
          echo "hello from xonsh"
          $PATH.append('/mypath')
          print($PATH)

Job-level default

Declare defaults.run.shell: xonsh {0} once and every subsequent run: block in the job executes as xonsh:

jobs:
  my-job:
    runs-on: ubuntu-latest
    defaults:
      run:
        shell: xonsh {0}
    steps:
      - uses: actions/checkout@v4
      - uses: xonsh/actions@v1

      - run: |
          echo "hello from xonsh"
          $PATH.append('/mypath')
          print($PATH)

Why {0}? GitHub Actions doesn't support a bare shell: xonsh — the {0} placeholder is required for every non-built-in shell.

Inputs

Input	Description	Default
xonsh-version	PyPI version spec (e.g. 0.23.1, >=0.23.1). Empty installs the latest.	(latest)
python-version	If set, runs actions/setup-python@v5 with this version.	(pre-installed Python)
extras	pip extras for xonsh, e.g. full. Installs as xonsh[<extras>].	(none)
xontribs	Space-separated list of extra pip packages (xontribs, etc.) installed after xonsh. E.g. xontrib-abbrevs xontrib-pipeliner.	(none)

Outputs

Output	Description
xonsh-version	The installed xonsh version (e.g. 0.23.1).
xonsh-path	Absolute path to the xonsh executable.

Cross-platform

Tested on ubuntu-latest, macos-latest, and windows-latest.

Full example

Uses every input and reads both outputs:

jobs:
  my-job:
    runs-on: ubuntu-latest
    defaults:
      run:
        shell: xonsh {0}
    steps:
      - uses: actions/checkout@v4

      - id: xonsh
        uses: xonsh/actions@v1
        with:
          python-version: '3.13'         # actions/setup-python before install
          xonsh-version: '0.23.1'        # pinned PyPI version
          extras: 'full'                 # installs xonsh[full]
          xontribs: 'xontrib-abbrevs xontrib-pipeliner'   # space-separated pip packages

      - name: Use xonsh
        run: |
          echo "installed xonsh ${{ steps.xonsh.outputs.xonsh-version }}"
          echo "xonsh binary at ${{ steps.xonsh.outputs.xonsh-path }}"
          print(f"running xonsh {xonsh.__version__} on Python {sys.version.split()[0]}")
          xcontext
          xontrib load pipeliner
          echo hello | pl @!(line.upper())

Sharing state with later steps

$PATH.append('/mypath') inside a xonsh step only affects that step's process. To make the change visible in subsequent steps, also append to $GITHUB_PATH:

jobs:
  my-job:
    runs-on: ubuntu-latest
    defaults:
      run:
        shell: xonsh {0}
    steps:
      - uses: actions/checkout@v4
      - uses: xonsh/actions@v1

      - run: |
          $PATH.append('/mypath')
          with open($GITHUB_PATH, 'a') as f:
              f.write('/mypath\n')

Reusable workflows

test-pip-xontrib.yml

Real life example from xontrib-abbrevs/.github/workflows/test.yml:

name: Testing

on:
  push:
  pull_request:

jobs:
  testing:
    # reuse workflow definitions
    uses: xonsh/actions/.github/workflows/test-pip-xontrib.yml@v1
    with:
      cache-dependency-path: pyproject.toml

test-poetry-xontrib.yml

Same matrix, but uses Poetry for dependency management. Pass the xontrib_name input so the workflow can xontrib load it:

jobs:
  testing:
    uses: xonsh/actions/.github/workflows/test-poetry-xontrib.yml@v1
    with:
      xontrib_name: my_xontrib