GitHub Actions schedule이 실행되지 않을 때 확인 순서

GitHub Actions에서 수동 실행은 되는데 예약 실행만 생기지 않는다면 job 코드보다
먼저 실행 시각, 기본 브랜치, workflow 활성화 상태를 확인하세요. 특히 매시
정각의 cron은 부하로 늦어지거나 누락될 수 있으므로, 한국 시간을 명시하고 정각을
피한 분으로 바꾸는 것이 가장 빠른 첫 조치입니다.

먼저 실행이 없었는지, 늦었는지 구분하세요

저장소의 Actions 탭에서 해당 workflow를 선택한 뒤 예정 시각 전후의 실행
기록을 확인합니다. 실행 기록이 있고 시작 시각만 늦었다면 스케줄러 지연이고,
기록 자체가 없다면 cron 해석, 기본 브랜치 또는 비활성화 문제부터 봐야 합니다.
실행 기록이 생성된 뒤 job이 빨간색으로 실패한 경우에는 schedule 트리거가 아니라
실패한 step의 로그를 진단해야 합니다.

보이는 상태	먼저 확인할 항목	판단
실행 기록이 전혀 없음	시간대, 기본 브랜치, workflow 활성화	트리거 문제 가능성이 큼
예정 시각보다 늦게 실행됨	매시 정각 여부와 GitHub Status	예약은 됐지만 지연됨
workflow_dispatch만 실행됨	schedule 등록 조건과 기본 브랜치	job 코드는 대체로 정상
실행 기록이 있고 job이 실패함	실패한 step 로그	schedule은 정상 작동
workflow에 Enable workflow가 보임	수동 또는 자동 비활성화	다시 활성화해야 함
담당자 계정 변경 뒤 예약만 멈춤	schedule의 마지막 actor 계정	Enterprise Managed Users 환경이면 계정 상태 확인

가장 빠른 해결 순서

아래 순서에서는 코드를 지우거나 Secret을 바꾸지 않습니다. 한 단계씩 확인한 뒤
다음 예정 시각 또는 수동 실행 결과를 기록하면 원인을 섞지 않고 좁힐 수 있습니다.

1. cron이 의도한 시간대와 요일인지 확인합니다.
2. workflow 파일이 저장소의 기본 브랜치에 있는지 확인합니다.
3. Actions 화면에서 workflow가 활성화되어 있는지 확인합니다.
4. Enterprise Managed Users 조직이면 마지막 actor 계정이 활성 상태인지 확인합니다.
5. 매시 정각을 피한 분으로 바꾸고 다음 실행을 기다립니다.
6. workflow_dispatch를 추가해 job 자체가 실행되는지 분리합니다.
7. 한 번의 누락도 허용할 수 없다면 대상 workflow 밖에 실행 감시와 대체 트리거를 둡니다.

한국 시간과 cron 표현을 먼저 바로잡으세요

GitHub의 schedule 이벤트 문서에
따르면 별도 시간대를 적지 않은 예약 workflow는 UTC를 기준으로 실행됩니다.
현재 문법은 IANA 시간대 문자열도 지원하므로 한국 시간 기준이라면
timezone: "Asia/Seoul"을 명시할 수 있습니다.

GitHub가 timezone 지원을 발표한 시점은
2026년 3월 19일입니다.
따라서 검색 결과나 예전 예제에서 “schedule은 UTC만 지원한다”고 설명하더라도
현재 GitHub.com 문법의 근거로 사용하지 마세요. 기존 UTC cron은 그대로 둘 수
있지만, 한국 시각으로 유지할 workflow라면 시간대를 명시해 계산 실수를 줄일 수
있습니다.

평일 오전 9시 17분에 실행하고 수동 진단 버튼도 남기는 예시는 다음과 같습니다.

on:
  workflow_dispatch:
  schedule:
    - cron: "17 9 * * 1-5"
      timezone: "Asia/Seoul"

17분을 사용한 이유는 cron 문법 때문이 아니라 매시 정각의 부하를 피하기
위해서입니다. @daily, @hourly 같은 비표준 축약 문법은 지원되지 않으며,
예약 실행의 최소 간격은 5분입니다. 시간대를 명시하지 않는 기존 workflow라면
한국 표준시가 UTC보다 9시간 빠르다는 점을 반영해 의도한 시각을 다시 계산하세요.

workflow 파일은 기본 브랜치에 있어야 합니다

schedule 이벤트는 feature 브랜치에 파일이 있어도 그 브랜치에서 실행되지 않습니다.
GitHub 공식 문제 해결 문서는
schedule이 기본 브랜치의 workflow 파일에서만 트리거된다고 설명합니다. 실행할
때도 기본 브랜치의 최신 커밋을 사용합니다.

먼저 저장소의 Settings → Branches 또는 저장소 첫 화면의 브랜치 선택기에서
기본 브랜치 이름을 확인하세요. 그다음 기본 브랜치에 대상 파일이 실제로 있는지
확인합니다.

.github/
└─ workflows/
   └─ daily-report.yml

로컬 복사본에서는 다음 명령으로 현재 브랜치와 추적 중인 원격 브랜치를 읽을 수
있습니다.

git branch --show-current
git status -sb
git remote get-url origin

현재 브랜치가 기본 브랜치가 아니라면 그 사실만으로 schedule이 등록됐다고
판단하지 마세요. workflow 파일을 기본 브랜치에 반영하는 변경은 반드시 저장소의
일반 검토 절차를 거쳐야 합니다.

비활성화된 workflow를 다시 켜세요

workflow 파일을 삭제하지 않아도 Actions 화면에서 개별 workflow를 끌 수 있습니다.
해당 workflow 화면에 Enable workflow가 보이면 활성화한 뒤 다음 예약 시각을
확인하세요. GitHub CLI를 사용한다면 이름이나 파일명을 정확히 확인한 뒤 다음
명령으로 활성화할 수 있습니다.

gh workflow enable daily-report.yml

GitHub의 workflow 활성화 문서는
공개 저장소에 60일 동안 저장소 활동이 없으면 예약 workflow가 자동으로
비활성화될 수 있고, 공개 저장소를 fork하면 예약 workflow가 기본적으로
비활성화된다고 안내합니다. 이 규칙을 비공개 저장소에도 그대로 적용해 원인을
단정하지 마세요.

활성화 전에 workflow가 외부 API 호출, 배포 또는 비용이 생기는 작업을 수행하는지
확인해야 합니다. 원인을 찾는 동안에는 운영 workflow 대신 민감 정보와 외부 쓰기가
없는 테스트 workflow를 사용하는 편이 안전합니다.

조직에서 담당자가 바뀌었다면 schedule actor를 확인하세요

GitHub의 schedule 이벤트 문서는
기본 브랜치를 바꾼 사용자가 예약 workflow의 actor가 된다고 설명합니다.
비활성화된 예약에서는 쓰기 권한이 있는 사용자가 cron을 변경해 커밋하면 workflow가
다시 활성화되고 그 사용자가 actor가 됩니다. 예약 실행 알림도 cron 문법을
마지막으로 수정한 사용자에게 전송됩니다.

Enterprise Managed Users를 사용하는 기업이라면 이 actor 계정이 IdP에서
비활성화되거나 삭제됐을 때 예약 workflow가 실행되지 않습니다. 반면 일반 조직에서
사용자를 조직 구성원에서 제거했다는 사실만으로 그 사용자가 actor인 예약 실행이
멈추는 것은 아닙니다. 따라서 담당자 퇴사나 계정 이전 뒤 문제가 시작됐더라도 모든
조직에 같은 원인을 적용하지 말고, 먼저 엔터프라이즈 관리자에게 계정 유형과 활성
상태를 확인하세요.

Enterprise Managed Users 환경에서 마지막 actor가 비활성 상태이고 workflow도
비활성화되어 있다면, 현재 활성 사용자가 일반 코드 검토 절차를 거쳐 cron 변경을
반영한 뒤 다음 예약 실행을 관찰할 수 있습니다. workflow가 비활성화된 상태가
아니라면 actor를 바꾸려고 의미 없는 커밋이나 기본 브랜치 변경을 반복하지 말고,
저장소·workflow 경로·cron·actor 상태를 정리해 GitHub 지원에 확인하세요.

매시 정각 지연과 누락 가능성을 고려하세요

GitHub는 Actions 실행 부하가 높은 시간에는 schedule 이벤트가 늦어질 수 있고,
부하가 충분히 높으면 대기 중인 일부 작업이 누락될 수 있다고 명시합니다. 특히
매시 정각은 부하가 높은 시간으로 안내되어 있습니다.
GitHub Actions 트리거 문제 해결

따라서 다음처럼 0분에 몰린 예약을 정각이 아닌 분으로 분산합니다.

on:
  schedule:
    - cron: "23 * * * *"
      timezone: "Asia/Seoul"

이는 매시간 23분에 실행을 요청하는 설정이지 정확히 그 시각에 시작된다는 보장은
아닙니다. 결제 마감, 보안 대응, 데이터 백업처럼 한 번의 누락도 허용하기 어려운
작업은 GitHub Actions 예약만으로 충족할 수 있는지 별도 신뢰성 요구사항을 먼저
검토하세요.

누락을 허용할 수 없다면 외부 감시를 분리하세요

정각을 피하는 조치는 지연 가능성을 낮출 뿐 누락 방지 장치가 아닙니다. GitHub는
부하가 충분히 높으면 일부 대기 작업이 누락될 수 있다고 명시하므로, 마감 시각이나
복구 목표가 있는 작업을 schedule 하나에만 맡기면 안 됩니다.

작업 성격	권장 구성
보고서·캐시 갱신처럼 지연을 허용	정각을 피한 schedule과 실행 기록 확인
누락 시 사람이 재실행해도 됨	schedule과 workflow_dispatch, 누락 알림
정해진 시간 안에 반드시 시작해야 함	GitHub 밖의 스케줄러·감시와 workflow_dispatch, 별도 실패 알림

누락 감시를 대상 workflow의 같은 schedule job에 넣으면 그 예약 자체가 호출되지
않았을 때 경고도 실행되지 않습니다. 별도 시스템에서 최근 schedule 실행 시각을
조회하고, 정상 간격과 허용 지연을 합친 기준보다 오래됐을 때 알리도록 구성하세요.
아래 읽기 전용 PowerShell 예시는 최근 실행의 생성 시각이 90분보다 오래됐는지만
확인합니다. 90은 예시이므로 실제 예약 간격보다 길게 조정해야 합니다.

$workflowFile = "daily-report.yml"
$maxAgeMinutes = 90
$runs = gh run list --workflow $workflowFile --event schedule --all --limit 1 --json createdAt,url |
    ConvertFrom-Json

if (-not $runs -or $runs.Count -eq 0) {
    throw "schedule 실행 기록이 없습니다."
}

$lastCreated = [DateTimeOffset]::Parse($runs[0].createdAt)
$ageMinutes = ([DateTimeOffset]::UtcNow - $lastCreated).TotalMinutes

if ($ageMinutes -gt $maxAgeMinutes) {
    throw ("최근 schedule 실행이 {0:N0}분 전입니다: {1}" -f $ageMinutes, $runs[0].url)
}

외부 스케줄러가 대체 실행까지 요청해야 한다면 GitHub의
Create a workflow dispatch event를
사용할 수 있습니다. 대상 workflow에는 workflow_dispatch가 있어야 하며,
fine-grained 토큰에는 해당 저장소의 Actions: write 권한이 필요합니다. 토큰은
대상 저장소로 범위를 제한하고 외부 스케줄러의 Secret 저장소에만 보관하며 URL,
로그 또는 workflow 파일에 넣지 마세요. 외부 요청이 접수돼도 이후 queue와 runner
시작까지 보장하는 것은 아니므로, 실행 생성 여부와 완료 상태도 따로 감시해야 합니다.

수동 실행으로 job 오류와 트리거 문제를 나누세요

workflow_dispatch를 함께 추가하면 Actions 화면의 Run workflow로 같은 job을
수동 실행할 수 있습니다. 이 버튼을 쓰려면 workflow 파일이 기본 브랜치에 있고,
실행하는 사용자에게 쓰기 권한이 있어야 합니다.
GitHub의 workflow 수동 실행 문서

수동 실행이 성공하고 schedule 실행만 없다면 runner 이미지, 설치 명령, Secret보다
앞의 시간대·기본 브랜치·활성화·부하 조건을 먼저 확인하세요. 수동 실행도 실패하면
예약 문제가 아니라 실패한 job과 step의 로그를 기준으로 진단합니다.

GitHub CLI로 활성 상태와 예약 실행 기록을 확인하세요

Actions 화면만 보고 판단하기 어렵다면 GitHub CLI의 읽기 명령으로 기본 브랜치,
workflow 상태, 최근 schedule 실행을 한 번에 확인할 수 있습니다. 아래 명령은
workflow를 실행하거나 설정을 바꾸지 않으며, 저장소 주소와 공개 가능한 실행
메타데이터만 출력합니다.

gh repo view --json nameWithOwner,defaultBranchRef
gh workflow list --all --json name,path,state
gh run list --workflow daily-report.yml --event schedule --all --limit 10 --json createdAt,startedAt,status,conclusion,headBranch,url

daily-report.yml은 실제 workflow 파일명으로 바꾸세요. 저장소 정보 명령은
기본 브랜치를 반환합니다. GitHub CLI는 기본적으로
비활성 workflow를 목록에서 숨기므로, workflow 목록 명령에
문서화된 --all을 붙여 비활성 상태도 확인합니다. 최근 실행은
run 목록 명령의
--event schedule로 수동 실행을 제외합니다.

확인 결과	해석과 다음 행동
defaultBranchRef와 workflow가 있는 브랜치가 다름	기본 브랜치에 검토된 workflow 변경을 반영
state가 active가 아님	비활성화 원인을 확인한 뒤 안전성을 검토하고 활성화
schedule 실행의 createdAt이 예정 시각보다 늦음	트리거 지연으로 기록하고 정각을 피한 시간으로 조정
createdAt은 가깝지만 startedAt이 늦음	실행 생성 뒤 queue 또는 runner 시작 지연을 분리해 기록
최근 예정 시각 이후 schedule 실행이 전혀 없음	cron·기본 브랜치·활성화·actor·GitHub Status 정보를 모아 지원 문의

그래도 예약 실행이 생기지 않을 때 모을 정보

GitHub Status에 Actions 장애가 있었는지 확인한
뒤, 지원 요청에는 다음 정보만 정리합니다.

• 저장소 공개·비공개 여부와 fork 여부
• 기본 브랜치 이름과 workflow 파일 경로
• on.schedule 부분의 cron 및 timezone
• workflow 활성화 상태
• GitHub CLI로 확인한 기본 브랜치, workflow state, 최근 schedule 실행의 createdAt과 startedAt
• Enterprise Managed Users 사용 여부와 마지막 actor 계정의 활성 상태
• 마지막으로 정상 예약 실행된 시각
• 기대 시각과 실제 생성 시각 또는 누락된 횟수
• workflow_dispatch 성공 여부

Secret 값, 토큰, 전체 환경 변수와 비공개 로그는 질문이나 화면 캡처에 넣지 마세요.
실행 기록이 전혀 없으면 job 로그도 생성되지 않으므로, 존재하지 않는 로그를 찾는
대신 위의 트리거 정보를 전달하는 편이 유용합니다.

자주 묻는 질문

cron은 항상 UTC로 계산되나요?

시간대를 쓰지 않으면 기본값은 UTC입니다. 현재 GitHub Actions schedule 문법에서는
timezone: "Asia/Seoul"처럼 IANA 시간대를 명시할 수 있으므로, 한국 시각 기준
workflow는 cron과 함께 시간대를 적는 편이 읽고 유지하기 쉽습니다.

5분마다 설정하면 정확히 5분마다 실행되나요?

아닙니다. 5분은 설정할 수 있는 가장 짧은 간격이며 정시 실행 보장이 아닙니다.
GitHub의 실행 부하에 따라 지연되거나 일부 실행이 누락될 수 있습니다.

수동 실행은 되는데 schedule만 안 되는 이유는 무엇인가요?

job 자체보다 schedule 전용 조건을 먼저 봐야 합니다. workflow가 기본 브랜치에
있는지, 한국 시간으로 해석한 cron이 맞는지, 비활성화되지 않았는지, 매시 정각에
몰리지 않았는지 순서대로 확인하세요.

정리

GitHub Actions 예약 실행이 보이지 않으면 Asia/Seoul 시간대와 cron을 먼저
확인하고, 기본 브랜치의 workflow인지와 활성화 상태를 점검하세요. 그다음 정각을
피한 분으로 조정하고 수동 실행으로 job 오류와 트리거 문제를 분리하면 됩니다.

schedule뿐 아니라 push 실행도 전혀 생기지 않는다면 GitHub Actions가 push 후
실행되지 않을 때 확인할 7가지에서
파일 위치와 브랜치·경로 필터까지 이어서 확인하세요.