수동으로 배포 버전을 선택해서 실행하고 싶을 때 workflow_dispatch

문제 발생

특정 커밋을 골라서 수동으로 스테이징 환경에 배포하고 싶은데, 워크플로우가 push 트리거로만 되어 있어 매번 임시 브랜치를 만들고 push해야만 실행할 수 있었습니다.

원인 분석

GitHub Actions의 대부분의 트리거(push, pull_request 등)는 저장소에서 일어나는 이벤트에 자동으로 반응합니다. 하지만 "사람이 직접, 원하는 시점에, 원하는 값을 입력해서" 실행해야 하는 워크플로우(수동 배포, 특정 버전 릴리스, 일회성 마이그레이션 스크립트 실행 등)는 이런 자동 트리거로 표현하기 어렵습니다.

해결 방안

workflow_dispatch 트리거를 쓰면 GitHub Actions 탭에서 "Run workflow" 버튼으로 수동 실행할 수 있고, inputs로 실행 시 필요한 값을 입력받을 수 있습니다.

on:
  workflow_dispatch:
    inputs:
      environment:
        description: "배포할 환경"
        required: true
        type: choice
        options: [staging, production]
      version:
        description: "배포할 이미지 태그"
        required: true
        type: string

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying ${{ inputs.version }} to ${{ inputs.environment }}"

1. type: choice로 입력값을 정해진 목록 중에서만 고르게 강제할 수 있습니다 — 오타로 잘못된 값이 들어가는 것을 방지합니다.
2. production처럼 민감한 environment를 선택지에 포함한다면, GitHub의 Environment protection rules(승인자 지정, 특정 브랜치에서만 배포 허용 등)와 함께 조합해 실수로 아무나 프로덕션에 배포하지 못하도록 이중으로 막을 수 있습니다.
3. GitHub CLI로도 실행할 수 있어, 사람이 웹 UI를 열지 않고도 스크립트에서 트리거할 수 있습니다.

gh workflow run deploy.yml -f environment=staging -f version=sha-abc1234

4. workflow_dispatch는 push/schedule 등 다른 트리거와 함께 같은 워크플로우 파일에 공존시킬 수 있습니다 — "평소엔 자동, 필요하면 수동으로도"라는 조합이 가능합니다.

공식 문서

• GitHub Actions Docs: Events that trigger workflows — workflow_dispatch
• GitHub Actions Docs: Manually running a workflow