Integrations

Expanse integrates with your existing development tools and CI/CD pipelines.

AI Coding Assistants

Expanse provides context files that help AI coding assistants understand your HPC workflows.

Claude Code

Create a CLAUDE.md file in your project root to give Claude context about Expanse:

# CLAUDE.md

## Project Overview
This is an HPC simulation project using Expanse for workflow orchestration.

## Expanse Structure
- `nodes/` - Computational nodes (each folder has node.yaml + source code)
- `workflows/` - Pipeline definitions connecting nodes
- `data/` - Static input files
- `results/` - Output files from completed workflows
- `expanse.yaml` - Cluster configuration

## Key Commands
- `expanse run <workflow>` - Execute a workflow
- `expanse nodes validate` - Check node configurations
- `expanse status` - View running jobs
- `expanse logs <job-id>` - Stream job logs

## Node Development
Nodes use expanse_io for data I/O:
- Python: `from expanse_io import read_input, write_output`
- Fortran: `use expanse_io` with `expanse_read_real64`, `expanse_write_real64`
- C: `#include "expanse_io.h"`

Inputs arrive in EXPANSE_INPUTS, outputs go to EXPANSE_ARTIFACT_DIR.

## Data Types
- `array[float64, N]` - N-dimensional float array
- `array[int32, N]` - N-dimensional integer array
- `json` - JSON configuration
- `file` - Raw file path

Claude will use this context to provide better assistance with node development, workflow design, and debugging.

Other AI Assistants

Create similar context files for other assistants:

• AGENTS.md - For OpenAI Codex / ChatGPT
• GEMINI.md - For Google Gemini
• .cursorrules - For Cursor IDE

The content structure is the same—adapt the filename to your assistant's convention.

GitHub Integration

GitHub Actions

Validate workflows and run tests on every push:

# .github/workflows/expanse.yml
name: Expanse CI

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install Expanse CLI
        run: curl -sSL https://get.expanse.org.uk | sh
      
      - name: Validate nodes
        run: expanse nodes validate
      
      - name: Validate workflows
        run: expanse workflows validate
      
      - name: Dry run (syntax check)
        run: expanse run workflows/pipeline.yaml --dry-run

  test:
    runs-on: ubuntu-latest
    needs: validate
    steps:
      - uses: actions/checkout@v4
      
      - name: Install Expanse CLI
        run: curl -sSL https://get.expanse.org.uk | sh
      
      - name: Run test workflow
        run: expanse run workflows/test.yaml --cluster local --wait

Branch-Based Workflows

Run different workflows based on branch:

# .github/workflows/expanse-deploy.yml
name: Expanse Deploy

on:
  push:
    branches: [main, develop]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install Expanse CLI
        run: curl -sSL https://get.expanse.org.uk | sh
      
      - name: Run on develop (test cluster)
        if: github.ref == 'refs/heads/develop'
        run: expanse run workflows/pipeline.yaml --cluster test
      
      - name: Run on main (production cluster)
        if: github.ref == 'refs/heads/main'
        run: expanse run workflows/pipeline.yaml --cluster archer2

GitLab Integration

GitLab CI/CD

# .gitlab-ci.yml
stages:
  - validate
  - test
  - deploy

variables:
  EXPANSE_TOKEN: $EXPANSE_TOKEN  # Set in GitLab CI/CD variables

validate:
  stage: validate
  image: ubuntu:latest
  script:
    - curl -sSL https://get.expanse.org.uk | sh
    - expanse nodes validate
    - expanse workflows validate

test:
  stage: test
  image: ubuntu:latest
  script:
    - curl -sSL https://get.expanse.org.uk | sh
    - expanse run workflows/test.yaml --cluster local --wait
  only:
    - merge_requests
    - develop

deploy:
  stage: deploy
  image: ubuntu:latest
  script:
    - curl -sSL https://get.expanse.org.uk | sh
    - expanse run workflows/pipeline.yaml --cluster archer2 --wait
  only:
    - main
  when: manual  # Require manual approval for production runs

GitLab Badges

Add status badges to your README:

[![Expanse Validation](https://gitlab.com/your-org/your-project/badges/main/pipeline.svg)](https://gitlab.com/your-org/your-project/-/pipelines)

Authentication in CI/CD

Store your Expanse credentials as CI/CD secrets:

GitHub:

• Go to Settings → Secrets and variables → Actions
• Add EXPANSE_TOKEN with your API token

GitLab:

• Go to Settings → CI/CD → Variables
• Add EXPANSE_TOKEN (masked and protected)

Then in your workflow:

- name: Authenticate
  run: expanse login --token ${{ secrets.EXPANSE_TOKEN }}

IDE Integration

VS Code

Install the Expanse extension for:

• Syntax highlighting for node.yaml and workflow files
• Validation on save
• Job status in the status bar
• Log streaming in the terminal

code --install-extension expanse.expanse-vscode

JetBrains (PyCharm, CLion)

Plugin available in JetBrains Marketplace:

• Search "Expanse HPC" in Settings → Plugins
• Provides YAML schema validation and run configurations

note

IDE extensions and some CI integrations are under development. Check back for the latest availability.