EIC containers

89.6% of first-parent commits in 12 months came from PRs and 93.3% of merged PRs were reviewed, under an active ruleset requiring one approval, with the eic organization PR template applying; about 37 commits were pushed directly through the ruleset's always-bypass team, so not nearly all changes arrive through PRs.

Gaps to the next level

• The "Default" ruleset gives one team always-bypass, and about 10% of default-branch commits in 12 months bypassed PRs.
• No CODEOWNERS file.

Actions

• medium S Change the bypass team in the "Default" ruleset to pull_request bypass mode so that all changes go through PRs.
• medium S Add .github/CODEOWNERS naming at least two owners for spack-environment/, containers/ and .github/workflows/.

build-push.yml builds the base, eic_ci and eic_xl images for amd64, amd64_v3 and arm64 on every PR and push and runs npsim/EICrecon jobs in the built image, the eicweb pipeline builds every other flavor (cuda, tf, dbg, jl, prod, cvmfs) and triggers the detector and physics benchmarks, and the ruleset requires the eicweb status and the four manifest jobs; 96% of default-branch runs succeeded.

Tests are end-to-end only: npsim/EICrecon runs, a user Spack environment build and the benchmarks, all against the eic_ci image; the eic_xl, cuda, tf, dbg, jl and prod images are only built, and the build scripts have no tests.

Gaps to the next level

• No test exercises the eic_xl image that eic-shell installs by default, or the cuda, tf, dbg, jl and prod images.
• The capybara comparisons with the previous master artifacts are reported in a PR comment but never fail the job.
• scripts/build-*.sh, scripts/resolve_git_ref and scripts/check_image_size have no tests.

Actions

• medium S Add a smoke-test job per image flavor that runs eic-info and imports key Python modules (ROOT, podio, edm4eic, acts) inside each pipeline-tagged image.
• medium S Add the eic_xl image to the npsim/EICrecon job matrix in .github/workflows/build-push.yml.

pre-commit.ci runs whitespace and end-of-file fixers, check-yaml, actionlint and shellcheck (--severity=warning) on every PR, and all Dockerfiles set #check=error=true; hadolint is skipped on pre-commit.ci and excludes both main Dockerfiles, and pre-commit.ci is not a required check.

Gaps to the next level

• hadolint never runs in CI and excludes containers/debian/Dockerfile and containers/eic/Dockerfile.
• containers/debian/bashrc is excluded from shellcheck, and pre-commit.ci is not a required status check.

Actions

• medium S Add pre-commit.ci - pr to the required status checks of the "Default" ruleset.
• medium S Add a CI step that runs docker buildx build --check on both main Dockerfiles, replacing the skipped hadolint hook.

Images are built from multi-stage Dockerfiles through scripts/build-base.sh and scripts/build-eic.sh, with versions and variants kept in Spack environment files and pinned version scripts; the GitHub Actions and GitLab pipelines duplicate job logic, and version overrides are applied with sed on marker comments.

Gaps to the next level

• Build logic is maintained twice (build-push.yml and .gitlab-ci.yml), and the npsim/EICrecon jobs are copy-pasted four times.
• The image runtime interface (environment variables, profile.d scripts, eic-info, tag scheme) is not documented as a stable interface.

Actions

• medium S Document the image runtime interface (tags, environment variables, /etc/eic_info, profile.d hooks) in docs/image-interface.md.
• low M Move the duplicated npsim/EICrecon job steps in build-push.yml into one reusable workflow.

The README only links eic-shell; the hosted docs give prerequisites, local build commands, build options and troubleshooting, but the quick start pulls ghcr.io/eic/eic_xl:latest and build-eic.sh falls back to :latest, a tag that does not exist on ghcr.io.

Gaps to the next level

• docker pull ghcr.io/eic/eic_xl:latest fails: ghcr.io has nightly, master and <version>-stable tags but no latest.
• The README itself has no usage or build instructions, and the docs list 3 of the 12 image flavors.

Actions

• high S Replace :latest with :nightly and a <version>-stable example in docs/README.md and in the fallback of scripts/build-eic.sh.
• medium S Add a "Using the images" section to README.md linking the docs site and listing the image flavors and tag scheme.

docs/architecture.md, docs/build-pipeline.md and docs/spack-environment.md describe the build tracks, caches and environments with diagrams, build-script options and build arguments are documented, and the Docsify site is deployed by CI; parts are stale.

Gaps to the next level

• docs/architecture.md and docs/building-locally.md name buildcache spack-v2025.07.0; the pinned spack-packages is v2026.06.0.
• The GitLab pipeline, which builds most flavors and runs the benchmarks, is described only in AGENTS.md.

Actions

• medium S Update the buildcache references and image table in docs/ and add a page describing the eicweb GitLab pipeline and benchmark triggers.

There is no CONTRIBUTING.md, but AGENTS.md (addressed to coding agents) covers local builds, coding conventions, validation steps, commit format and PR rules, and the eic organization PR and issue templates apply; review expectations are one line and no newcomer issues are labeled.

Gaps to the next level

• Contributor guidance is in a file addressed to Copilot agents and is not linked from README.md.
• No issue carries the good first issue label; no devcontainer or documented ready-made development environment.

Actions

• medium S Add CONTRIBUTING.md (linked from README.md) with the review expectations, how to propose new packages or flavors, and the local build workflow.
• low S Label at least three open issues (for example

Median first response is 1.84 days and 1 of 7 open issues is older than a year, but no issue opened in 12 months was labeled, there are no milestones, and 26.1% of new issues received no response.

Gaps to the next level

• No issue triage; 0% of new issues labeled, no milestones or project board.
• 16 of 30 open PRs are older than 90 days.

Actions

• medium S Apply the existing bug/enhancement/question labels to every new issue and document the triage practice in CONTRIBUTING.md.
• low S Close or rebase the 16 PRs older than 90 days.

10 authors from 4 e-mail domains committed in 24 months with 5 new authors in 12 months, but no merged PR in 12 months came from outside the maintainer group.

Gaps to the next level

• No external PRs merged in 12 months.

Actions

• medium S Invite package requests as PRs to spack-environment/ from ePIC working groups and document how in CONTRIBUTING.md.

One author wrote 69.7% of commits in 24 months (bus factor 1), while 8 people reviewed and 3 merged PRs in 12 months; no CODEOWNERS or maintainer list exists.

Gaps to the next level

• Bus factor (50%) is 1.
• No CODEOWNERS or maintainer list.

Actions

• high S Add .github/CODEOWNERS with two owners per directory and document the release-tagging and backport procedure in docs/releasing.md.

Changes are discussed in public PRs, but neither the README, the docs nor a CODEOWNERS file names maintainers, and there is no decision process, roadmap or milestone.

Gaps to the next level

• No maintainers named and no decision process or path to maintainership.
• Requirements for which packages ship in eic-shell are not documented.

Actions

• high S Add GOVERNANCE.md naming the maintainers, the owning ePIC body, how package additions are decided, and how to become a maintainer.

The eic organization issue-template configuration links the ePIC Mattermost and weekly Indico meetings and the docs point to GitHub issues, but no code of conduct applies at repository or organization level.

Gaps to the next level

• No code of conduct with a reporting contact.

Actions

• high S Add CODE_OF_CONDUCT.md to eic/.github (or link the collaboration code) with a reporting contact.

The project's product is the eic-shell image set: every release tag is built and published as OCI images (Docker Hub eicweb/eic_xl:26.10.0-stable, ghcr.io) and distributed through OSG CVMFS, which the eic-shell installer uses; there is no package recipe, which does not apply to an image build.

42 tags in 24 months follow vYY.MM.P-stable, and the 15 GitHub releases since January 2026 have generated notes, but the version scheme is not documented, the 2025 tags have no release notes, and there is no changelog.

Gaps to the next level

• The CalVer scheme (vYY.MM.P-stable, release branches vYY.MM-stable) is not documented.
• Tags before 2026 have no release notes; no changelog flags breaking changes.

Actions

• medium S Document the version scheme, release branches and backport labels in README.md.

Spack, spack-packages, key4hep-spack and eic-spack are pinned to tags or SHAs, packages.yaml pins versions with require, Dependabot covers GitHub Actions and literal Docker FROM lines, and a nightly workflow opens eic-spack bump PRs; there is no SECURITY.md.

Gaps to the next level

• No SECURITY.md or vulnerability reporting route for images used across EIC.
• Base images set in CI configuration (debian:trixie-slim, nvidia/cuda) are not monitored by Dependabot.

Actions

• medium S Add SECURITY.md naming a private vulnerability reporting route and enable GitHub private vulnerability reporting.

The environment is defined by pinned Spack environments and Dockerfiles, each release tag yields immutable tagged images, CI runs npsim/EICrecon with fixed seeds inside the pipeline-built image, and each image records the Spack report and full package/variant list in /etc/eic_info.

CI builds amd64, amd64_v3 and arm64 images and runs npsim/EICrecon on amd64 and arm64 with cross-architecture capybara comparisons, the base image ships GCC and Clang, CUDA images are built, and the images run unmodified from OSG CVMFS through eic-shell and eic/run-cvmfs-osg-eic-shell.

The images assemble EIC-supported components from eic-spack, key4hep-spack and Spack recipes without parallel implementations, and the project provides the environment that EICrecon, epic and other EIC repositories build and test in.

Not applicable: The project builds container images and reads or writes no physics or detector data itself; its CI only runs other components (npsim, EICrecon).

Build and distribution infrastructure with no physics I/O of its own.

The project builds the eic-shell images and every PR tests the pipeline-built images: npsim/EICrecon jobs on the default build and the detector and physics benchmarks on both the default (pinned versions) and nightly builds; using the images is documented.

The pins in packages.yaml define the current eic-shell (EICrecon 1.42.0, epic 26.10.0, DD4hep 1.38, ROOT 6.40.04) and eic-spack is bumped nightly, but npsim 1.9.0 (2026-09-08) was not adopted in v26.10.0-stable and ACTS stays at 46.8.1 after 47.0.0 (2026-07-14) and 48.0.0.

Gaps to the next level

• npsim 1.9.0 was not adopted within one monthly release cycle.
• ACTS is pinned two major versions behind upstream with no documented reason.

Actions

• medium S Bump npsim to 1.9.0 in spack-environment/packages.yaml and record the reason for the ACTS 46.8.1 pin in a comment next to it.

The repository has no LICENSE file and GitHub detects no license; only an OCI image label in containers/debian/Dockerfile declares GPL-3.0-or-later.

Gaps to the next level

• No license file grants rights to the repository content.

Actions

• high S Add a LICENSE file with the GPL-3.0-or-later text that the image label already declares (or another chosen OSI license) so GitHub detects it.

No CITATION.cff, .zenodo.json, codemeta or DOI exists.

Gaps to the next level

• No citation information.

Actions

• high S Add CITATION.cff and enable the Zenodo-GitHub integration so each -stable release gets a DOI.

The images are eic-shell: the eic-shell installer and eic/run-cvmfs-osg-eic-shell use them, EICrecon and epic CI run in them, and EICrecon and epic pipelines trigger container builds on eicweb.

The image label names "Electron-Ion Collider Software Working Groups" with a mailing-list contact as authors and the docs link the organization for support, but no document assigns maintenance to a named ePIC body or acknowledges institutional support.

Gaps to the next level

• No owning ePIC body, maintainer institutions or funding stated in README or docs.

Actions

• high S State in README.md the ePIC computing body that owns eic-shell, the maintainers' institutions and any funding acknowledgement.