GitHub Actions 작성자를 위한 자동 버전 관리

Source: Dev.to

위에 제공된 소스 링크 외에 번역할 텍스트가 포함되어 있지 않습니다. 번역을 원하는 본문을 알려주시면 한국어로 번역해 드리겠습니다.

개요

세 개의 GitHub Actions를 유지보수하는 입장에서 버전 관리가 늘 조금은 어려웠습니다. GitHub 문서에는 가이드가 있지만, 모든 것이 올바른지 쉽게 검증할 방법이 없습니다. 마켓플레이스를 빠르게 살펴보면 저만 그런 것이 아니라 GitHub 자체 액션들조차 일관성이 부족한 경우가 있음을 알 수 있습니다.

그래서 저는 몇 년 전 v1 버전의 Actions Semver Checker를 급히 만들었습니다. 제게는 충분히 잘 작동했지만, 초기 구현에는 몇 가지 버그가 있었고 유지보수가 어려웠으며, 변경 사항마다 무언가를 깨뜨렸는지 쉽게 테스트할 수 없었기 때문에 위험하게 느껴졌습니다.

v1에서 v2로

저는 Copilot Agent에게 v1 코드를 청사진으로 사용하고 다음 제약 조건을 적용해 리팩터링하도록 요청했습니다:

저는 Copilot에게 관련 GitHub 문서와 블로그(CLI 릴리스 명령, Releases REST API, Tags REST API, GraphQL API, 불변 릴리스, Actions 버전 관리) 링크를 제공했습니다. Claude Opus가 상세한 계획을 생성하도록 도왔고, 저는 그 계획을 약간 수정한 뒤 Copilot이 약 45분 동안 코딩하도록 했습니다.

그 결과는 first‑vibe‑coded GitHub Action으로, 대부분 필요한 기능을 수행했으며 계획의 몇몇 공백을 드러내고 두 구현 사이에 흥미로운 얽힘을 만들었습니다.

90개 이상의 테스트로 구성된 테스트 스위트를 만든 뒤, 저는 동작을 조정하는 데 자신감을 얻었습니다. Copilot과 여러 차례 주고받으며 VS Code에서 직접 작업한 결과, GitHub Actions Semver Checker의 v2를 자랑스럽게 출시하게 되었습니다.

액션이 수행하는 작업

액션은 GitHub Action을 호스팅하는 저장소 내부에 설치되는 것을 목표로 합니다(예: actions/checkout 또는 jessehouwing/actions-semver-checker). 모든 브랜치, 태그 및 릴리스를 분석하고 일련의 규칙에 따라 검증합니다.

핵심 검증 규칙 (v1)

새로운 검증 규칙 (v2)

대부분의 검증에 대해 autofix 옵션이 발견된 문제를 자동으로 수정합니다. 액션이 문제를 수정할 수 없는 경우, 워크플로우 요약 페이지에 수동 해결 단계가 기록됩니다.

Autofix 기능

추가 개선 사항

• 구성 가능한 규칙 스위트 – 실행할 규칙 그룹을 선택합니다.
• 전체 체크아웃 불필요 – 이 액션은 전체 리포지토리를 체크아웃할 필요가 없습니다.
• 재시도 및 속도 제한 처리 – API 속도 제한에 대한 내장 재시도 로직.
• PowerShell Gallery 모듈 – PowerShell Gallery에서 모듈로 제공됩니다.

중단되는 변경 사항 (v1 → v2)

이제 비밀 ${{ secrets.GITHUB_TOKEN }}을 액션의 token: 입력에 전달해야 합니다.

시작하기

1. 액션을 설치 하여 기본 설정으로 액션 저장소에 추가합니다. 그러면 저장소를 분석하고 규칙 위반 사항을 보고합니다.

2. 설정을 조정 하여 원하는 동작에 맞춥니다:

예시 워크플로우

name: Check SemVer

on:
  push:
    branches: ['main']
    tags:
      - '*'
  workflow_dispatch:

permissions: {}

jobs:
  check-semver:
    permissions:
      contents: write   # needed for validations & autofix
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
      cancel-in-progress: true
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository (shallow)
        uses: actions/checkout@v4
        with:
          fetch-depth: 1   # no need for full history

      - name: Run SemVer Checker (v2)
        uses: jessehouwing/actions-semver-checker@v2
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          floating-versions-use: tags
          check-minor-version: warning
          check-releases: error
          check-release-immutability: warning
          ignore-preview-releases: true
          ignore-versions: |
            0.0.1
            1.0.0-beta

요약

• v2는 많은 새로운 검증 규칙과 강력한 자동 수정 시스템을 추가합니다.
• 이 액션은 완전하게 구성 가능하며, 전체 체크아웃이 필요 없고, 재시도 및 속도 제한 처리를 포함합니다.
• PowerShell Gallery 모듈로 제공되며, v1과 나란히 실행되어 쉽게 비교할 수 있습니다.

자유롭게 사용해 보시고, 워크플로에 맞게 입력을 조정한 뒤, 이 액션이 GitHub Action 릴리스를 깨끗하고 일관되며 불변하게 유지하도록 하세요!

GitHub Workflow Example

# Example job fragment
{{ github.workflow }}:
  cancel-in-progress: true

  runs-on: ubuntu-latest

  steps:
    - uses: jessehouwing/actions-semver-checker@v2
      with:
        token: ${{ secrets.GITHUB_TOKEN }}
        check-release-immutability: none

⚠️ Important:
autofix 를 켜기 전에 check-release-immutability 설정을 매우 주의해서 사용하세요. 대부분의 자동 수정은 Git 명령줄을 사용하면 쉽게 되돌릴 수 있지만, 릴리즈가 불변으로 설정되면 되돌릴 방법이 없습니다.

1️⃣ Clean up existing tags

기존 태그를 정리하고 그 영향에 대해 충분히 이해한 뒤, 릴리즈 불변성 검사를 활성화합니다:

steps:
  - uses: jessehouwing/actions-semver-checker@v2
    with:
      token: ${{ secrets.GITHUB_TOKEN }}
      check-release-immutability: error

2️⃣ Run in read‑only mode

잠시 동안 읽기 전용 모드로 액션을 사용하면서, 제안된 수정 단계를 수동으로 수행합니다.

3️⃣ Enable autofix (optional)

액션이 원하는 대로 동작한다는 확신이 서면 autofix 를 켜는 것을 고려하세요:

steps:
  - uses: jessehouwing/actions-semver-checker@v2
    with:
      token: ${{ secrets.GITHUB_TOKEN }}
      autofix: true

How it works with autofix

autofix 를 켜면 새 버전을 릴리즈하고 모든 태그와 릴리즈를 업데이트하기 위해 새 태그를 푸시 하는 것(vX.Y.Z 등)만 하면 됩니다. 그러면 액션이 다음을 수행합니다:

1. 올바른 이름으로 새 릴리즈를 생성합니다.
2. 모든 관련 태그를 자동으로 업데이트합니다.

이게 전부입니다—추가적인 수동 단계가 필요하지 않습니다!