🖼️ See the drawing + lab 🏠 Course home 🌿 Branch on GitHub ✏️ View source

🖼️ आकृती आणि labThe drawing + lab पूर्ण पानावर उघडा ↗Open full page ↗

📎 धडा 05 — Artifacts आणि test reports: डेस्कांमध्ये काय प्रवास करते

📍 तुम्ही इथे आहात: 12 पैकी धडा 05 · मागे: lesson-04-cache-parallel-matrix · पुढे: lesson-06-secrets-oidc

📦 या ब्रँचमध्ये काय आहे

धडे 01–04, आणि डेस्क दुसऱ्या कोणाला देऊ शकते अशा दोन गोष्टी: माणूस वाचतो तो test report आणि नंतरच्या job ला लागणारे artifact. खऱ्या files:

.github/workflows/ci.yml — 📎 upload the report card step: if: always(), retention-days: 7
.github/workflows/ship.yml — build job image.tar.gz जपून ठेवतो; push job ती दुसऱ्या मशीनवर download करतो
app/package.json — npm run test:ci प्रगतिपुस्तक ज्यापासून बनते ते JUnit XML लिहिते
.circleci/config.yml, .gitlab-ci.yml, Jenkinsfile — तेच प्रगतिपुस्तक इतर तीन बोलींमध्ये

🧒 5 वर्षांच्या मुलाला समजावल्यासारखे

तपासणी डेस्कने ✅ तुमचा गृहपाठ तपासून संपवला. त्या डेस्कवरून दोन गोष्टी बाहेर पडतात.

पहिली, प्रगतिपुस्तक 📋: "3 तपासण्या, 3 पास". ते अशा ठिकाणी लावले जाते जिथे कोणीही वाचू शकेल — शिक्षिका, तुमचे पालक, पुढच्या मंगळवारी कोणती तपासणी बिघडली याचा विचार करणारे तुम्ही. CI मध्ये ती JUnit XML file असते. CircleCI, GitLab आणि Jenkins ती वाचून प्रत्येक test साठी एक ओळ असलेले table बनवतात; GitHub Actions ती download म्हणून ठेवते जी तुम्ही स्वतः उघडता.

दुसरी, पाकीट 📎: फोटोकॉपी डेस्क 🍱 तुमच्या गृहपाठाची प्रत काढतो आणि ती delivery डेस्ककडे द्यायची असते. पण तो डेस्क वेगळ्या खोलीत आहे — CI मध्ये प्रत्येक job नव्या मशीनवर उतरतो, म्हणून तुम्ही बनवलेले सगळे job संपताक्षणी नाहीसे होते. तुम्ही ते पाकिटात ठेवता, त्यावर नाव लिहिता, आणि run च्या कप्प्यात टाकता. पुढचा डेस्क ते नावाने उचलतो. ते पाकीट म्हणजे artifact.

आणि धडा 04 मधला तासलेल्या पेन्सिलींचा ड्रॉवर 🗄️? तो म्हणजे cache. शिपायाने ड्रॉवर रिकामा केला तर कोणालाच त्याची उणीव भासणार नाही — तुम्ही फक्त पुन्हा तासाल. पाकीट हरवणे म्हणजे deliverable हरवणे. तीच फळी, अगदी वेगळे नियम.

🗺️ आकृती

flowchart LR
    t["✅ test job<br/>node --test → test-results.xml"]
    rc["📋 report card<br/>artifact test-results-node22"]
    human["🧑‍🏫 a human downloads it<br/>gh run download"]
    b["🍱 build job<br/>docker save → image.tar.gz"]
    env["📎 envelope<br/>artifact image"]
    p["🚚 push job<br/>another machine, docker load"]
    t -->|"1 upload, even on failure"| rc
    rc -->|"2 read later"| human
    b -->|"3 upload"| env
    env -->|"4 download by name"| p

❓ काय

Artifact = या run चा output असलेली file (किंवा folder), जी CI system ठेवते म्हणजे माणूस किंवा नंतरचा job ती आणू शकेल. नाव असलेली, एका run शी बांधलेली, ठरावीक दिवस ठेवलेली.
Cache = पुढचा run पुन्हा बनवू शकेल अशा गोष्टीची copy, फक्त वेळ वाचवण्यासाठी ठेवलेली. तिच्या inputs च्या hash वरून key; कोणत्याही क्षणी काढून टाकली जाऊ शकते.
Test report = test run चा machine ला वाचता येणारा सारांश. JUnit XML हा सामान्य format आहे — तो Java जगात सुरू झाला आणि या कोर्समधली CI tools तो समजतात.
Retention = artifact किती काळ राहते. प्रगतिपुस्तकासाठी retention-days: 7, image च्या पाकिटासाठी retention-days: 1.
Jobs दरम्यान = एका run चे jobs सहसा वेगवेगळ्या runners वर उतरतात, म्हणून job A कडून job B कडे file देण्याचा भरवशाचा मार्ग म्हणजे A मध्ये upload, B मध्ये download.

🧠 पाकीट विरुद्ध ड्रॉवर

	📎 artifact	🗄️ cache
ते काय आहे	या run चा output	नंतरच्या runs साठी वेग वाढवणारे
ते कोण वाचते	माणसे, नंतरचे jobs, इतर workflows	तीच step, पुढच्या वेळी
ते नाहीसे झाले तर	deliverable हरवते — एक bug	step फक्त सावकाश चालते
ओळख कशावरून	एका run मधले नाव	inputs वरून hash केलेली key

🤔 का

प्रगतिपुस्तकाशिवाय लाल run म्हणजे log च्या मजकुराची भिंत, आणि "कोणती test?" याचे उत्तर म्हणजे scroll करत राहणे. Artifact शिवाय push job ला image पुन्हा build करावी लागते — आणि मग तुम्ही push करता तो डबा तुम्ही smoke-test केलेला डबा नसतो. Reports failures वाचनीय करतात; artifacts हस्तांतरण प्रामाणिक ठेवतात. Output विरुद्ध वेग वाढवणारे ही हीच रेषा Docker शाळेच्या धडा 02 मधल्या Docker layer cache मधूनही जाते: cache स्वागतार्ह आहे, पण पुढचे काहीही तो असण्यावर अवलंबून असू नये.

🔧 कसे (या repo मध्ये)

प्रगतिपुस्तक. Node चा test runner एकाच वेळी दोन reporters लिहू शकतो — तुमच्या terminal वर माणसाला सोपा spec आणि file मध्ये junit. app/package.json मधून:

"test:ci": "node --test --test-reporter=spec --test-reporter-destination=stdout --test-reporter=junit --test-reporter-destination=test-results.xml"

ci.yml तीच command चालवते, मग file upload करते — tests fail झाल्या तरीही, आणि नेमके तेव्हाच तुम्हाला ती हवी असते:

      - name: 🧪 test
        run: >
          node --test
          --test-reporter=spec  --test-reporter-destination=stdout
          --test-reporter=junit --test-reporter-destination=test-results.xml

      - name: 📎 upload the report card (lesson 05)
        if: always()          # especially when tests FAIL — that's when you need the report
        uses: actions/upload-artifact@v4
        with:
          name: test-results-node${{ matrix.node }}
          path: app/test-results.xml
          retention-days: 7

दोन तपशील थांबून पाहण्यासारखे. if: always() नसेल तर fail होणारी test step job थांबवते आणि upload वगळला जातो — report फक्त हिरव्या runs साठीच असेल. आणि artifact च्या नावात Node version आहे कारण matrix चे तीनही भाग प्रत्येकी एक बनवतात; upload-artifact@v4 मध्ये एक artifact नाव एका run मध्ये एकदाच वापरता येते, म्हणून सामायिक नाव असेल तर दुसऱ्या फूटपट्टीचा upload fail होईल.

डेस्कांमधले पाकीट. ship.yml मध्ये build job नुकतीच smoke-test केलेली image बांधतो, आणि push job — वेगळी मशीन — तेच bytes उघडतो:

      - name: 💾 keep the image for the push job (same run, different machine)
        run: docker save hello-courier:${GITHUB_SHA} | gzip > image.tar.gz
      - uses: actions/upload-artifact@v4
        with: { name: image, path: image.tar.gz, retention-days: 1 }

    steps:
      - uses: actions/download-artifact@v4
        with: { name: image }
      - run: docker load < image.tar.gz

एका दिवसाचे retention पुरेसे आहे: push काही मिनिटांनीच होतो, आणि image चे दीर्घकालीन घर ECR आहे, artifact store नाही (धडा 07). retention-days नसेल तर GitHub artifacts repository च्या default नुसार ठेवतो — Settings → Actions मध्ये कोणी बदलले नसेल तर 90 दिवस.

🔁 हेच CircleCI मध्ये

      - run:
          name: 🧪 test
          command: |
            mkdir -p test-results
            node --test --test-reporter=spec --test-reporter-destination=stdout \
                        --test-reporter=junit --test-reporter-destination=test-results/junit.xml
      - store_test_results:                                   # lesson 05: the report card, parsed
          path: test-results
      - store_artifacts:                                      # …and the raw file, downloadable
          path: test-results

store_test_results Tests tab ला माहिती पुरवते (आणि CircleCI च्या वेळेवर आधारित test splitting ला); store_artifacts कच्ची XML Artifacts खाली ठेवते. Jobs दरम्यान CircleCI files persist_to_workspace / attach_workspace ने देते (# illustrative — इथे गरज नाही, कारण या config मध्ये build आणि push एकच job वाटून घेतात).

🦊 हेच GitLab CI मध्ये

  artifacts:                                  # lesson 05: the report card — parsed into the MR widget
    when: always
    reports:
      junit: app/test-results.xml
    paths: [app/test-results.xml]
    expire_in: 1 week

reports: junit merge request वर test summary widget काढते ("1 failed, 2 passed"). paths: शिवाय file download करण्याजोगी करते, when: always म्हणजे if: always(), आणि expire_in म्हणजे retention. नंतरच्या stages मधल्या jobs ना आधीच्या jobs चे artifacts: default नुसार मिळतात.

🎩 हेच Jenkins मध्ये

            post { always { junit 'app/test-results.xml' } }   // lesson 05: the report card

junit (JUnit plugin) file वाचून build चे test result page आणि trend graph बनवते, आणि test fail झाली तर build ला failed ऐवजी unstable अशी खूण करते. कच्ची file सुद्धा ठेवायची असेल तर:

archiveArtifacts artifacts: 'app/test-results.xml'   // illustrative

🧪 करून पाहा

# 0) in your fork (lesson 03): make sure at least one ✅ ci run exists
gh run list --workflow ci.yml --limit 3

# 1) grab the newest run's id and download the Node 22 report card
RUN=$(gh run list --workflow ci.yml --limit 1 --json databaseId --jq '.[0].databaseId')
gh run download "$RUN" -n test-results-node22 -D report
cat report/test-results.xml         # <testsuite … tests="3" failures="0" …> — one <testcase> per test

# 2) produce the same file locally — no CI needed
cd app && npm run test:ci && head -5 test-results.xml && cd ..

# 3) see the envelope that ship.yml builds (Actions → 📦 ship → a run → Artifacts → "image")
gh run list --workflow ship.yml --limit 1
# it is tens of MB gzipped and disappears after a day — that's retention-days: 1 at work

⚠️ नेहमीच्या चुका

jobs दरम्यान files देण्यासाठी cache वापरणे — cache miss झाला की पुढच्या job ला गपचूप काहीच मिळत नाही; artifact वापरा
upload step वर if: always() विसरणे, म्हणजे प्रगतिपुस्तक फक्त काहीच बिघडले नसतानाच असते
default 90-दिवसांच्या retention सह भलामोठा folder (node_modules, build output) upload करणे — लागणाऱ्या files निवडा आणि retention-days ठरवा

⏭️ पुढे

Push job आता AWS शी बोलणार आहे. त्याने शाळेची मुख्य किल्ली 🔑 खिशात घेऊन फिरू नये — त्याने बॅज दाखवून डे पास घ्यावा. 🪪

git checkout lesson-06-secrets-oidc

📎 Lesson 05 — Artifacts & test reports: what travels between desks

📍 You are here: Lesson 05 of 12 · Previous: lesson-04-cache-parallel-matrix · Next: lesson-06-secrets-oidc

📦 What's in this branch

Lessons 01–04, plus the two things a desk can hand to someone else: a test report a human reads and an artifact a later job needs. Real files:

.github/workflows/ci.yml — the 📎 upload the report card step: if: always(), retention-days: 7
.github/workflows/ship.yml — the build job saves image.tar.gz; the push job downloads it on another machine
app/package.json — npm run test:ci writes the JUnit XML the report card is made from
.circleci/config.yml, .gitlab-ci.yml, Jenkinsfile — the same report card in the other three dialects

🧒 Explain like I'm 5

The checking desk ✅ finished your homework. Two things leave that desk.

First, the report card 📋: "3 checks, 3 passed". It gets pinned where anyone can read it — the teacher, your parents, you next Tuesday when you wonder which check broke. In CI that's a JUnit XML file. CircleCI, GitLab and Jenkins parse it into a table with a row per test; GitHub Actions keeps it as a download you open yourself.

Second, the envelope 📎: the photocopier desk 🍱 makes a copy of your homework and has to hand it to the delivery desk. But that desk is in a different room — in CI each job lands on a fresh machine, so anything you made is gone the moment the job ends. You put it in an envelope, write a name on it, and drop it in the run's pigeonhole. The next desk picks it up by name. That envelope is an artifact.

And the drawer of sharpened pencils 🗄️ from lesson 04? That's a cache. Nobody would miss the drawer if the janitor emptied it — you'd just sharpen again. An envelope going missing is a lost deliverable. Same shelf, very different rules.

🗺️ Diagram

flowchart LR
    t["✅ test job<br/>node --test → test-results.xml"]
    rc["📋 report card<br/>artifact test-results-node22"]
    human["🧑‍🏫 a human downloads it<br/>gh run download"]
    b["🍱 build job<br/>docker save → image.tar.gz"]
    env["📎 envelope<br/>artifact image"]
    p["🚚 push job<br/>another machine, docker load"]
    t -->|"1 upload, even on failure"| rc
    rc -->|"2 read later"| human
    b -->|"3 upload"| env
    env -->|"4 download by name"| p

❓ What

Artifact = a file (or folder) that is an output of this run, stored by the CI system so a human or a later job can fetch it. Named, tied to one run, kept for a set number of days.
Cache = a copy of something a future run could rebuild, kept only to save time. Keyed by a hash of its inputs; may be evicted at any moment.
Test report = a machine-readable summary of the test run. JUnit XML is the common format — it started in the Java world and the CI tools in this course understand it.
Retention = how long the artifact lives. retention-days: 7 for the report card, retention-days: 1 for the image envelope.
Between jobs = jobs of one run usually land on different runners, so the dependable way to pass a file from job A to job B is upload-in-A, download-in-B.

🧠 Envelope vs drawer

	📎 artifact	🗄️ cache
what it is	an output of this run	a speed-up for later runs
who reads it	humans, later jobs, other workflows	the same step, next time
if it vanishes	a deliverable is missing — a bug	the step just runs slower
addressed by	a name inside one run	a key hashed from the inputs

🤔 Why

Without the report card, a red run is a wall of log text and the answer to "which test?" is scrolling. Without the artifact, the push job has to rebuild the image — and then the box you push is not the box you smoke-tested. Reports make failures readable; artifacts make handoffs honest. The same output-vs-speed-up line runs through the Docker layer cache in the Docker school's lesson 02: a cache is welcome, but nothing downstream should depend on it existing.

🔧 How (in this repo)

The report card. Node's test runner can write two reporters at once — the human-friendly spec to your terminal and junit to a file. From app/package.json:

"test:ci": "node --test --test-reporter=spec --test-reporter-destination=stdout --test-reporter=junit --test-reporter-destination=test-results.xml"

ci.yml runs the same command, then uploads the file — even when the tests fail, which is exactly when you want it:

      - name: 🧪 test
        run: >
          node --test
          --test-reporter=spec  --test-reporter-destination=stdout
          --test-reporter=junit --test-reporter-destination=test-results.xml

      - name: 📎 upload the report card (lesson 05)
        if: always()          # especially when tests FAIL — that's when you need the report
        uses: actions/upload-artifact@v4
        with:
          name: test-results-node${{ matrix.node }}
          path: app/test-results.xml
          retention-days: 7

Two details worth a pause. Without if: always() a failing test step stops the job and the upload is skipped — the report would exist only for green runs. And the artifact name includes the Node version because the three matrix legs each produce one; with upload-artifact@v4 an artifact name can be used once per run, so a shared name would make the second ruler's upload fail.

The envelope between desks. In ship.yml the build job packs the image it just smoke-tested, and the push job — a separate machine — unpacks the very same bytes:

      - name: 💾 keep the image for the push job (same run, different machine)
        run: docker save hello-courier:${GITHUB_SHA} | gzip > image.tar.gz
      - uses: actions/upload-artifact@v4
        with: { name: image, path: image.tar.gz, retention-days: 1 }

    steps:
      - uses: actions/download-artifact@v4
        with: { name: image }
      - run: docker load < image.tar.gz

One day of retention is plenty: the push happens minutes later, and the long-term home of the image is ECR, not the artifact store (lesson 07). Without retention-days GitHub keeps artifacts for the repository's default — 90 days unless someone changed it under Settings → Actions.

🔁 The same thing in CircleCI

      - run:
          name: 🧪 test
          command: |
            mkdir -p test-results
            node --test --test-reporter=spec --test-reporter-destination=stdout \
                        --test-reporter=junit --test-reporter-destination=test-results/junit.xml
      - store_test_results:                                   # lesson 05: the report card, parsed
          path: test-results
      - store_artifacts:                                      # …and the raw file, downloadable
          path: test-results

store_test_results feeds the Tests tab (and CircleCI's timing-based test splitting); store_artifacts keeps the raw XML under Artifacts. Between jobs CircleCI passes files with persist_to_workspace / attach_workspace (# illustrative — not needed here, because build and push share one job in this config).

🦊 The same thing in GitLab CI

  artifacts:                                  # lesson 05: the report card — parsed into the MR widget
    when: always
    reports:
      junit: app/test-results.xml
    paths: [app/test-results.xml]
    expire_in: 1 week

reports: junit is what draws the test summary widget on a merge request ("1 failed, 2 passed"). paths: additionally makes the file downloadable, when: always is the if: always(), and expire_in is the retention. Jobs in later stages receive earlier jobs' artifacts: by default.

🎩 The same thing in Jenkins

            post { always { junit 'app/test-results.xml' } }   // lesson 05: the report card

junit (JUnit plugin) parses the file into the build's test result page and trend graph, and marks the build unstable rather than failed when a test fails. To keep the raw file too:

archiveArtifacts artifacts: 'app/test-results.xml'   // illustrative

🧪 Try it

# 0) in your fork (lesson 03): make sure at least one ✅ ci run exists
gh run list --workflow ci.yml --limit 3

# 1) grab the newest run's id and download the Node 22 report card
RUN=$(gh run list --workflow ci.yml --limit 1 --json databaseId --jq '.[0].databaseId')
gh run download "$RUN" -n test-results-node22 -D report
cat report/test-results.xml         # <testsuite … tests="3" failures="0" …> — one <testcase> per test

# 2) produce the same file locally — no CI needed
cd app && npm run test:ci && head -5 test-results.xml && cd ..

# 3) see the envelope that ship.yml builds (Actions → 📦 ship → a run → Artifacts → "image")
gh run list --workflow ship.yml --limit 1
# it is tens of MB gzipped and disappears after a day — that's retention-days: 1 at work

⚠️ Common mistakes

using a cache to pass files between jobs — a cache miss silently hands the next job nothing; use an artifact
forgetting if: always() on the upload step, so the report card exists only when nothing went wrong
uploading a huge folder (node_modules, build output) with the default 90-day retention — pick the files you need and set retention-days

⏭️ Next

The push job is about to talk to AWS. It should not be carrying the school's master key 🔑 in its pocket — it should show a badge and get a day pass. 🪪

git checkout lesson-06-secrets-oidc

← Previouscache parallel matrix Next →secrets oidc

This page is the lesson's README from the lesson-05-artifacts-reports branch, shown here so the whole School stays on one site. Code files open on GitHub at the same branch.