Artifacts, Reports, Retention, Dependencies, needs:artifacts, and Cross-Job Data Flow: Configuration, Design Choices, and Tradeoffs

1. Artifact design is interface design

When one job produces files for another job, the producer has an interface. Its contract includes file names/paths, format, source identity, digest, sensitivity, retention window, access assumptions, and who is allowed to consume it. A broad artifacts: paths: [.] is not a convenient interface—it is an undocumented export of the workspace.

Design the artifact contract so a reviewer can answer: what was produced, by which source/job, for whom, for how long, and how do we know it is the same object?

2. Generic artifacts versus typed reports

Do not deploy a JUnit XML simply because it is an artifact. Conversely, a deployable binary can have a separate test report that proves validation without being the deployable object itself.

3. Short versus long retention

Retention should match the consumer horizon. A two-hour debug trace may not need months of storage. A release candidate needed for a week-long approval window must not expire after one hour. Compliance evidence may need a dedicated retention strategy beyond ordinary CI artifact storage.

4. Broad paths versus allowlisted outputs

Narrow paths are both a security control and a maintainability control. A workspace may contain source, temporary files, downloaded dependencies, debug logs, generated credentials, and tool caches. Export only the files the next consumer genuinely needs.

artifacts:
  paths:
    - dist/app.bin
    - evidence/app.sha256
    - evidence/provenance.txt

This is preferable to archiving the entire project directory. If a new required file is introduced, update the interface deliberately and review its sensitivity.

5. Access is a separate authorization decision

artifacts:access controls UI/API download eligibility. Current documented values are all, developer, maintainer, and none. The maintainer option is a newer value, so older GitLab installations require compatibility review.

Do not assume this setting blocks every CI-to-CI retrieval route. Job-token authorization and project CI/CD visibility are separate controls. For sensitive-but-nonsecret evidence, combine narrow paths, suitable access, short retention, and project membership policy.

6. Default fetching, dependencies, or needs:artifacts?

7. Cross-job transfer is not the same as durable promotion

Job artifacts are excellent same-pipeline outputs and evidence, but release distribution often needs a longer-lived, versioned object with repository semantics. For a production package or container, promote the exact verified artifact/digest into the appropriate package/container registry or release process rather than relying indefinitely on a branch’s latest job artifact.

That promotion is a side effect and belongs to later course chapters. The Chapter 10 rule is simpler: build once, preserve identity, and never rebuild silently merely because a later consumer cannot find the original output.

8. Download by exact job versus “latest by ref”

The Artifacts API can target a specific job ID or resolve an artifact by job name + ref from the latest successful pipeline. Those are different identity guarantees. For incident response or release evidence, prefer exact job/pipeline identity when you already know it. A ref such as main moves over time.

Current API behavior also supports direct report downloads by job ID/file type. That capability should not encourage scripts to select ambiguous “latest” artifacts for deployment.

9. Worked scenario: four outputs, four different contracts

A service pipeline emits: a Linux binary, a JUnit report, a short debug trace, and dependency cache data. Choose separately:

The decision is not “everything is an artifact.” It is “each data type gets the state system that matches its correctness and lifecycle role.”

10. Decision checklist

Knowledge check

Official references and version notes

Documentation verification date: 2026-09-11. Artifact/report retention, access, API behavior, and cross-job transfer semantics are version-sensitive; verify the deployed GitLab version for Self-Managed/Dedicated installations.

• Job artifacts — creation, paths, expiry, download, artifact browsing, access, latest-success retention, and default previous-stage fetching.
• CI/CD YAML syntax reference — authoritative artifacts, artifacts:access, artifacts:expire_in, dependencies, and needs:artifacts semantics.
• CI/CD artifacts report types — typed report ingestion and report-specific GitLab UI behavior.
• Unit test reports — JUnit report configuration and display.
• Job Artifacts API — artifact archive/file/report download, keep, and delete operations with exact job identity.
• Troubleshooting job artifacts — artifact expiry and upload/report problems.
• Caching in GitLab CI/CD — artifact-versus-cache boundary.
• Make jobs start earlier with needs — DAG dependency edges and artifact-transfer interaction.