Artifacts, Reports, Retention, Dependencies, needs:artifacts, and Cross-Job Data Flow: Concepts, Architecture, and Mental Model

1. The practical problem: a successful job can still lose its output

Chapter 09 made job dependencies explicit. That graph answers when a consumer may run, but not automatically which files the consumer should receive or how long those files remain available. A runner workspace can disappear after a job, a Docker container can be destroyed, and a Kubernetes pod can be removed. If a file matters after the producing job, the pipeline needs an explicit retained-output contract.

GitLab job artifacts provide that contract for pipeline outputs and evidence. A producer selects paths or typed reports from its project workspace, GitLab stores them with the producing job, and later jobs or authorized users can retrieve them according to retention and access rules.

2. Mental model: workspace → selected outputs → retained evidence → verified consumer

Read the model from left to right. The producer begins with a checked-out source revision and temporary workspace. Its script creates files. The artifacts declaration selects only intended paths/reports. Runner uploads those outputs to GitLab, where the artifact record inherits producer identity and retention/access policy. A consumer then downloads through the pipeline transfer mechanism, verifies identity/digest, and uses the output.

            flowchart TD
              A[Source ref + exact SHA] --> B[Producer job workspace]
              B --> C[Selected artifacts: paths / reports]
              C --> D[GitLab artifact record
            producer job + pipeline + expiry/access]
              D --> E[Consumer download
            default / dependencies / needs:artifacts]
              E --> F[Digest + identity verification]
              F --> G[Review / test / package / deploy input]
          

The arrows are causal. If the producer did not create the path, upload fails or collects nothing. If the retention window expires, a later consumer may fail even though the original build was green. If the consumer rebuilds instead of downloading, it has created a different object whose equivalence must not be assumed.

3. Keep artifact state separate from every neighboring state

4. Generic artifact versus typed report

A generic artifact is primarily a retained file/archive. A typed report tells GitLab how to interpret a file for a feature such as test results, coverage, code quality, or security. The same underlying file can sometimes be listed in both artifacts:reports and artifacts:paths when you want GitLab-native ingestion and convenient browsing/download.

5. Three same-pipeline fetching models

Without an explicit restriction, jobs in later stages download artifacts from all earlier-stage jobs. This is convenient for small pipelines but can become ambiguous and wasteful. dependencies narrows which earlier-stage jobs provide artifacts while retaining normal stage scheduling. A job that uses needs no longer relies on that default previous-stage download model; its needs entries can specify whether each needed producer’s artifacts are fetched.

6. Give every artifact an evidence identity

A filename such as app.zip is not enough. Two pipelines can produce files with the same name. The minimum evidence tuple is producer project + pipeline ID + job ID/name + exact source SHA + artifact logical name/path + cryptographic digest + retention/access assumptions.

build_app:
  stage: build
  script:
    - mkdir -p dist evidence
    - printf 'release-candidate:%s\n' "$CI_COMMIT_SHA" > dist/app.txt
    - sha256sum dist/app.txt > evidence/app.sha256
    - printf 'pipeline=%s\njob=%s\nsha=%s\n' "$CI_PIPELINE_ID" "$CI_JOB_ID" "$CI_COMMIT_SHA" > evidence/producer.txt
  artifacts:
    name: "app-$CI_PIPELINE_ID-$CI_JOB_ID"
    paths:
      - dist/app.txt
      - evidence/app.sha256
      - evidence/producer.txt
    expire_in: 7 days

The example prints identifiers, not secrets. It records enough provenance for a later job to prove which bytes it received.

7. Retention is part of correctness

artifacts:expire_in starts its retention clock when GitLab stores the artifact. If omitted, GitLab uses the instance-wide default. Current GitLab also normally keeps artifacts from the most recent successful pipeline for each ref even when an expire_in value exists, unless that keep-latest behavior is disabled. Therefore “expires in seven days” is not a universal statement about actual deletion time.

Retention should outlive every intended consumer: later pipeline stages, human review, deployment windows, incident investigation, compliance evidence, or rollback. Conversely, long retention of large or sensitive outputs has storage and exposure cost.

8. Access controls reduce exposure; they do not make artifacts a secret vault

artifacts:access controls who can download a job’s artifacts through the GitLab UI/API. Current values include all, developer, maintainer, and none. This control also applies to report artifacts, but it is not a substitute for preventing secrets from entering the artifact in the first place.

Job-token access has its own authorization model. A UI/API artifact access setting and CI job-token cross-project permissions are separate security states.

9. Read-only inspection before changing artifact flow

1. Record pipeline source, ref, and exact SHA.
2. Open the compiled configuration and identify every artifact producer and declared consumer.
3. Record producer job ID/status and the exact artifact paths/reports.
4. Inspect the job’s artifact metadata/UI and retention/access policy without deleting or keeping anything yet.
5. For a consumer, identify whether transfer is default, dependencies, or needs:artifacts.
6. Compare producer and consumer digests when the file is correctness-relevant.

10. Misconceptions to remove now

11. Micro-lab: predict the transfer before running

Given one build job that produces dist/app.txt and test/report.xml, predict the answer for each consumer:

• A later-stage job with no dependencies: which earlier artifacts does it fetch by default?
• A later-stage job with dependencies: [build_app]: what does it fetch?
• A DAG job with needs: [{job: build_app, artifacts: true}]: when can it start and what does it receive?
• A DAG job with the same need but artifacts: false: what control dependency remains and what data dependency disappears?

Do not execute yet. The goal is to separate ordering from transfer before syntax becomes habit.

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.