Developer How-To

Step-by-step procedures for common development tasks.

Add a New Machine

Complete procedure to add support for a new machine.

Step 1: Create Component

  1. Create component directory:

    mkdir -p templates/newmachine-pipeline

  2. Choose template base:

    • For SLURM machines: Copy templates/dane-pipeline/template.yml

    • For Flux machines: Copy templates/tioga-pipeline/template.yml

  3. Create templates/newmachine-pipeline/template.yml:

    Replace all instances of source machine name with new machine name:

    # Example: If copying from dane
sed 's/dane/newmachine/g; s/DANE/NEWMACHINE/g' \
  templates/dane-pipeline/template.yml > \
  templates/newmachine-pipeline/template.yml

  4. Update machine-specific details:

    • Runner tags

    • Scheduler commands (if different)

    • Default allocation parameters

    • Environment setup

Step 2: Update Base Pipeline

Add machine rules to templates/base-pipeline/template.yml:

# Add after other machine rules
.newmachine:
  rules:
    - if: '$ON_NEWMACHINE == "OFF"'
      when: never
    - when: on_success

Step 3: Create Legacy Implementation

For backward compatibility:

  1. Create pipelines/newmachine.yml by copying similar machine

  2. Replace machine names throughout

  3. Test legacy include syntax works

Step 4: Update Customization Templates

  1. Add to customization/subscribed-pipelines.yml:

    # NewMachine
newmachine-up-check:
  extends: [.newmachine, .machine-check]
  variables:
    ASSOCIATED_CHILD_PIPELINE: "newmachine-build-and-test"

newmachine-build-and-test:
  needs: [newmachine-up-check]
  extends: [.newmachine, .build-and-test]
  variables:
    CI_MACHINE: "newmachine"
  trigger:
    include:
      - local: '.gitlab/custom-jobs.yml'
      - project: 'radiuss/radiuss-shared-ci'
        ref: '${SHARED_CI_REF}'
        file: 'pipelines/newmachine.yml'
      - local: '.gitlab/jobs/newmachine.yml'

  2. Add to customization/custom-jobs-and-variables.yml:

    # NewMachine allocation parameters
NEWMACHINE_SHARED_ALLOC: "--nodes=1 --time=30"
NEWMACHINE_JOB_ALLOC: "--nodes=1"

Step 5: Update Documentation

  1. Update README.md at repository root:

    Add subsection under ## Components:

    ### NewMachine Pipeline

Provides CI templates for NewMachine (SLURM, Intel CPUs).

**Usage:**

```yaml
include:
  - component: $CI_SERVER_FQDN/radiuss/radiuss-shared-ci/newmachine-pipeline@v2026.02.2
    inputs:
      job_cmd: "./build-and-test.sh"
```

[View component inputs →](https://lc.llnl.gov/gitlab/radiuss/radiuss-shared-ci/-/components/newmachine-pipeline)

    Do not list inputs - they appear automatically on component page

  2. Add to docs/sphinx/reference/components/machine-pipelines.rst:

    Add section describing the new machine with:

    • Hardware description (CPU/GPU)

    • Scheduler type

    • Common allocation parameters

    • Example usage

  3. Update machine lists in:

    • docs/sphinx/getting_started/choosing-your-path.rst

    • docs/sphinx/user_guide/quick-reference.rst

    • docs/sphinx/getting_started/five-minute-setup.rst (if appropriate)

  4. Add ON_NEWMACHINE to variable tables

Step 6: Test Implementation

  1. Commit changes to development branch:

    git checkout -b add-newmachine-support
git add templates/newmachine-pipeline/ pipelines/newmachine.yml
git add customization/ examples/ docs/
git commit -m "Add NewMachine support"
git push origin add-newmachine-support

  2. Wait for GitHub to LC GitLab mirror sync (5-30 minutes)

  3. Test in project:

    include:
  - component: .../newmachine-pipeline@add-newmachine-support
    inputs:
      job_cmd: "./test.sh"
      shared_alloc: "--nodes=1"
      job_alloc: "--nodes=1"

  4. Verify:

    • Machine check executes

    • Jobs run successfully

    • Allocations work correctly

    • GitHub status reports

    • Reproducer prints correctly

Step 7: Submit Changes

  1. Update CHANGELOG.md:

    ## [Unreleased]

### Added
- NewMachine support (SLURM/Flux, CPU/GPU description)

  2. Open pull request on GitHub with:

    • Description of new machine

    • Hardware/scheduler details

    • Test results

    • Links to test pipeline runs

Add a Utility Component

Procedure for adding non-machine components (like draft-pr-filter).

Step 1: Create Component

  1. Create directory:

    mkdir -p templates/utility-feature-name

  2. Create templates/utility-feature-name/template.yml:

    spec:
  inputs:
    required_input:
      type: string
      description: "What this input does"
---
# Component implementation
feature-job:
  stage: prerequisites
  tags: [shell, oslic]
  script:
    - echo "Doing something with ${{ inputs.required_input }}"

Step 2: Add Documentation

  1. Add to docs/sphinx/reference/components/utility-components.rst

  2. Update README.md at repository root:

    Add subsection under ## Components with:

    • What the component does

    • YAML usage example

    • Link to published component (do not list inputs)

    Example:

    ### Utility: Feature Name

Brief description of what this utility does.

**Usage:**

```yaml
include:
  - component: $CI_SERVER_FQDN/radiuss/radiuss-shared-ci/utility-feature-name@v2026.02.2
    inputs:
      required_input: "value"
```

[View component inputs →](https://lc.llnl.gov/gitlab/radiuss/radiuss-shared-ci/-/components/utility-feature-name)

  3. Update examples if needed

Step 3: Test and Submit

  1. Test in development branch

  2. Update CHANGELOG.md

  3. Submit pull request

Update Component Version

Procedure for making version updates.

For Breaking Changes

  1. Update component spec:

    spec:
  inputs:
    new_required_input:  # New required input is breaking
      type: string

  2. Update legacy implementation to match

  3. Document in CHANGELOG.md:

    ### Breaking Changes
- Component now requires `new_required_input`

### Migration
```yaml
inputs:
  new_required_input: "value"  # Add this
```

  4. Update all examples and documentation

For Non-Breaking Changes

  1. Add optional inputs (with defaults):

    spec:
  inputs:
    new_optional_input:
      type: string
      default: "default_value"

  2. Update CHANGELOG.md under Added or Changed

  3. Update examples to show new functionality

Update Examples

When updating example files for new version.

Procedure

  1. Update version references in:

    • examples/example-gitlab-ci.yml

    • examples/example-custom-jobs.yml

    • examples/example-jobs-*.yml

  2. Find and replace:

    cd examples/
sed -i 's/@v2026.02.2/@v2026.03.0/g' *.yml

  3. Update customization/*.yml ref values:

    cd customization/
sed -i 's/v2026.02.2/v2026.03.0/g' *.yml

  4. Verify changes and test

Build Documentation

Procedure to build docs locally.

Setup

cd docs

# Create virtual environment (one time)
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Build

# Build documentation
sphinx-build -b html sphinx _build/html

# Open in browser
open _build/html/index.html

Rebuild After Changes

# Clean previous build
rm -rf _build

# Rebuild
sphinx-build -b html sphinx _build/html

Check for Warnings

Look for Sphinx warnings during build:

  • Broken cross-references

  • Missing files in toctree

  • Invalid RST syntax

Fix warnings before submitting changes.

Troubleshooting

For development issues, see Developer Troubleshooting.

Additional Resources