ออกแบบ Workflow และ Trigger ที่เหมาะสมใน GitHub Actions เมื่อมี Pull Request เพื่อสร้าง Release Notes อัตโนมัติ

ในโลกของการพัฒนาซอฟต์แวร์สมัยใหม่ การจัดการเวอร์ชันและการสื่อสารการเปลี่ยนแปลง (Changelog/Release Notes) เป็นกระบวนการที่สำคัญแต่ก็มักจะถูกมองข้ามไป การจะนั่งเขียนรายการเปลี่ยนแปลงทั้งหมดด้วยมือหลังจากการ Merge Pull Request แต่ละครั้งนั้นทั้งเสียเวลาและเสี่ยงต่อความผิดพลาด บทความนี้จะเจาะลึกถึงวิธีการ ออกแบบ Workflow และ Trigger ที่เหมาะสมใน GitHub Actions เมื่อมี Pull Request เพื่อสร้าง Release Notes อัตโนมัติ ซึ่งจะช่วยให้ทีมของคุณประหยัดเวลาและมั่นใจได้ว่าเอกสาร Release Notes จะทันสมัยอยู่เสมอ ออกแบบ Workflow และ Trigger ที่เหมาะสมใน GitHub Actions เมื่อมี Pull Request เพื่อสร้าง Release Notes อัตโนมัติ คือหัวใจสำคัญของการทำ CI/CD ที่มีประสิทธิภาพ

ทำไมต้องสร้าง Release Notes อัตโนมัติด้วย GitHub Actions?

การสร้าง Release Notes ด้วยมือ (Manual Changelog) มีข้อเสียหลายประการ ไม่ว่าจะเป็นความไม่สม่ำเสมอของรูปแบบ (Inconsistency) การตกหล่นของฟีเจอร์ที่สำคัญ หรือการต้องใช้เวลาหลังจากการปล่อยเวอร์ชันเพื่อมานั่งรวบรวมข้อมูล GitHub Actions เข้ามาช่วยแก้ปัญหานี้ด้วยการผูกกระบวนการเข้ากับเหตุการณ์ (Event) ที่เกิดขึ้นใน Git Repository โดยตรง

ข้อดีของการใช้ Automation

• ✓ **ความสม่ำเสมอ:** ทุก Release Notes จะมีรูปแบบที่กำหนดไว้ตายตัว
• ✓ **ลดข้อผิดพลาด:** ข้อมูลถูกดึงจาก Commit Messages หรือ PR Titles โดยตรง
• ✓ **ประหยัดเวลา:** ทีมไม่ต้องเสียเวลาในการจัดทำเอกสาร

การเลือก Trigger ที่เหมาะสมสำหรับ Release Notes

หัวใจของการทำงานอัตโนมัติคือการกำหนดเงื่อนไขที่ถูกต้องในการเริ่มต้น Workflow (Trigger) สำหรับการสร้าง Release Notes เรามักจะต้องการให้มันเกิดขึ้นเมื่อมีการตัดสินใจที่จะ ‘ปล่อย’ ซอฟต์แวร์แล้ว ซึ่งมีสองแนวทางหลักที่ต้องพิจารณาในการ ออกแบบ Workflow และ Trigger ที่เหมาะสมใน GitHub Actions

1. Trigger บน Pull Request Merge (แนะนำ)

นี่คือแนวทางที่ได้รับความนิยมสูงสุด โดย Workflow จะถูกเรียกใช้เมื่อ Pull Request ถูก **Merge** เข้าสู่ Branch เป้าหมาย (เช่น `main` หรือ `release/*`) ซึ่งหมายความว่าโค้ดนั้นได้รับการตรวจสอบและอนุมัติแล้ว

on: 
  push:
    branches:
      - main
    paths-ignore:
      - 'docs/**' # เพื่อไม่ให้รันเมื่อมีการอัปเดตเฉพาะเอกสาร
  workflow_dispatch: # สำหรับการรันด้วยมือ

2. Trigger บน Tag Creation (สำหรับ Production Release)

หากคุณใช้ Git Tagging (เช่น `v1.0.0`) เพื่อระบุการปล่อยเวอร์ชันอย่างเป็นทางการ คุณสามารถตั้ง Trigger ให้ทำงานเมื่อมีการสร้าง Tag ใหม่

on: 
  push:
    tags:
      - 'v*.*.*' # รันเมื่อมีการ push tag ที่ขึ้นต้นด้วย v

การใช้ Action เพื่อดึงข้อมูล Pull Request

เมื่อ Trigger ทำงานแล้ว ขั้นตอนต่อไปคือการรวบรวมข้อมูลการเปลี่ยนแปลง ซึ่งโดยปกติแล้วจะมาจาก Commit Messages หรือ Titles ของ Pull Request ที่ถูก Merge เข้ามาสู่ Branch นั้นๆ เราจะใช้ Action ของชุมชนเพื่อช่วยในการดึงข้อมูลเหล่านี้อย่างมีประสิทธิภาพ

Action ยอดนิยม: `Release Drafter` หรือ `standard-version`

เครื่องมือยอดนิยมสำหรับการสร้าง Release Notes อัตโนมัติคือการใช้ Action ที่วิเคราะห์ Commit Messages ตามหลักการ Conventional Commits (เช่น `feat:`, `fix:`, `docs:`) ซึ่งช่วยให้การจัดหมวดหมู่ใน Release Notes ทำได้ง่ายขึ้น

ตัวอย่าง Workflow การสร้าง Release Notes

นี่คือโครงสร้าง Workflow ที่ใช้การทำงานเมื่อมีการ Push เข้าสู่ `main` และใช้ Action เพื่อสร้างเนื้อหา Release Notes โดยอัตโนมัติ

name: Auto Generate Release Notes

on:
  push:
    branches:
      - main

jobs:
  generate_notes:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Generate Release Notes
        uses: release-drafter/release-drafter@v5
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Create GitHub Release
        uses: release-drafter/action@v5
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

ในตัวอย่างนี้, Action `release-drafter` จะตรวจสอบ Commit Messages ตั้งแต่ Tag ล่าสุดจนถึง HEAD ปัจจุบัน และจัดกลุ่มการเปลี่ยนแปลง จากนั้น Action ตัวที่สองจะใช้ข้อมูลนั้นในการสร้าง Draft Release บน GitHub โดยอัตโนมัติ

ชมตัวอย่างการตั้งค่า

เพื่อให้เห็นภาพการทำงานจริงและการตั้งค่าไฟล์คอนฟิกูเรชัน (เช่น `.github/release-drafter.yml`) ได้ชัดเจนยิ่งขึ้น ลองรับชมวิดีโอนี้ซึ่งอธิบายขั้นตอนอย่างละเอียด

การปรับแต่ง Workflow ให้เหมาะสมกับบริบท

การ ออกแบบ Workflow และ Trigger ที่เหมาะสมใน GitHub Actions ไม่ได้จบแค่การเลือก Action แต่ยังรวมถึงการปรับแต่งเงื่อนไขและการกรองข้อมูลด้วย หากคุณไม่ต้องการให้การอัปเดตเอกสารหรือการแก้ไขเล็กน้อยรันกระบวนการสร้าง Release Notes คุณต้องใช้ `paths-ignore` หรือ `paths-include` ในส่วนของ `on:` trigger

การกำหนดเงื่อนไขด้วย `if` ใน Job

ในบางกรณี คุณอาจต้องการให้ Workflow รันเมื่อมีการ Push แต่จะทำงานเฉพาะเมื่อมีการเปลี่ยนแปลงไฟล์ที่เกี่ยวข้องกับโค้ดเท่านั้น คุณสามารถใช้ Contexts ของ GitHub Actions เพื่อตรวจสอบเงื่อนไขเพิ่มเติมได้

Action ที่ต้องสร้าง Draft Release หรือ Push Tag จำเป็นต้องมีสิทธิ์ในการเขียน Repository นั้นๆ โดยทั่วไป `GITHUB_TOKEN` ที่ GitHub จัดเตรียมให้จะมีสิทธิ์เพียงพอสำหรับการสร้าง Draft Release แต่หากคุณต้องการสร้าง Release โดยตรง คุณอาจต้องใช้ Personal Access Token (PAT) ที่มีสิทธิ์ `repo` และเก็บไว้ใน GitHub Secrets อย่างปลอดภัย

คำถามที่พบบ่อย (FAQ)

เราได้รวบรวมคำถามที่พบบ่อยเกี่ยวกับการตั้งค่า Workflow สำหรับ Release Notes อัตโนมัติไว้ด้านล่างนี้

1. หากฉันไม่ได้ใช้ Conventional Commits Workflow จะยังสร้าง Release Notes ได้หรือไม่?

ได้แน่นอนครับ! หากคุณไม่ใช้ Conventional Commits คุณสามารถใช้ Action อื่นๆ ที่เน้นการดึงข้อมูลจาก Pull Request Title หรือใช้ Action ที่อนุญาตให้คุณกำหนดรูปแบบการดึงข้อมูลที่ซับซ้อนกว่าเดิม หรือแม้กระทั่งใช้ Action ที่ดึงข้อมูลทั้งหมดจาก PR Description แทน

2. Trigger `pull_request` ต่างจาก `push` อย่างไรในการสร้าง Release Notes?

Trigger `pull_request` จะทำงานเมื่อมีการเปิด, อัปเดต, หรือปิด PR แต่ถ้าคุณต้องการให้ Release Notes ถูกสร้างขึ้นทันทีที่โค้ดถูกรวม (Merge) เข้าสู่ `main` การใช้ `push` บน branch ปลายทาง (เช่น `main`) จะเหมาะสมกว่า เพราะมันยืนยันว่าการเปลี่ยนแปลงนั้นถูกผนวกรวมเรียบร้อยแล้ว

3. ฉันจะป้องกันไม่ให้ Workflow รันซ้ำเมื่อมีการสร้าง Release โดยอัตโนมัติ?

หาก Workflow ของคุณสร้าง Release (ซึ่งเป็นการ Push Tag หรือการอัปเดต Release) และคุณตั้ง Trigger ให้รันเมื่อมีการ Push (เช่น `on: push`) มันอาจเกิดการวนลูปได้ วิธีแก้คือการตรวจสอบใน Job ว่าเป็นการ Push ที่เกิดจากการกระทำของ Action เองหรือไม่ โดยการตรวจสอบตัวแปรสภาพแวดล้อม เช่น `github.actor` หรือใช้เงื่อนไข `if: github.actor != ‘github-actions[bot]’`

4. ต้องตั้งค่าไฟล์คอนฟิกูเรชันสำหรับ Release Drafter ที่ไหน?

โดยปกติแล้ว ไฟล์คอนฟิกูเรชันของ `release-drafter` ควรถูกวางไว้ที่รากของ Repository ในชื่อไฟล์ว่า `.github/release-drafter.yml` เพื่อให้ Action สามารถอ่านและนำไปใช้ในการจัดรูปแบบ Release Notes ได้อย่างถูกต้อง

5. การใช้ `workflow_dispatch` ช่วยในการสร้าง Release Notes อย่างไร?

`workflow_dispatch` เป็น Trigger ที่อนุญาตให้ผู้ใช้สามารถรัน Workflow ได้ด้วยตนเองผ่านหน้า GitHub UI ซึ่งมีประโยชน์อย่างยิ่งหากคุณต้องการสร้าง Release Notes สำหรับเวอร์ชันเก่าที่ถูก Tag ย้อนหลัง หรือต้องการตรวจสอบการตั้งค่า Workflow โดยไม่ต้องรอการ Merge PR จริง

References

เอกสาร GitHub Actions Events

GitHub Repository สำหรับ Release Drafter