Build Artifacts

Artifact là đầu ra có thể phân phối hoặc dùng để điều tra của một build, ví dụ gói phát hành, report kiểm thử, checksum hay SBOM. Trang này phân biệt nơi file sống trong Pipeline với nơi nó được giữ lâu dài, để tránh vừa làm đầy controller vừa biến dữ liệu không tin cậy thành kênh phát tán.

Mục lụcCopy Anchor Link

• Bốn khái niệm không thể thay thế nhau
  • So sánh nhanh
• Luồng artifact và ranh giới dữ liệu
• Archive từ workspace
  • Chọn file bằng include, exclude và default excludes
  • Jenkinsfile archive an toàn
• Bảo mật, toàn vẹn và quyền truy cập
  • Đầu ra không tin cậy, symlink và path traversal
  • Quyền file, bất biến và bằng chứng phát hành
  • Secret không phải artifact
• Fingerprint: truy vết chứ không ký số
• Retention và build discard policy
• External artifact storage và artifact repository
  • Chọn đúng cơ chế
  • Upload download, retry và idempotency
  • Chi phí, quota và khôi phục
• Lab sandbox: archive một artifact vô hại
  • Chuẩn bị và Jenkinsfile
  • Kết quả mong đợi và cleanup
• Troubleshooting
• Checklist trước khi publish
• Nguồn Jenkins chính thức
• Đọc tiếp

Bốn khái niệm không thể thay thế nhauCopy Anchor Link

Một file có thể đi qua cả bốn cơ chế, nhưng mục đích của chúng khác nhau. Chọn sai cơ chế thường tạo retention khó đoán hoặc làm một build phụ thuộc vào workspace đã biến mất.

So sánh nhanhCopy Anchor Link

stash tối ưu cho sự liên tục của luồng Pipeline, không phải kho lưu trữ lâu dài. Chỉ stash những input nhỏ đã biết; nén/di chuyển lượng dữ liệu lớn có thể làm chậm agent, controller hoặc backend. unstash chỉ khôi phục vào workspace của stage sau, vì vậy stage đó vẫn phải kiểm tra checksum và không được coi workspace là nguồn phát hành chuẩn.

Workspace cũng không phải artifact store. Agent ephemeral, cleanup định kỳ, đổi node hoặc hai build dùng chung workspace có thể làm file biến mất hay lẫn với file cũ. Xem Chọn agent cho Pipeline và Tổng quan Jenkins Agent để hiểu executor, agent và vòng đời workspace.

Luồng artifact và ranh giới dữ liệuCopy Anchor Link

direction: down
A: "Source đã được review"
B: "Agent workspace"
C: "Build và test"
D: "dist/release đường dẫn cố định"
E: "SHA-256, SBOM và metadata"
F: "archiveArtifacts"
G: "Artifact Manager: controller\ndisk hoặc backend ngoài"
H: "Publisher có credential phạm vi\nhẹp"
I: "Artifact repository / object\nstorage"
J: "Fingerprint: build tạo và build\ndùng"
K: "Retention Jenkins"
L: "Versioning, immutability và\nlifecycle repository"

A -> B
B -> C
C -> D
D -> E
E -> F
F -> G
E -> H
H -> I
F -> J
G -> K
I -> L

Agent tạo file trong workspace. archiveArtifacts thu file khớp mẫu rồi chuyển trách nhiệm giữ file cho Artifact Manager. Với backend mặc định, artifact được lưu trong JENKINS_HOME trên controller; tải archive lớn, I/O và retention dài vì thế trực tiếp gây áp lực disk, backup và hiệu năng controller. Với một Artifact Manager plugin, ví dụ Artifact Manager on S3, Jenkins có thể lưu artifact/stash ở object storage thay vì controller disk. Đây là thay đổi backend của Jenkins artifact, không tự biến artifact thành package Maven/npm hay cung cấp workflow promotion.

Archive từ workspaceCopy Anchor Link

archiveArtifacts lấy file từ workspace của build hiện tại. Mẫu include/exclude được hiểu theo kiểu Ant và tương đối với workspace, không phải đường dẫn tuyệt đối của agent. Luôn tạo đầu ra vào một thư mục phát hành cố định như dist/release/, rồi archive đúng thư mục đó.

Chọn file bằng include, exclude và default excludesCopy Anchor Link

defaultExcludes không phải bộ lọc secret. Nó chủ yếu loại các tên file hệ thống/VCS theo quy ước Ant. Nếu build vô tình tạo dist/release/token.txt, mẫu rộng vẫn có thể archive nó. Cho phép archive phải dựa trên danh sách output mong đợi, review code tạo output và quét secret/SBOM theo policy, không dựa vào tên ẩn.

Jenkinsfile archive an toànCopy Anchor Link

Ví dụ sau chỉ archive ba loại file được tạo tại đường dẫn cố định. allowEmptyArchive: false khiến thiếu package trở thành lỗi thay vì build xanh nhưng không có artifact. fingerprint: true tạo fingerprint cho artifact được archive; phần sau giải thích giới hạn của fingerprint.

pipeline {
  agent { label 'linux && build-tools' }

  options {
    buildDiscarder(logRotator(
      daysToKeepStr: '30',
      numToKeepStr: '30',
      artifactDaysToKeepStr: '14',
      artifactNumToKeepStr: '10'
    ))
  }

  stages {
    stage('Build release output') {
      steps {
        sh '''#!/bin/sh
          set -eu
          mkdir -p dist/release
          ./scripts/build-release --output dist/release/app-1.2.3.tar.gz
          sha256sum dist/release/app-1.2.3.tar.gz > dist/release/SHA256SUMS
          ./scripts/create-sbom --output dist/release/sbom.cdx.json
        '''
      }
    }

    stage('Archive') {
      steps {
        archiveArtifacts(
          artifacts: 'dist/release/app-1.2.3.tar.gz,dist/release/SHA256SUMS,dist/release/sbom.cdx.json',
          excludes: 'dist/release/**/*.tmp',
          defaultExcludes: true,
          allowEmptyArchive: false,
          onlyIfSuccessful: true,
          followSymlinks: false,
          fingerprint: true
        )
      }
    }
  }
}

Thay ./scripts/build-release và ./scripts/create-sbom bằng lệnh đã được review của dự án. Nếu bản step không có followSymlinks, đừng tự suy diễn: nâng/cấu hình plugin theo quy trình vận hành hoặc chặn symlink ở bước build rồi xác minh bằng test sandbox. Nếu dùng post để lưu report khi test fail, xem cách giữ failure signal tại Xử lý lỗi và Retry.

Bảo mật, toàn vẹn và quyền truy cậpCopy Anchor Link

Đầu ra không tin cậy, symlink và path traversalCopy Anchor Link

Artifact có thể do dependency, test, pull request hoặc tool sinh ra. Vì vậy output của build từ nguồn không tin cậy cũng không tin cậy. Không archive toàn bộ workspace, .git, home directory hay một path do input người dùng/branch name điều khiển. Đặc biệt, không ghép trực tiếp biến PR, URL hay tên file không được chuẩn hóa vào include pattern hoặc destination upload.

Symbolic link có thể dẫn archive hay publisher ra ngoài thư mục dự kiến. Dùng thư mục output mới tạo, path cố định và tắt theo symlink khi step hỗ trợ. Trước khi publish/extract, kiểm tra manifest file; công cụ giải nén phía nhận phải từ chối entry ../, path tuyệt đối và link bất thường để tránh path traversal. Chạy build PR/fork trên agent tách biệt, không dùng credential publish hoặc quyền ghi vào bucket/repository production. Ranh giới credential và nguồn code được trình bày ở Credentials trong Pipeline.

Quyền file, bất biến và bằng chứng phát hànhCopy Anchor Link

Không giả định mode của file còn nguyên sau khi đi qua archive, object storage hay công cụ giải nén; backend và định dạng có thể xử lý metadata khác nhau. Trước khi đóng gói, đặt quyền tối thiểu cần thiết (ví dụ data 0644, executable được review 0755), không đóng gói file private chỉ vì nó đọc được trong workspace. Khi tải/xả artifact, dùng thư mục cô lập, owner không đặc quyền và umask phù hợp; xác minh tên, owner, mode và checksum trước khi dùng.

Một release nên có tối thiểu các bằng chứng sau:

• Checksum mạnh: tạo và công bố SHA-256/SHA-512 cho đúng byte của package. Jenkins fingerprint dùng MD5 lịch sử không thay thế checksum mật mã.
• SBOM và metadata: lưu SBOM (ví dụ CycloneDX/SPDX), revision SCM, version, thời điểm build, toolchain và provenance theo chuẩn của tổ chức. Metadata phải mô tả artifact, không chứa token hay URL có chữ ký ngắn hạn.
• Bất biến: repository/object store phải từ chối ghi đè version release đã publish. Dùng version bất biến, policy retention/lock phù hợp và tài khoản CI chỉ có quyền ghi namespace cần thiết. Không dùng lại latest làm bằng chứng phát hành.
• Xác minh khi download: lấy checksum/manifest từ kênh đáng tin, kiểm SHA-256 trước deploy hay test tiếp theo và ghi nhận kết quả audit.

Secret không phải artifactCopy Anchor Link

Secret, credential, private key, kubeconfig, token, file binding tạm và .env không bao giờ là artifact, dù chúng được dùng để tạo artifact. Không archive chúng, không để chúng trong dist/release/, không nhúng chúng vào report/SBOM/metadata và không in chúng để debug. Masking chỉ giảm nguy cơ lộ log, không biến secret thành dữ liệu an toàn để lưu hay upload.

Credential upload/download phải được nạp trong scope hẹp bằng Jenkins Credentials. Token cần quyền nhỏ nhất: publisher chỉ ghi repository/path của nó; consumer chỉ đọc version cần dùng. Bật TLS, xác minh CA/hostname, log actor/repository/version/checksum thay vì header xác thực, và review audit log của Jenkins lẫn repository. Chi tiết binding an toàn nằm tại Credentials trong Pipeline.

Fingerprint: truy vết chứ không ký sốCopy Anchor Link

Fingerprint là metadata Jenkins liên kết một file với build đã tạo và các build đã dùng file đó. Jenkins tính fingerprint dựa trên MD5 để nhận diện cùng nội dung byte-for-byte trong lịch sử Jenkins. Khi một Pipeline archive với fingerprint: true, Jenkins ghi association từ file đến build producer. Step fingerprint riêng cũng có thể ghi file đã tiêu thụ ở build downstream.

stage('Record consumed dependency') {
  steps {
    sh '''#!/bin/sh
      set -eu
      test -f vendor/input-library-4.5.6.jar
      sha256sum vendor/input-library-4.5.6.jar
    '''
    fingerprint targets: 'vendor/input-library-4.5.6.jar', recordArtifacts: false
  }
}

recordArtifacts: false chỉ ghi dấu vết; nó không làm file thành artifact tải được. Sau đó, trang fingerprint có thể trả lời build nào đã tạo/đã dùng cùng bytes, hữu ích khi đánh giá tác động của một dependency hay điều tra provenance nội bộ.

Fingerprint không chứng minh file an toàn, không ký phát hành, không thay thế SHA-256/Sigstore/chữ ký theo policy và không ép downstream phải dùng đúng file. Khi cần chuỗi cung ứng đáng tin, lưu checksum mạnh, chữ ký/provenance và phiên bản bất biến cùng artifact; dùng fingerprint như một chỉ mục truy vết bổ sung.

Retention và build discard policyCopy Anchor Link

Retention là policy giữ lại record build và bytes artifact theo thời gian hoặc số lượng. buildDiscarder(logRotator(...)) trên Jenkinsfile giúp policy đi cùng source, nhưng controller có thể có global policy, folder policy, plugin policy hay ngoại lệ compliance. Xác nhận policy có hiệu lực trong UI và bằng build sandbox; đừng cho rằng mọi job thừa kế y hệt nhau.

Trong ví dụ archive, Jenkins giữ tối đa 30 build record/30 ngày, còn artifact giữ tối đa 10 bản/14 ngày, tùy điều kiện nào đến trước. Khi artifact hết hạn nhưng record build còn, người điều tra có thể thấy build metadata/log mà không còn file tải được. Ngược lại, giữ artifact rất lâu làm controller disk, object storage, backup và thời gian restore tăng lên.

Thiết kế retention từ câu hỏi vận hành thay vì một số mặc định:

Đặt quota theo job/team/repository, dashboard dung lượng và alert trước ngưỡng disk/object-store. Đánh giá số byte mỗi build, tần suất, thời gian giữ, bản sao backup, API/list request và egress download; giá storage rẻ vẫn có thể kéo theo chi phí restore hay truy xuất cao. Kiểm tra backup và phục hồi JENKINS_HOME theo Backup & Restore Jenkins, còn capacity/độ trễ cần được theo dõi qua Hiệu năng Jenkins.

External artifact storage và artifact repositoryCopy Anchor Link

Chọn đúng cơ chếCopy Anchor Link

Có hai lớp external thường bị gọi chung là “external artifact storage”. Chúng bổ sung nhau, không đồng nghĩa.

Dùng external storage khi artifact lớn/nhiều, nhiều agent ephemeral, retention dài, controller disk gần ngưỡng, backup JENKINS_HOME quá nặng, hoặc cần phân phối qua vùng/đội khác. Không chuyển ra ngoài chỉ để né policy: phải có owner, encryption, IAM, logging, quota, lifecycle, restore drill và kế hoạch nếu plugin/backend không sẵn sàng.

Upload download, retry và idempotencyCopy Anchor Link

Ví dụ này giả định HTTP Request Plugin phiên bản đã được phê duyệt và tương thích Jenkins LTS hiện hành, cùng artifact repository sandbox chấp nhận HTTPS Basic authentication cho service account. Credential artifact-repository-uploader là Jenkins Username with password credential có quyền ghi đúng namespace; xác nhận step httpRequest, kiểu credential và các tham số khả dụng trong Pipeline Syntax → Snippet Generator của controller trước khi dùng. Địa chỉ .invalid chỉ là placeholder cố định.

stage('Publish to approved repository') {
  steps {
    script {
      def response = httpRequest(
        authentication: 'artifact-repository-uploader',
        consoleLogResponseBody: false,
        contentType: 'APPLICATION_OCTETSTREAM',
        httpMode: 'PUT',
        ignoreSslErrors: false,
        timeout: 30,
        uploadFile: 'dist/release/app-1.2.3.tar.gz',
        url: 'https://repository.example.invalid/releases/app/1.2.3/app-1.2.3.tar.gz',
        validResponseCodes: '200:201,204'
      )
      echo "Published immutable release path; HTTP status ${response.status}"
    }
  }
}

authentication chỉ là credential ID. HTTP Request Plugin lấy username/password từ Jenkins credential store trong JVM để tạo request; Jenkinsfile không nạp secret vào biến Groovy hay shell, không tạo process curl, và không đưa secret vào argv, URL, log, artifact hoặc workspace. Scope chỉ là step upload; sau step plugin không để lại file credential cần cleanup. consoleLogResponseBody: false giảm nguy cơ response chứa dữ liệu nhạy cảm bị in ra, nhưng không thay thế quyền tối thiểu hay review log/audit.

Mẫu cố ý chỉ nhận mã thành công của lần publish mới. Với retry, chỉ bọc request bằng retry sau khi repository đã xác nhận semantics cho PUT vào key version bất biến. Nếu timeout khiến client không biết server đã nhận bytes, trước lần gửi lại hãy dùng chính client/step credential-aware để gọi HEAD hoặc API metadata của repository, đối chiếu size và SHA-256 với SHA256SUMS. Chỉ coi 409/"already exists" là idempotent khi metadata xác nhận cùng nội dung; nếu khác, dừng và điều tra. Không dùng POST tạo version mới, không xóa hay ghi đè artifact production để thử lại.

Download cũng dùng client/plugin credential-aware hoặc credential được repository hỗ trợ, với TLS và quyền read-only scope hẹp. Không truyền token, password hay private key qua argv, custom header được shell mở rộng, URL query hoặc log; không đặt chúng trong artifact hay workspace. Audit cần ghi actor, credential ID, repository path, version, checksum, HTTP status và thời điểm — không ghi giá trị xác thực. Xem Credentials trong Pipeline và Xử lý lỗi và Retry để thiết kế scope và failure behavior.

Chi phí, quota và khôi phụcCopy Anchor Link

External backend giảm bytes trên controller nhưng tăng dependency mạng, IAM và độ trễ. Theo dõi tỷ lệ upload/download fail, retry count, latency, bytes theo job, quota denial, số object không có manifest và egress. Bất kỳ alert nào cũng cần runbook: phân biệt controller/job lỗi, agent mất mạng, token hết hạn, quota, object lifecycle đã xóa hoặc backend outage.

Retention Jenkins, Artifact Manager và repository/object lifecycle có thể không đồng bộ. Ví dụ Jenkins còn build record nhưng object đã bị lifecycle xóa, hoặc repository còn release mà Jenkins đã dọn archive. Chốt nguồn chuẩn cho từng loại artifact, giữ checksum/metadata đủ lâu, định kỳ thử download/verify trong sandbox, và ghi rõ RPO/RTO. Restore controller không tự khôi phục object bị xóa ở backend; phục hồi phải bao gồm quyền truy cập, bucket/repository, key/encryption và manifest. Quy trình nền tảng nằm tại Backup & Restore Jenkins.

Lab sandbox: archive một artifact vô hạiCopy Anchor Link

Lab này tạo một file text, checksum và SBOM JSON tối thiểu trong workspace lab. Nó không dùng credential, network, dữ liệu thật hay lệnh xóa ngoài workspace. Chạy trên job Pipeline sandbox với Linux agent; kiểm tra Pipeline: Basic Steps trước khi chạy.

Chuẩn bị và JenkinsfileCopy Anchor Link

Tạo một Pipeline job mới, dán Jenkinsfile sau rồi chạy Build Now. Tên demo-artifact và nội dung file đều vô hại. post { always { deleteDir() } } chỉ dọn workspace mà build lab đang được cấp sau khi archive hoàn tất.

pipeline {
  agent { label 'linux' }

  stages {
    stage('Create harmless output') {
      steps {
        sh '''#!/bin/sh
          set -eu
          mkdir -p dist/release
          printf 'jenkins artifact lab\n' > dist/release/demo-artifact.txt
          sha256sum dist/release/demo-artifact.txt > dist/release/SHA256SUMS
          printf '{"bomFormat":"CycloneDX","specVersion":"1.5","components":[]}\n' \
            > dist/release/sbom.cdx.json
        '''
      }
    }

    stage('Archive and fingerprint') {
      steps {
        archiveArtifacts(
          artifacts: 'dist/release/demo-artifact.txt,dist/release/SHA256SUMS,dist/release/sbom.cdx.json',
          defaultExcludes: true,
          allowEmptyArchive: false,
          onlyIfSuccessful: true,
          followSymlinks: false,
          fingerprint: true
        )
      }
    }
  }

  post {
    always {
      deleteDir()
    }
  }
}

Kết quả mong đợi và cleanupCopy Anchor Link

Build phải có trạng thái SUCCESS. Tại build page, mục Artifacts có đúng demo-artifact.txt, SHA256SUMS và sbom.cdx.json; trang fingerprint của file cho thấy build lab hiện tại. Tải hai file text, chạy sha256sum -c SHA256SUMS trong thư mục tải về và nhận demo-artifact.txt: OK.

Sau build, log deleteDir cho biết workspace lab đã được dọn. Xác nhận job khác không dùng chung workspace trước khi dùng cleanup này. Khi lab kết thúc, chỉ xóa build/job sandbox qua UI theo policy đội ngũ; không đụng archive, bucket hay artifact production.

TroubleshootingCopy Anchor Link

Checklist trước khi publishCopy Anchor Link

• Output chỉ nằm trong path cố định như dist/release/; include/exclude hẹp, defaultExcludes: true và allowEmptyArchive: false cho release.
• Đã kiểm tra symlink/path traversal, source không tin cậy và quyền file trước archive/publish/extract.
• Archive không chứa secret, credential, file binding, .env, private key hay URL có chữ ký; upload/download dùng credential scope hẹp qua TLS.
• Mỗi release có version bất biến, SHA-256/SHA-512, SBOM và metadata/provenance đã được review.
• Fingerprint được hiểu là truy vết MD5 giữa build producer/consumer, không phải xác minh mật mã hay chữ ký.
• buildDiscarder và retention backend/repository có owner, quota, cost model, monitoring, audit và restore drill.
• File lớn/cross-team dùng Artifact Manager backend hoặc artifact repository đã phê duyệt; controller disk không là kho mặc định vô hạn.
• Upload có timeout, retry có giới hạn và thao tác idempotent; download xác minh checksum trước sử dụng.
• Lab sandbox đã cho ra ba artifact, fingerprint và cleanup đúng workspace trước khi áp dụng production.

Nguồn Jenkins chính thứcCopy Anchor Link

• Jenkins Pipeline Syntax: archiveArtifacts
• Jenkins Pipeline Syntax: stash và unstash
• Jenkins User Handbook: Using fingerprints
• Jenkins User Handbook: Managing build records
• Jenkins Pipeline Syntax: buildDiscarder và logRotator
• Jenkins Artifact Manager on S3 plugin
• Jenkins HTTP Request Plugin
• Jenkins Credentials

Đọc tiếpCopy Anchor Link