base-pipeline¶

The foundational component that provides orchestration templates and machine availability checks for RADIUSS Shared CI pipelines.

Purpose¶

The base-pipeline component is required for all RADIUSS Shared CI setups. It provides:

Orchestration Templates: Job templates for child pipeline triggers
Machine Check Templates: Templates checking machine availability and reporting status
Customization Hooks: Base templates for project-specific customization
Machine Rules: Templates that define machine-specific behavior

This component does NOT define stages (you must define them yourself) to allow customization.

When to Use¶

Always. Every RADIUSS Shared CI pipeline must include base-pipeline.

Include it first, before any machine or utility components:

include:
  # Always include base-pipeline first
  - component: $CI_SERVER_FQDN/radiuss/radiuss-shared-ci/base-pipeline@v2026.02.2
    inputs:
      github_project_name: "my-project"
      github_project_org: "LLNL"
      github_token: $GITHUB_STATUS_TOKEN

  # Then other components
  - component: .../dane-pipeline@v2026.02.2
    inputs: { ... }

Inputs¶

Input	Type	Required	Description
`github_project_name`	string	Yes	GitHub repository name (e.g., “RAJA”, “Umpire”)
`github_project_org`	string	Yes	GitHub organization name (e.g., “LLNL”)
`github_token`	string	No	GitHub personal access token for status updates. If not provided, status reporting will be skipped. Set as CI/CD variable in GitLab UI.

Exported Templates¶

The component exports several job templates you can extend:

.machine-check¶

Purpose: Template for machine availability check jobs.

Usage: Create machine check jobs by extending this template with machine-specific rules.

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

What it does:

Queries Lorenz status file for machine availability
Reports status to GitHub (if token provided)
Fails if machine is down (preventing child pipeline from starting)
Uses ASSOCIATED_CHILD_PIPELINE variable to set correct GitHub status context

Key Variables:

CI_MACHINE: Set by machine rule (e.g., .dane sets it to “dane”)
ASSOCIATED_CHILD_PIPELINE: Name of the child pipeline job (e.g., “dane-build-and-test”)

Important

As of v2026.02.0, ASSOCIATED_CHILD_PIPELINE is required. This ensures machine check status uses the same GitHub context as the child pipeline, allowing failing checks to be overridden when the machine comes back up.

.build-and-test¶

Purpose: Template for child pipeline trigger jobs.

Usage: Create pipeline trigger jobs that spawn machine-specific child pipelines.

dane-build-and-test:
  needs: [dane-up-check]
  extends: [.dane, .build-and-test]
  trigger:
    include:
      - component: .../dane-pipeline@v2026.02.2
        inputs: { ... }
      - local: '.gitlab/jobs/dane.yml'

What it does:

Uses strategy: depend to wait for child completion
Forwards pipeline variables to child
Sets appropriate stage (build-and-test)

.custom_job¶

Purpose: Base customization template for all build/test jobs.

Usage: Override, for example in .gitlab/custom-jobs.yml, and include in each child pipeline trigger definition to add project-specific setup.

# In .gitlab/custom-jobs.yml
.custom_job:
  before_script:
    - echo "Project-specific setup"
    - module load my-dependencies
  artifacts:
    reports:
      junit: junit.xml

What it does:

Provides an empty template that all job templates extend
Allows to define project specific job configuration in one place
Applies to all build/test jobs across all machines (if included accordingly)

.custom_perf¶

Purpose: Base customization template for performance jobs.

Usage: Override, for example in your .gitlab/custom-jobs.yml, and include in performance pipeline trigger for performance-specific setup.

# In .gitlab/custom-jobs.yml
.custom_perf:
  before_script:
    - echo "Performance environment setup"
    - export PERF_FLAGS="..."

# In .gitlab-ci.yml
performance-measurements:
  extends: [.performance-measurements]
  trigger:
    include:
      - component: .../performance-pipeline@v2026.02.2
        inputs: { ... }
      - local: '.gitlab/custom-jobs.yml'
      - local: '.gitlab/jobs/performances.yml'

What it does:

Similar to .custom_job but for performance pipeline
Extends to all performance jobs (if included accordingly)
Separate from .custom_job to allow different configurations

Machine-Specific Rules¶

The component also exports machine-specific rule templates (not typically used directly):

.dane - Sets CI_MACHINE: "dane" and machine-specific rules
.matrix - Sets CI_MACHINE: "matrix"
.corona - Sets CI_MACHINE: "corona"
.tioga - Sets CI_MACHINE: "tioga"
.tuolumne - Sets CI_MACHINE: "tuolumne"

These are used with .machine-check and .build-and-test templates.

Variables Set¶

The component sets several internal variables:

Variable	Description
`RSCI_GITHUB_PROJECT_NAME`	Internal: GitHub project name from input
`RSCI_GITHUB_PROJECT_ORG`	Internal: GitHub organization from input
`RSCI_GITHUB_TOKEN`	Internal: GitHub token from input

Note

RSCI_ prefix was added in v2026.02.1 to avoid collisions with GitLab global variables. You don’t need to use these directly - they’re for internal component use.

The component also includes ID token configuration from lc-templates/id_tokens.

Examples¶

Minimal Example¶

Simplest possible setup with base-pipeline:

stages:
  - prerequisites
  - build-and-test

variables:
  GITHUB_PROJECT_NAME: "my-project"
  GITHUB_PROJECT_ORG: "LLNL"

include:
  - component: $CI_SERVER_FQDN/radiuss/radiuss-shared-ci/base-pipeline@v2026.02.2
    inputs:
      github_project_name: $GITHUB_PROJECT_NAME
      github_project_org: $GITHUB_PROJECT_ORG
      github_token: $GITHUB_STATUS_TOKEN

Typical Example¶

Standard setup with machine checks and child pipelines:

stages:
  - prerequisites
  - build-and-test

variables:
  GITHUB_PROJECT_NAME: "my-project"
  GITHUB_PROJECT_ORG: "LLNL"
  JOB_CMD:
    value: "./scripts/build-and-test.sh"
    expand: false

include:
  - component: $CI_SERVER_FQDN/radiuss/radiuss-shared-ci/base-pipeline@v2026.02.2
    inputs:
      github_project_name: $GITHUB_PROJECT_NAME
      github_project_org: $GITHUB_PROJECT_ORG
      github_token: $GITHUB_STATUS_TOKEN

# Machine availability check
dane-up-check:
  extends: [.dane, .machine-check]
  variables:
    ASSOCIATED_CHILD_PIPELINE: "dane-build-and-test"

# Child pipeline trigger
dane-build-and-test:
  needs: [dane-up-check]
  extends: [.dane, .build-and-test]
  trigger:
    include:
      - component: $CI_SERVER_FQDN/radiuss/radiuss-shared-ci/dane-pipeline@v2026.02.2
        inputs:
          job_cmd: $JOB_CMD
          shared_alloc: "--nodes=1 --exclusive --time=30"
          job_alloc: "--nodes=1"
          github_project_name: $GITHUB_PROJECT_NAME
          github_project_org: $GITHUB_PROJECT_ORG
      - local: '.gitlab/jobs/dane.yml'

Advanced Example with Custom Jobs¶

Using custom job templates:

# .gitlab-ci.yml
include:
  - component: .../base-pipeline@v2026.02.2
    inputs: { ... }

# In child pipeline trigger
dane-build-and-test:
  trigger:
    include:
      - component: .../dane-pipeline@v2026.02.2
      - local: '.gitlab/custom-jobs.yml'  # Your customizations
      - local: '.gitlab/jobs/dane.yml'

# .gitlab/custom-jobs.yml
.custom_job:
  before_script:
    - echo "Setting up environment"
    - export MY_VAR="value"
  after_script:
    - echo "Cleaning up"
  artifacts:
    reports:
      junit: build/junit.xml
    paths:
      - build/logs/

Common Issues¶

Missing ASSOCIATED_CHILD_PIPELINE¶

Error: Machine check job fails with “ASSOCIATED_CHILD_PIPELINE variable not set”

Solution: Add the variable to your machine check job:

dane-up-check:
  extends: [.dane, .machine-check]
  variables:
    ASSOCIATED_CHILD_PIPELINE: "dane-build-and-test"  # Add this

Why: This ensures the machine check and child pipeline share the same GitHub status context.

GitHub Status Not Showing¶

Symptom: Pipeline runs but no status appears on GitHub PR/commit

Possible causes:

Token not provided: Add github_token input
Token expired: Regenerate token in GitHub settings (max 30 days expiration per LLNL policy)
Wrong permissions: Token needs repo:status scope
Token not in GitLab: Set GITHUB_STATUS_TOKEN variable in GitLab CI/CD settings
Wrong project name: Verify github_project_name matches GitHub repo name

Stages Not Defined¶

Error: “Stage ‘prerequisites’ not defined” or similar

Solution: The component does NOT define stages. Add them to your .gitlab-ci.yml:

stages:
  - prerequisites      # Required
  - build-and-test     # Required
  - performance-measurements  # If using performance pipeline

Why: Allowing you to define stages enables adding custom stages without conflicts.

Template Not Found¶

Error: “Job extends template that doesn’t exist: .machine-check”

Solution: Ensure base-pipeline is included in your parent pipeline (not child pipeline).

# In .gitlab-ci.yml (parent pipeline)
include:
  - component: .../base-pipeline@v2026.02.2  # Include here

base-pipeline¶

Purpose¶

When to Use¶

Inputs¶

Exported Templates¶

.machine-check¶

.build-and-test¶

.custom_job¶

.custom_perf¶

Machine-Specific Rules¶

Variables Set¶

Examples¶

Minimal Example¶

Typical Example¶

Advanced Example with Custom Jobs¶

Common Issues¶

Missing ASSOCIATED_CHILD_PIPELINE¶

GitHub Status Not Showing¶

Stages Not Defined¶

Template Not Found¶

See Also¶