Dependency Cache (ระบบบันทึกและกู้คืนแคช)

บันทึกและกู้คืนแคชของ dependency ระหว่างการรัน pipeline เพื่อเร่งความเร็ว

การอ้างอิง (Reference): loha/cache@v2

หมวดหมู่: Build (การสร้างอิมเมจและแคช)

รันไทม์ (Runtime): curlimages/curl:8.5.0 (รันแบบ non-root, ตรึงด้วย digest)

สัญญาอนุญาต (License): Apache-2.0

ควรใช้เมื่อ

ใช้ประกบหน้าหลังคำสั่งติดตั้ง (install) เพื่อลดระยะเวลาในการดาวน์โหลด dependency ซ้ำ โดยวางขั้นตอน restore ก่อนคำสั่ง install และวางขั้นตอน save หลังจาก install สำเร็จ

พารามิเตอร์

พารามิเตอร์	ชนิด	ค่าเริ่มต้น	จำเป็น	คำอธิบาย
`ACTION`	enum: `restore`, `save`	—	ใช่	การทำงานกับ cache: `restore` เพื่อกู้คืนข้อมูลแคชเดิม หรือ `save` เพื่อบันทึกแคชใหม่
`PATHS`	`string`	—	ใช่	รายการโฟลเดอร์หรือไฟล์ที่ต้องการบันทึกหรือกู้คืนจาก cache (คั่นด้วยจุลภาค)
`KEY_FILES`	`string`	`package-lock.json`	ไม่	รายการไฟล์ที่นำเนื้อหามาแฮช (hash) เพื่อสร้าง cache key (คั่นด้วยจุลภาค)
`CACHE_PREFIX`	`string`	`default`	ไม่	ข้อความ prefix นำหน้าเพื่อแยก cache ของแต่ละงานให้ไม่ปะปนกัน
`FAIL_ON_MISS`	enum: `true`, `false`	`false`	ไม่	กำหนดให้ task ล้มเหลวทันทีหากไม่พบแคชที่ตรงกันเมื่อสั่งกู้คืน (restore)
`WORKING_DIRECTORY`	`string`	`.`	ไม่	ไดเรกทอรีทำงานของ task โดยคิดเทียบจาก root ของ workspace

พื้นที่ทำงาน (Workspaces)

source (จำเป็น): เชื่อมโยงจาก pipeline workspace source

ผลลัพธ์ (Results)

ผลลัพธ์ (Result)	คำอธิบาย
`CACHE_HIT`	ค่าเป็น `true` เมื่อกู้คืนแคชสำเร็จ หรือ `false` หากไม่พบแคชหรือกำลังสั่งบันทึกแคช
`CACHE_KEY`	คีย์ระบุแคชที่คำนวณได้จากผลการแฮชไฟล์ใน KEY_FILES

การทำงาน

ระบบจะสร้าง cache key ขึ้นจาก CACHE_PREFIX รวมกับค่าแฮชของไฟล์ใน KEY_FILES หากไฟล์เหล่านี้มีการเปลี่ยนแปลง ค่า cache key จะเปลี่ยนไปและระบบจะสร้างแคชชุดใหม่ ทั้งนี้ระบบจะแยกพื้นที่แคชตาม repository และ branch: build จะพยายามอ่านแคชของ branch ตัวเองก่อน หากไม่พบจะค้นหาจาก default branch แต่การเขียนบันทึกแคชจะทำได้เฉพาะใน branch ของตนเองเท่านั้นเพื่อป้องกันการเขียนทับแคชของ branch อื่น

ตัวอย่าง

ใช้แคชกับการติดตั้ง npm install

steps:
  - name: restore-cache
    uses: loha/cache@v2
    with:
      ACTION: 'restore'
      PATHS: 'node_modules,.npm'
      KEY_FILES: 'package-lock.json'
      CACHE_PREFIX: 'npm'

  - name: install
    uses: loha/run-command@v1
    with:
      COMMAND: 'npm ci'

  - name: save-cache
    uses: loha/cache@v2
    with:
      ACTION: 'save'
      PATHS: 'node_modules,.npm'
      KEY_FILES: 'package-lock.json'
      CACHE_PREFIX: 'npm'

ใช้แคชกับการติดตั้ง pip install ในโปรเจกต์ Python

steps:
  - name: restore-cache
    uses: loha/cache@v2
    with:
      ACTION: 'restore'
      PATHS: '.venv,.pip-cache'
      KEY_FILES: 'requirements.txt,requirements-dev.txt'
      CACHE_PREFIX: 'pip'

  - name: install
    uses: loha/run-command@v1
    with:
      COMMAND: 'pip install -r requirements.txt --cache-dir .pip-cache'
      IMAGE: 'python:3.12-slim'

  - name: save-cache
    uses: loha/cache@v2
    with:
      ACTION: 'save'
      PATHS: '.venv,.pip-cache'
      KEY_FILES: 'requirements.txt,requirements-dev.txt'
      CACHE_PREFIX: 'pip'

ใช้แคชกับการคอมไพล์ cargo build ในภาษา Rust

steps:
  - name: restore-cache
    uses: loha/cache@v2
    with:
      ACTION: 'restore'
      PATHS: 'target,.cargo/registry'
      KEY_FILES: 'Cargo.lock'
      CACHE_PREFIX: 'cargo'

  - name: build
    uses: loha/run-command@v1
    with:
      COMMAND: 'cargo build --release'
      IMAGE: 'rust:1.76-alpine'

  - name: save-cache
    uses: loha/cache@v2
    with:
      ACTION: 'save'
      PATHS: 'target,.cargo/registry'
      KEY_FILES: 'Cargo.lock'
      CACHE_PREFIX: 'cargo'

การแก้ปัญหา

ปัญหา: เกิด cache miss (ไม่พบแคช) ในทุกๆ ครั้งที่สั่งรัน

วิธีแก้: ตรวจสอบว่าเส้นทางไฟล์ที่ระบุใน KEY_FILES มีอยู่จริงใต้ WORKING_DIRECTORY ขณะ pipeline กำลังทำงาน เนื่องจากการสะกดชื่อไฟล์ผิดจะทำให้การคำนวณแฮชเปลี่ยนไปตลอดเวลา

ปัญหา: ขั้นตอน restore สำเร็จ แต่ขั้นตอน install ก็ยังดาวน์โหลดแพ็กเกจใหม่ทั้งหมด

วิธีแก้: ตรวจสอบว่ารายการใน PATHS ครอบคลุมไดเรกทอรีที่ package manager นั้นใช้งานอย่างครบถ้วน (เช่น สำหรับ npm จำเป็นต้องระบุทั้ง node_modules และโฟลเดอร์แคช .npm)

ปัญหา: ขั้นตอน cache แจ้งว่า "build caching is not available for this run" และถูกข้ามไป

วิธีแก้: Build cache ปิดอยู่สำหรับ repository นี้, แพ็กเกจไม่รวมการแคช, build นี้ไม่มี repository ให้ผูกแคช (เช่น manual run ที่ไม่มี repository) หรือระบบที่ติดตั้งอยู่ไม่รองรับแคช ขั้นตอนนี้จะไม่ทำอะไรและ build ทำงานต่อโดยไม่ใช้แคช ดูสาเหตุได้จาก build warnings — ผู้ดูแล workspace เปิดได้ที่ Repository settings → Build cache และถ้า build ต้องมีแคชเสมอ ให้ตั้ง FAIL_ON_MISS: true ที่ขั้นตอน restore

ปัญหา: ในล็อกของขั้นตอน save มีข้อความ "cache save failed" แต่ build ยังเป็นสีเขียว

วิธีแก้: การบันทึกแคชเชื่อมต่อกับที่เก็บแคชไม่ได้ จึงไม่มีอะไรถูกบันทึกและ build ครั้งถัดไปจะเริ่มโดยไม่มีแคช ตัว build เองไม่ได้รับผลกระทบ หากทุกครั้งที่ save แสดงข้อความนี้ แสดงว่าที่เก็บแคชของระบบที่ติดตั้งตั้งค่าไว้ไม่ถูกต้อง ให้แจ้งผู้ดูแลระบบ Loha หากข้อความแสดง CACHE_BUDGET_EXCEEDED แสดงว่า workspace ใช้พื้นที่แคชของ build เต็มตามขีดจำกัดแล้ว รายการแคชที่เก่ากว่าจะถูกลบทุกชั่วโมง หรือผู้ดูแลระบบ Loha สามารถเพิ่มขีดจำกัดให้ได้

ปัญหา: การรันบน Pull Request พบแคช (cache hit) แต่ branch หลักระยะยาวกลับไม่พบแคช (cache miss)

วิธีแก้: เป็นพฤติกรรมปกติของระบบ: แต่ละ branch จะอ่านแคชของตนเองเป็นลำดับแรกก่อน fallback ไปยัง default branch และจะสามารถเขียนบันทึกแคชได้เฉพาะใน scope ของ branch ตนเองเท่านั้น

ควรใช้เมื่อ​

พารามิเตอร์​

พื้นที่ทำงาน (Workspaces)​

ผลลัพธ์ (Results)​

การทำงาน​

ตัวอย่าง​

ใช้แคชกับการติดตั้ง npm install​

ใช้แคชกับการติดตั้ง pip install ในโปรเจกต์ Python​

ใช้แคชกับการคอมไพล์ cargo build ในภาษา Rust​

การแก้ปัญหา​