Gitlab documentation

[TerrenceMcGuinness-NOAA]

Add Comprehensive GitLab CI/CD Pipeline Documentation

Summary

Adds a new ReadTheDocs page documenting the full GitLab CI/CD pipeline infrastructure for global-workflow. This fills a significant documentation gap — until now, the mirroring setup, pipeline architecture, runner deployment, and maintenance procedures were only known through tribal knowledge and inline code comments.

Motivation

The CI/CD infrastructure spans multiple GitLab instances, five RDHPCS platforms, and a GitHub Actions bridge, with configuration spread across ~15 files. New developers and maintainers had no single reference to understand how the pieces fit together. This documentation provides that reference.

What's Included

New Files

File	Description
docs/source/ci_cd_pipeline.rst	~900-line comprehensive RST document
docs/source/_static/ci_cd_architecture.svg	Architecture diagram (SVG)

Modified Files

File	Change
docs/source/index.rst	Added ci_cd_pipeline to the toctree (after testing)

Documentation Sections

The RST document covers the following topics in depth:

1. Overview — Why GitLab CI/CD is used alongside GitHub; key design principles
2. Repository Mirroring — Two-stage mirror chain:
   • Pull mirror (Licensed GitLab Premium) — pulls from GitHub (advanced feature requiring paid tier)
   • Push mirror (Licensed → VLab Community) — propagates to the community instance where CI/CD actually runs
   • Mirror chain summary with ASCII diagram
3. Pipeline Architecture — Four stages (Build → Setup → Run → Finalize), two modalities (PR Cases via Rocoto, CTests via CMake), per-host test matrices for all 5 platforms, pipeline variables reference
4. GitHub Actions Integration — How trigger-gitlab-pipelines.yml bridges GitHub PRs to GitLab pipelines, including secrets, label lifecycle (CI-Ready-to-Run → CI-{host}-Running → CI-{host}-{Pass/Fail}), and manual trigger instructions
5. Nightly Operations — Scheduled pipelines, develop branch testing, badge generation
6. GitLab Runner Setup — launch_gitlab_runner.sh usage (register/run/unregister), platform-specific configurations for all 5 hosts, directory layout, maintenance procedures
7. Pipeline Execution Details — ci_utils.sh functions, run_check_gitlab_ci.sh experiment monitoring, timeout handling
8. Adding New Hosts — Step-by-step guide for onboarding a new RDHPCS platform
9. File Reference — Complete table of all CI/CD-related files with locations and purposes
10. Troubleshooting — Common failure scenarios and resolutions

Architecture Diagram

The SVG diagram visually shows:

• The three-repository mirror chain (GitHub → Licensed GitLab → VLab Community GitLab)
• GitHub Actions API trigger path (GitHub → VLab Community)
• Feedback loop (labels, comments, badges back to GitHub)
• Four pipeline stages with descriptions
• All five RDHPCS runner platforms with test case counts and tags
• Key configuration files

Important architectural note: The Licensed GitLab instance is used only for mirroring (pull from GitHub, push to VLab). The VLab Community GitLab instance is where the CI/CD pipelines actually execute and where runners are registered.

ReadTheDocs Preview

https://global-workflow--4576.org.readthedocs.build/en/4576/ci_cd_pipeline.html

Notes for Reviewers

• The document references actual file paths, variable names, and script functions from the codebase — please verify these are still accurate
• Test case counts per host (Hera: 17, Gaea C6: 15, Orion: 8, Hercules: 10, Ursa: 17) were sourced from gitlab-ci-hosts.yml — confirm these are current
• The mirroring description reflects that pull mirroring requires GitLab Premium and the community VLab instance runs the actual pipelines/runners
• No functional code changes — documentation only

[Copilot]

Pull request overview

This PR adds comprehensive documentation for the GitLab CI/CD pipeline infrastructure used by the global-workflow project. The documentation explains the repository mirroring strategy between GitHub and GitLab, pipeline architecture, runner deployment on RDHPCS systems, and maintenance procedures. It includes a detailed SVG architecture diagram that visually illustrates the CI/CD flow from GitHub through GitLab to the HPC runners.

Changes:

• Added comprehensive GitLab CI/CD pipeline documentation covering all aspects of the CI infrastructure
• Created an SVG architecture diagram showing repository mirroring and pipeline execution flow
• Updated documentation index to include the new CI/CD pipeline documentation

Reviewed changes

Copilot reviewed 2 out of 3 changed files in this pull request and generated no comments.

File	Description
docs/source/index.rst	Added ci_cd_pipeline.rst to the documentation table of contents
docs/source/ci_cd_pipeline.rst	Comprehensive 877-line documentation covering repository mirroring, pipeline architecture, runner setup, execution details, and troubleshooting
docs/source/_static/ci_cd_architecture.svg	Professional SVG diagram (229 lines) illustrating the complete CI/CD architecture with GitHub, GitLab instances, pipeline stages, and RDHPCS runners

[DavidHuber-NOAA]

There's a lot of extraneous information in all of this documentation. Let's aim to keep this to what's important and not be too redundant.

Suggest removing this.

Suggested change

	Key Design Principles
	=====================
	- **GitHub is authoritative**: All development happens on GitHub
	(``https://github.com/NOAA-EMC/global-workflow``). GitLab is used solely as
	a CI execution platform.
	- **Two-tier mirroring**: A licensed GitLab instance performs the pull mirror from
	GitHub, and subsequently push mirrors to the NOAA community GitLab instance.
	- **HPC-native testing**: Runners execute directly on the target HPC nodes,
	ensuring tests build and run against the real Spack-Stack software environment.
	- **Multi-modal pipelines**: The system supports both comprehensive end-to-end
	experiment cases and fast CTest-based functional checks.
	- **GitHub feedback loop**: Pipeline results flow back to GitHub through PR labels,
	PR comments (including error log gists), and status badges.

[TerrenceMcGuinness-NOAA]

Ok, will refine.

[DavidHuber-NOAA]

I think this all can just be summarized. No need for the details here. Just

• mirror from github to VLab gitlab
• mirror from VLab gitlab to public gitlab

is enough. Having the URLs for all of these would be useful, but beyond that is extraneous.

[DavidHuber-NOAA]

This is way to jargony. We don't need to know the internals. Please put this into laymen's terms.

[DavidHuber-NOAA]

This doesn't belong here. This is too specific and would be a bear trying to keep updated. Just paths to where this is controlled is needed.

[DavidHuber-NOAA]

Please move this after the GitHub Actions Integration section.

[DavidHuber-NOAA]

Why is this important? If it isn't, please remove. If it is important, can you please further describe what concurrency is?

[DavidHuber-NOAA]

Not necessary.

Suggested change

	└── Jenkins/ # Legacy Jenkins directories
	├── agent/
	└── workspace/

[DavidHuber-NOAA]

Important to note that this needs to be done on the same head node that it was initially launched on.

[DavidHuber-NOAA]

Please move this to the end.