loha plan
loha plan แสดงสิ่งที่ Loha จะรันจาก .loha.yml ของคุณใน branch และ event ที่ระบุ ได้แก่ job และขั้นตอนใดบ้าง
ใช้อิมเมจอะไร ได้ CPU และหน่วยความจำเท่าไร และแต่ละขั้นตอนอ่าน secret ตัวใดได้ ไม่มีอะไรถูกรันจริง ระบบไม่สร้างบิลด์
ไม่ถอดรหัส secret และไม่ออก token จึงรัน plan ซ้ำกี่ครั้งก็ได้อย่างปลอดภัย
plan สร้างจากกระบวนการเดียวกับที่คลัสเตอร์ใช้เริ่มบิลด์จริง และอ่านจากเซิร์ฟเวอร์ของ Loha จึงตรงกับหน้าบิลด์ ไม่ใช่การตีความไฟล์ด้วยเครื่องของคุณเอง สิ่งที่บิลด์จริงปฏิเสธ (เช่น อิมเมจนอกรีจิสทรีที่อนุญาต ชื่อ environment ที่ถูกห้าม matrix เกินขีดจำกัด) plan ก็ปฏิเสธด้วยข้อความเดียวกัน
loha plan เป็นส่วนหนึ่งของฟีเจอร์ local run ซึ่งเปิดเป็นค่าเริ่มต้น หากผู้ดูแลแพลตฟอร์มของ Loha ปิดไว้สำหรับเวิร์กสเปซของคุณ คำสั่งจะหยุดพร้อมข้อความ
Local runs are not enabled for this workspace. Ask a workspace admin to turn on local_run. และออกด้วยโค้ด 2
หากต้องการรัน plan บนเครื่องของคุณเอง ดู loha run --local
วิธีใช้
รันจากภายใน checkout ที่ remote origin ชี้ไปยังรีโพสิทอรีที่ onboard กับ Loha แล้ว:
loha plan
หากไม่ระบุแฟล็ก CLI จะอ่าน branch, commit ล่าสุด และรีโพสิทอรีจาก git checkout ของคุณ สมมติว่าเป็น event push
และทำ plan ของ ./.loha.yml
Plan for .loha.yml on main (push) at 3f9c2ab
On: would fire (Matches the on.push entry for branch main.)
Trigger: tr_8a1 (auto)
build [medium 2 / 4Gi]
run clone node:22
emu checkout alpine/git@sha256:aaaa…
↳ Replaced by the staged working tree.
run test node:22
secrets: NPM_TOKEN
skip lint-extra node:22
↳ Condition `matrix.skip_lint != 'true'` is false for branch main, event push.
release skipped: Condition `github.event == 'tag_push'` is false for branch main, event push.
loha-security-final-gate [platform]
skip security-gate
↳ The managed security gate runs only on the cluster.
! Step "notify" references secret "SLACK_URL" but no such secret is defined in scope
Variables: names only (token lacks variables:values:read)
ค่าข้างต้นเป็นตัวอย่าง ชื่ออิมเมจ รหัส และ job ที่คุณเห็นขึ้นอยู่กับเวิร์กสเปซและ pipeline ของคุณ บรรทัดว่างคั่นระหว่างบรรทัดแรก แต่ละ job คำเตือน และบรรทัด Variables:
แฟล็ก
| แฟล็ก | หน้าที่ |
|---|---|
--file <path> | ไฟล์ pipeline ที่จะทำ plan (ค่าเริ่มต้น .loha.yml) |
--branch <name> | branch ที่จะทำ plan (ค่าเริ่มต้นคือ branch ที่ checkout อยู่ หาก HEAD แยกตัว (detached) ต้องระบุแฟล็กนี้) |
--event <type> | event ที่จะทำ plan: push (ค่าเริ่มต้น), pull_request, tag, manual หรือ release (tag จะถูกส่งเป็น tag_push ซึ่งใช้เป็นชื่อ แทนได้เช่นกัน) เงื่อนไขของ job และขั้นตอนจะถูกประเมินตาม event นี้ |
--base <branch> | branch ปลายทางของ pull request เพื่อประเมินบล็อก on: กับมัน ใช้ได้กับ --event pull_request เท่านั้น |
--tag <tag> | tag ที่ถูก push เพื่อประเมินบล็อก on: กับมัน ใช้ได้กับ --event tag เท่านั้น |
--sha <sha> | commit ที่จะทำ plan (ค่าเริ่มต้น HEAD) |
--repo <id> | รีโพสิทอรีที่จะทำ plan (ค่าเริ่มต้น หาจาก git remote) |
--trigger <id> | ใช้ตัวแปรและการตั้งค่าของ trigger นี้ |
--var KEY=VALUE | ตัวแปรขณะรันที่ใส่เป็น env ของขั้นตอน ระบุซ้ำได้ |
--json | พิมพ์ plan จากเซิร์ฟเวอร์ตามเดิม สำหรับสคริปต์และเอเจนต์ |
โค้ดที่คำสั่งออก
| โค้ด | ความหมาย |
|---|---|
0 | แสดง plan สำเร็จ |
1 | คอนฟิกถูกปฏิเสธ พิมพ์ข้อผิดพลาดจากเซิร์ฟเวอร์ตรงตามที่คลัสเตอร์จะตอบ |
2 | ใช้คำสั่งผิด (รวมถึงส่งอาร์กิวเมนต์เกิน) หรือยืนยันตัวตนไม่ผ่าน เวิร์กสเปซยังไม่ได้เปิดใช้การรันในเครื่อง เซิร์ฟเวอร์อ่านคำขอไม่ได้ (เช่น --sha รูปแบบผิด) หรือเซิร์ฟเวอร์มีปัญหา (ไม่พบรีโพสิทอรีหรือ trigger, ตัววางแผนใช้งานไม่ได้, เกินอัตราที่กำหนด, 5xx) |
วิธีอ่าน plan
บรรทัดแรก Plan for <file> on <branch> (<event>) at <short sha> เมื่อใช้ --event tag event จะแสดงเป็น tag_push
On On: would fire (<reason>) หรือ On: would not fire (<reason>) บอกว่าบล็อก on: ของ pipeline
จ ะเริ่มบิลด์สำหรับ event, branch นี้หรือไม่ (และเมื่อใช้ --base หรือ --tag ก็รวม branch ปลายทางของ pull request หรือ tag ด้วย)
ซึ่งเป็นคำตอบของเซิร์ฟเวอร์จากการตรวจชุดเดียวกับที่เกิดขึ้นตอน push จริง ใช้ --event pull_request --base main
หรือ --event tag --tag v1.2.3 เพื่อถามเรื่อง event เหล่านั้น สำหรับ event release บรรทัดจะเป็น
On: not evaluated for release events หากเซิร์ฟเวอร์ไม่รายงานค่านี้ บรรทัดจะไม่ถูกแสดง บรรทัดนี้เป็นเพียงข้อมูล:
plan ยังถูกแสดง และ loha run --local ยังรัน ไม่ว่าคำตอบจะเป็นอย่างไร (การรันในเครื่องจะพิมพ์บรรทัดเดียวกันก่อนเป็น notice:
! On: would fire (<reason>) หรือ ! On: would not fire (<reason>)) การใช้ --base กับ event อื่นที่ไม่ใช่ pull_request หรือ --tag กับ event อื่นที่ไม่ใช่ tag
เป็นข้อผิดพลาดการใช้คำสั่ง (โค้ด 2) เพื่อให้คำตอบไม่เคยหมายถึงสิ่งอื่นนอกจากที่คุณถาม
Trigger Trigger: <id> (explicit) เมื่อคุณระบุ --trigger และ Trigger: <id> (auto) เมื่อรีโพสิทอรีมี trigger
ที่เปิดอยู่และอ่านไฟล์นี้เพียงตัวเดียวที่จะทำงานกับ event นั้น นอกจากนี้จะเป็น Trigger: none และมีคำเตือนแสดงรายการตัวเลือก
เพื่อให้คุณเลือกด้วย --trigger การเลือก trigger มีผลเพราะตัวแปรระดับ trigger และค่าเริ่มต้นด้านทรัพยากรของ plan มาจาก trigger นั้น
(ดู การจัดการ secret)
Job แต่ละ job แสดงเป็น <id> [<class> <cpu> / <memory>] คือทรัพยากรที่คลัสเตอร์จะให้ job นั้น
job ที่จะไม่ทำงานแสดงเป็น <id> skipped: <reason> (เช่น เงื่อนไขเป็นเท็จสำหรับ branch นี้) job แบบ matrix จะถูกขยายแล้ว
แสดงทีละชุด เหมือนในหน้าบิลด์ ส่วน job ที่ Loha เพิ่มเอง เช่น security gate จะแสดงเป็น [platform] โดยไม่มี CPU และหน่วยความจำ
ขั้นตอน ทุกขั้นตอนขึ้นต้นด้วยป้าย:
| ป้าย | ความหมาย |
|---|---|
run | รันตามที่เขียน ใช้อ ิมเมจและสคริปต์เดียวกัน loha run --local จะรันโดยไม่ดัดแปลง |
emu | จำลอง (emulated): ขั้นตอนบนคลัสเตอร์พึ่งสิ่งที่เครื่องส่วนตัวไม่มี การรันในเครื่องจะใช้ตัวแทน ได้แก่ การ clone commit ที่พุช, cache, job output และ artifact (เซิร์ฟเวอร์ในเครื่องตอบสคริปต์จริง), การ build อิมเมจ (engine ของคุณ build ให้ และไม่มีการ push) หรือ approval gate (คุณตอบในเทอร์มินัล) |
skip | ไม่รันบนเครื่องของคุณ เพราะเปลี่ยนสถานะระยะไกล (พุช deploy แจ้งเตือน เซ็นชื่อ) เป็น security gate ของแพลตฟอร์ม หรือเงื่อนไข if: เป็นเท็จสำหรับ branch และ event นี้ เหตุผลแสดงใต้ขั้นตอนนั้น |
ป้ายบอกว่าการรัน ในเครื่อง จะทำอะไร ไม่ใช่สิ่งที่คลัสเตอร์ทำ เช่น ขั้นตอน deploy ที่ขึ้น skip ยังคง deploy บนคลัสเตอร์ บรรทัดที่ขึ้นต้นด้วย ↳ ใต้ขั้นตอนคือเหตุผล
และ secrets: A, B คือรายชื่อ secret ที่ขั้นตอนนั้นได้รับสิทธิ์
คำเตือน บรรทัดที่ขึ้นต้นด้วย ! คือสิ่งที่ plan ตัดสินแทนคุณไม่ได้ เช่น ขั้นตอนอ้าง secret ที่ไม่มีอยู่ในขอบเขต
หรือโควตาที่อาจทำให้บิลด์ล่าช้า คำเตือนไม่ทำให้ plan ล้มเหลว
ตัวแปร บรรทัดสุดท้ายบอกว่า plan มีค่าตัวแปรที่เก็บไว้หรือไม่ ดูหัวข้อถัดไป
ตัวแปรและ secret ใน plan
plan ไม่มีค่า secret เลย แต่ละขั้นตอนแสดงเฉพาะ ชื่อ ของ secret ที่ได้รับสิทธิ์และมีอยู่ในขอบเขตเท่านั้น
ตัวแปรธรรมดา (ที่ไม่ใช่ secret) ขึ้นกับ token ของคุณ:
| token ของคุณ | plan แสดง |
|---|---|
มี variables:values:read | ค่าตัวแปรธรรมดา (Variables: values included) |
| ไม่มี | ชื่อเท่านั้น (Variables: names only (token lacks variables:values:read)) |
variables:values:read เป็น scope ของ personal access token แบบเลือกเปิดเอง
variables:read ยังหมายถึงข้อมูลเมตาเหมือนเดิม (ไม่เคยมีค่า) guest ถือ scope ใหม่นี้ไม่ได้ และชุดสิทธิ์ "Read only" ไม่รวม scope นี้
token ที่สร้างก่อนหน้านี้จะไม่ได้ scope ใหม่ หากต้องการให้ plan แสดงค่า ให้สร้าง token ใหม่แล้วเลือก scope นี้
plan ต้องใช้ scope pipelines:read และเหมือน token ทั่วไป จะเห็นได้เฉพาะเวิร์กสเปซที่ token ผูกอยู่ service account key ที่ผูกกับโปรเจกต์เดียว
ทำ plan ได้เฉพาะรีโพสิทอรีของโปรเจกต์นั้น
ไม่พบรีโพสิทอรีที่ตรงกัน
หาก git remote ไม่ตรงกับรีโพสิทอรีใดในเวิร์กสเปซที่ใช้งานอยู่ plan จะแสดงโดยไม่มีรีโพสิทอรี และแจ้งว่า:
No connected repository matches this checkout; planning without repository or trigger variables.
ตัวแปรระดับรีโพสิทอรีและระดับ trigger จะไม่อยู่ใน plan ระบุ --repo เพื่อเลือกรีโพสิทอรีเอง
plan จำลองอะไรได้และไม่ได้
plan คือคำตอบของคลัสเตอร์เอง จึงครอบคลุมทุกอย่างที่เซิร์ฟเวอร์ตัดสิน ตารางต่อไปนี้สรุปว่าเมื่อมีการรันขั้นตอนบนเครื่อง อะไรเหมือนเดิม อะไรถูกจำลอง และอะไรต่างไป
| ด้าน | ในเครื่องเทียบกับคลัสเตอร์ |
|---|---|
| การ parse เงื่อนไข matrix ลำดับความสำคัญของ env การ render task นโยบายอิมเมจ ชื่อ env ที่ถูกห้าม | เหมือนกัน เซิร์ฟเวอร์เป็นผู้ตัดสินทั้งหมด |
| อิมเมจ สคริปต์ user id capability และ working directory ของขั้นตอน | เหมือนกัน |
| CPU และหน่วยความจำ | ค่าเดียวกัน แต่การจัดวางและการเลือกโหนดไม่ถูกจำลอง |
| ซอร์สโค้ด | จำลอง ใช้ working tree ของคุณแทนการ clone commit ที่พุช |
| Services | จำลอง ใช้ alias ในเครือข่ายคอนเทนเนอร์แทน sidecar |
| Cache, job output, การ build อิมเมจ, approval gate | จำลอง ดูความต่างของแต่ละอย่างที่ loha run --local |
| เครือข่าย | ต่างกัน ใช้เครือข่ายของคุณ ไม่ใช่กฎ egress ของ build pod หรือ mirror ในคลัสเตอร์ |
| สถาปัตยกรรม | ต่างกัน เว้นแต่เลือก platform เอง |
| Secret และตัวแปรที่เก็บไว้ | ต่างที่มา secret ไม่อยู่ใน plan เลย ตัวแปรธรรมดามีเมื่อมี scope แบบเลือกเปิด |
| พุช deploy แจ้งเตือน เซ็นชื่อ security gate และบันทึกบิลด์ | ไม่ทำในเครื่องเด็ดขาด |
API
loha plan เรียก POST /api/v1/pipelines/plan (scope pipelines:read) body ประกอบด้วย YAML และบริบท git
(yaml, branch, event, commitSha และเลือกใส่ repositoryId, triggerId, runtimeVars, targetBranch, tag) คำตอบคือ { "plan": … }
เอกสารที่ไม่ถูกต้องได้ 422 พร้อมรายการข้อผิดพลาดเหมือน loha validate
คำขอที่เซิร์ฟเวอร์อ่านไม่ได้ (เช่น commitSha รูปแบบผิด) ได้ 400 พร้อม code: "VALIDATION_ERROR" และข้อความรายฟิลด์
คอนฟิกที่คลัสเตอร์จะปฏิเสธได้ 400 พร้อม code และข้อความ (PIPELINE_CONFIG_ERROR)
การปฏิเสธจาก Build Security (เช่น IMMUTABLE_SOURCE_REQUIRED) หรือคอนฟิกที่ plan แสดงผลไม่ได้ (PLAN_PROJECTION_FAILED) ได้ 422 พร้อม code และข้อความ
ไม่พบรีโพสิทอรีหรือ trigger ได้ 404 (Repository not found หรือ Trigger not found)
service account key ที่ผูกกับโปรเจกต์อื่น หรือการทำ plan โดยไม่มีรีโพสิทอรี ได้ 403 (Service account is not bound to this project)
เวิร์กสเปซที่ยังไม่เปิดฟีเจอร์ได้ 403 พร้อม code: "FEATURE_DISABLED"
และเมื่อตัววางแผนล้มเหลวด้วยเหตุอื่นที่ไม่ใช่การปฏิเสธคำขอของคุณ (เช่น ใช้งานไม่ได้) จะได้ 503 พร้อม code: "CONTROLLER_UNAVAILABLE" (The pipeline planner is unavailable. Try again shortly.)
ดู schema ฉบับเต็มใน เอกสาร OpenAPI
ดูเพิ่มเติม
loha run --local: รัน plan ใน container บนเครื่องของคุณ- CLI: การติดตั้ง การเข้าสู่ระบบ และคำสั่งอื่น
- Personal access tokens: scope ต่าง ๆ รวมถึง
variables:values:read - Triggers