GitHub Actions에서 배포 워크플로우 중복 실행을 어떻게 제어할까

|

GitHub Actions에서 배포 워크플로우 중복 실행을 어떻게 제어할까

같은 브랜치에 푸시가 연속으로 들어올 때 배포 워크플로우가 중복 실행되는 문제는 concurrency 키워드로 제어할 수 있습니다. 그런데 cancel-in-progress: true만 설정하면 실행 중인 배포가 강제 취소되고, cancel-in-progress 없이 기본값만 쓰면 대기 중인 실행이 덮어씌워집니다. 이 글은 세 가지 동작 모드의 차이를 명확히 구분하고, 배포 환경별로 어떤 설정을 선택해야 하는지 판단 기준을 제시합니다.

Concurrency – GitHub Actions Concepts 공식 문서 화면

concurrency 키워드가 없을 때 기본 동작

GitHub Actions는 기본적으로 동일 워크플로우의 여러 실행을 동시에 허용합니다. 공식 문서에 따르면 "multiple workflow runs within the same repository… to run concurrently"가 기본값입니다. main 브랜치에 커밋이 세 개 연속으로 푸시되면 배포 잡이 세 개 동시에 실행될 수 있고, 각 실행이 같은 환경에 쓰기를 시도하면 충돌이 발생합니다. concurrency를 설정하지 않은 채로 운영하면 CI 비용 증가와 환경 오염 위험이 함께 옵니다. [1]

  • 기본: 동일 워크플로우의 여러 실행이 동시에 가능
  • 설정 없이 연속 푸시 → 배포 잡 중복 실행 가능
  • 환경 쓰기 충돌·리소스 낭비 위험

cancel-in-progress: true — 실행 중인 잡을 즉시 취소

concurrency 그룹에 cancel-in-progress: true를 추가하면, 새 실행이 대기열에 들어오는 순간 현재 실행 중인 잡이 취소됩니다. 공식 문서 예시는 다음과 같습니다.

“`yaml
on:
push:
branches:
– main
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
“`

이 설정은 오래된 커밋에 대한 린트나 테스트처럼 최신 결과만 필요한 작업에 적합합니다. 반면 배포처럼 중간에 멈추면 환경이 반쪽 상태로 남을 수 있는 작업에는 주의가 필요합니다. 실행 중인 배포가 강제 취소되면 롤백 절차나 상태 복구 작업이 별도로 필요할 수 있으므로, 팀이 이 위험을 감수할 수 있는지 먼저 판단하십시오. [2]

  • 새 실행 큐 진입 시 현재 실행 중인 잡 즉시 취소
  • 린트·테스트처럼 최신 결과만 필요한 잡에 적합
  • 배포 잡에 적용 시 반쪽 상태 위험 — 팀 판단 필요

기본 동작 — 대기 실행 하나만 유지

cancel-in-progress를 명시하지 않으면 concurrency 그룹은 기본 동작을 따릅니다. 공식 문서에 따르면 "by default, any existing pending job or workflow in the same concurrency group will be canceled and the new queued job or workflow will take its place"입니다. 즉, 실행 중인 잡은 완료될 때까지 보호되지만 대기 중인 실행은 최신 것 하나만 남고 나머지는 취소됩니다.

“`yaml
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
# cancel-in-progress 생략 → 기본값
“`

커밋 A가 배포 중이고 커밋 B·C가 연속으로 푸시된 경우, A 완료 후에는 C만 배포되고 B는 취소됩니다. 중간 커밋이 반드시 배포되어야 하는 환경에서는 이 동작이 문제가 될 수 있습니다. [2]

  • 실행 중인 잡은 완료까지 보호
  • 대기 중인 실행은 최신 하나만 유지, 나머지 취소
  • 중간 커밋 배포가 필수인 환경에서는 별도 검토 필요
광고

queue: max — 최대 100개 실행을 순서대로 대기

모든 실행을 순서대로 빠짐없이 처리해야 한다면 queue: max를 사용합니다. 공식 문서 설명은 다음과 같습니다: "Up to 100 jobs or workflow runs can be pending in the concurrency group. When the queue is full, any additional jobs or workflow runs are canceled."

“`yaml
on:
push:
branches:
– main
concurrency:
group: production-deploy
queue: max
“`

이 설정은 프로덕션 배포처럼 각 커밋이 순서대로 반영되어야 하는 환경에 적합합니다. 공식 문서에 따르면 잡은 "first-in-first-out (FIFO) order according to the time each one started waiting on the concurrency group"으로 처리됩니다. 단, 실제 시작 시간의 편차 때문에 순서가 완전히 보장되지 않을 수 있다는 점도 문서에 명시되어 있습니다. [2]

  • 최대 100개 실행 대기 가능
  • 101번째 이후 실행은 취소
  • FIFO 순서 처리 — 단, 완전한 순서 보장은 아님

queue: max와 cancel-in-progress: true 동시 사용 금지

공식 문서는 이 조합을 명확히 금지합니다: "The combination of queue: max and cancel-in-progress: true is not allowed and will result in a workflow validation error." 두 옵션은 실행 중인 잡을 처리하는 방식이 서로 충돌하기 때문입니다. queue: max는 실행 중인 잡을 보호하면서 대기를 쌓고, cancel-in-progress: true는 실행 중인 잡을 즉시 취소합니다. 워크플로우 파일에 두 옵션을 함께 작성하면 유효성 검사 오류가 발생하며 실행 자체가 시작되지 않습니다. [2]

  • queue: max + cancel-in-progress: true → 워크플로우 유효성 검사 오류
  • 두 옵션은 서로 충돌하는 동작을 정의하므로 함께 사용 불가
  • 오류 발생 시 실행 자체가 시작되지 않음

브랜치별 조건부 취소 — release 브랜치 보호

개발 브랜치에서는 최신 실행만 필요하지만 릴리즈 브랜치에서는 모든 실행을 완료해야 하는 경우, cancel-in-progress에 조건식을 사용할 수 있습니다.

“`yaml
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: ${{ !contains(github.ref, 'release/') }}
“`

공식 문서 설명에 따르면 "multiple pushes to a release/1.2.3 branch would not cancel in-progress runs. Pushes to another branch, such as main, would cancel in-progress runs." 이 패턴은 릴리즈 브랜치의 안전성을 유지하면서 개발 브랜치의 불필요한 실행을 정리하는 데 유용합니다. [2]

  • release/* 브랜치: cancel-in-progress 비활성 → 실행 중인 잡 보호
  • main 등 개발 브랜치: cancel-in-progress 활성 → 최신 실행 우선
  • 조건식에 허용된 컨텍스트: github, inputs, vars, needs, strategy, matrix

설정 선택 기준과 검토 경계

세 가지 모드를 정리하면 다음과 같습니다. 린트·테스트처럼 최신 결과만 필요한 잡은 cancel-in-progress: true가 가장 간결합니다. 배포처럼 실행 중인 잡을 보호해야 하되 최신 대기 하나만 유지해도 되는 경우는 cancel-in-progress를 생략한 기본 동작이 적합합니다. 모든 커밋을 순서대로 반영해야 하는 프로덕션 배포는 queue: max를 사용합니다.

검토 경계: concurrency 그룹 이름은 대소문자를 구분하지 않습니다('prod'와 'Prod'는 같은 그룹). 여러 워크플로우가 같은 저장소에 있다면 그룹 이름이 겹치지 않도록 ${{ github.workflow }}를 포함시키는 것이 안전합니다. 조직 또는 엔터프라이즈 단위로 GitHub 호스팅 러너에서 현재 처리 중인 잡 수는 GitHub 공식 문서의 'Viewing your current jobs' 페이지에서 확인할 수 있습니다. [1], [2]

  • 린트·테스트 → cancel-in-progress: true
  • 배포(최신 하나만 필요) → cancel-in-progress 생략한 기본 동작
  • 배포(모든 커밋 순서 필요) → queue: max
  • 그룹 이름은 ${{ github.workflow }}-${{ github.ref }} 패턴으로 고유하게 유지
  • queue: max 사용 시 대기 101번째 이후는 자동 취소 — 모니터링 필요

참고한 자료

  1. Concurrency – GitHub Actions Concepts
  2. Control the concurrency of workflows and jobs – GitHub Docs

자료 확인 기준

2026년 11월 19일에 공식 원문을 확인했습니다. 자료는 이후 수정될 수 있으므로 세부 내용은 원문을 확인해 주세요.

배포 설정을 팀의 완료 기준에 넣기

중복 실행을 막는 설정을 적용했다면, 누가 언제 확인할지도 정해야 반복 배포에서 빠지지 않습니다. 배포 전 검증과 운영 책임을 문장으로 정리하는 방법은 팀의 완료 기준(DoD) 글에서 이어서 볼 수 있습니다.


cms world에서 더 알아보기

구독을 신청하면 최신 게시물을 이메일로 받아볼 수 있습니다.

응답

  1. […] 추상적인 문장에 머물지 않게 하려면 실제 배포 문제에 대입해 보세요. GitHub Actions 배포 중복 실행 제어는 동시 실행 정책, 대기 작업, 취소 조건을 팀이 확인할 항목으로 바꾸는 […]

답글 남기기