Toolsolve

AI·IT 문제 해결 가이드

홈으로

•

GitHub Actions가 push 후 실행되지 않을 때 확인할 7가지

GitHub에 정상적으로 push했는데 Actions에 새 실행 기록조차 생기지 않는다면
코드 오류보다 workflow 트리거 조건을 먼저 확인해야 합니다. Actions
화면에 실행 기록이 있으면 작업 실패이고, 기록이 전혀 없으면 파일 위치,
브랜치·경로 필터, 커밋 메시지 또는 workflow 상태 문제일 가능성이 큽니다.

먼저 실행 기록이 없는지 확인하세요

저장소의 Actions 탭을 열고 해당 workflow를 선택합니다. 방금 push한
커밋의 실행 기록이 있지만 빨간색으로 실패했다면 트리거는 정상 작동한
것입니다. 이때는 실패한 job과 step의 로그를 확인해야 합니다.

아래처럼 실행 상세 화면에 상태와 job이 표시된다면 workflow 트리거는
정상적으로 작동한 것입니다. 성공했다면 추가 조치가 필요 없고, 실패했다면
실패한 job을 열어 로그를 확인합니다.

GitHub Actions에서 push로 실행된 workflow의 성공 상태와 build·deploy 작업을 확인하는 화면

반대로 새로운 실행 기록이 하나도 없다면 아래 표처럼 접근하는 편이 빠릅니다.

보이는 상태 먼저 확인할 항목
workflow 자체가 목록에 없음 파일 위치와 YAML 문법
workflow는 있지만 새 실행이 없음 on, branches, paths, 커밋 메시지
workflow가 비활성화됨 Actions 화면의 Enable workflow
실행 기록이 있고 실패함 실패한 job의 로그와 Secrets

GitHub의 workflow 문제 해결 문서도
트리거 문제와 실행 중 실패를 구분해 확인하도록 안내합니다.

push 후 실행 기록 없음과 실행 실패를 구분하는 점검 흐름

1. workflow 파일 위치를 확인하세요

GitHub Actions workflow는 저장소의 .github/workflows/ 디렉터리에 있는
.yml 또는 .yaml 파일로 작성해야 합니다. 파일을 다른 폴더에 만들었거나
폴더 이름을 .github/workflow처럼 단수로 작성하면 workflow로 인식되지
않습니다.

정상적인 예시는 다음과 같습니다.

.github/
└─ workflows/
   └─ validate.yml

파일 위치가 맞다면 YAML의 들여쓰기와 on, jobs, steps 구조도
GitHub Actions workflow 문법과
비교합니다. Actions 탭에 workflow 자체가 나타나지 않는다면 이 단계부터
확인하는 것이 좋습니다.

2. 실제로 push한 브랜치를 확인하세요

다음 설정은 main 브랜치에 push할 때만 실행됩니다.

on:
  push:
    branches:
      - main

로컬에서 작업 중인 브랜치가 feature/test라면 GitHub에 push가 성공해도
이 workflow는 시작되지 않습니다. 로컬에서는 다음 명령으로 현재 브랜치와
최근 커밋을 확인할 수 있습니다.

git branch --show-current
git log -1 --oneline
git remote -v

git status에 Your branch is ahead가 표시된다면 커밋은 만들었지만 아직
원격 저장소에 보내지 않은 상태일 수 있습니다. 브랜치 이름을 확인하지 않고
반복해서 빈 커밋을 만드는 것보다, 현재 브랜치와 GitHub의 기본 브랜치를
먼저 비교하세요.

3. branches와 paths·paths-ignore 조건을 함께 확인하세요

아래 workflow는 두 조건을 모두 만족해야 합니다.

on:
  push:
    branches:
      - main
    paths:
      - "content/drafts/**/*.md"

즉, main에 push했더라도 변경 파일이 README.md뿐이면 실행되지 않습니다.
반대로 content/drafts/post.md를 변경했어도 다른 브랜치에 push했다면
실행되지 않습니다. GitHub 공식 문서는 branches/branches-ignore와
paths/paths-ignore를 함께 쓰면 두 필터가 모두 충족되어야 한다고
설명합니다.
GitHub Actions workflow 필터 문법

아래 실제 화면은 paths 대신 paths-ignore를 사용한 예시입니다.
main 또는 master 브랜치에 push하더라도 변경 파일이 .gitignore,
README.md, LICENSE처럼 제외 대상으로 지정된 파일뿐이면 workflow가
실행되지 않습니다. paths는 실행할 경로를 포함하는 필터이고,
paths-ignore는 실행에서 제외할 경로만 지정하는 필터입니다. 같은 이벤트에
두 키를 동시에 쓰지는 않습니다.

최근 커밋에 어떤 파일이 포함됐는지는 다음 명령으로 확인할 수 있습니다.

git diff-tree --no-commit-id --name-only -r HEAD

경로 패턴은 저장소 루트를 기준으로 작성합니다. 대소문자, 단수·복수,
하이픈과 밑줄도 실제 경로와 일치하는지 확인하세요.

GitHub Actions workflow에서 main·master 브랜치와 paths-ignore 경로 필터를 설정한 화면

4. 커밋 메시지에 실행 건너뛰기 문구가 없는지 확인하세요

push 또는 pull_request workflow는 커밋 메시지에 다음과 같은 문구가
들어 있으면 건너뛸 수 있습니다.

[skip ci]
[ci skip]
[no ci]
[skip actions]
[actions skip]

자동 커밋 도구나 복사한 커밋 메시지에 이런 문구가 포함되지 않았는지
확인하세요. 건너뛰기 문구가 원인이었다면 해당 문구가 없는 새 커밋을
push해야 합니다. 지원되는 문구와 적용 범위는
GitHub의 workflow 실행 건너뛰기 안내에서
확인할 수 있습니다.

5. workflow와 저장소 Actions가 활성화되어 있는지 확인하세요

workflow는 YAML 파일을 삭제하지 않고도 수동으로 비활성화할 수 있습니다.
Actions 탭에서 해당 workflow를 선택했을 때 Enable workflow 버튼이
보인다면 다시 활성화해야 트리거에 반응합니다.

저장소 전체의 Actions 사용 여부와 허용 정책도 확인합니다.

저장소 Settings
→ Actions
→ General
→ Actions permissions

조직 저장소에서는 조직 또는 엔터프라이즈 정책이 저장소 설정보다 우선할 수
있습니다. workflow가 비활성화됐을 때의 복구 방법은
workflow 비활성화 및 활성화 안내에서
확인할 수 있습니다.

GitHub 저장소 Actions permissions에서 모든 Actions와 재사용 workflow 허용을 선택한 화면

6. 다른 workflow가 GITHUB_TOKEN으로 push했는지 확인하세요

사람이 직접 push한 것이 아니라 앞선 GitHub Actions가
GITHUB_TOKEN으로 커밋을 push했다면, 그 push는 보통 새로운 workflow를
시작하지 않습니다. 무한히 workflow가 서로를 실행하는 상황을 막기 위한
동작입니다.

GITHUB_TOKEN 공식 문서는
workflow_dispatch와 repository_dispatch 등의 예외를 제외하면
GITHUB_TOKEN이 만든 이벤트가 새 workflow 실행을 생성하지 않는다고
설명합니다.

이 문제를 해결하려고 곧바로 개인 액세스 토큰을 넓은 권한으로 발급하기보다
다음 구조를 먼저 검토하세요.

  • 한 workflow 안에서 다음 job까지 이어서 실행
  • 재사용 workflow가 필요하면 workflow_call 사용
  • 앞선 workflow 완료 후 이어야 하면 workflow_run 검토
  • 외부 시스템이 명시적으로 실행해야 하면 repository_dispatch 검토

인증 수단을 변경해야 한다면 최소 권한의 GitHub App 또는 토큰을 사용하고,
토큰을 YAML이나 로그에 직접 출력하지 마세요.

7. 수동 실행으로 트리거 문제와 작업 오류를 분리하세요

workflow에 workflow_dispatch가 있으면 Actions 화면의 Run workflow
버튼으로 수동 실행할 수 있습니다.

on:
  workflow_dispatch:
  push:
    branches:
      - main

수동 실행은 성공하지만 push 실행만 생기지 않는다면 Python, Node.js 또는
배포 명령보다 push 아래의 브랜치·경로 조건을 먼저 고쳐야 합니다.
수동 실행도 시작되지 않는다면 workflow 비활성화, 저장소 정책 또는 YAML
구조를 다시 확인하세요.

외부 서비스에 데이터를 보내는 workflow라면 테스트 입력에서 dry_run을
기본값으로 두고, 실제 변경이 없는 상태로 먼저 실행하는 편이 안전합니다.

실제로 dry_run=true로 수동 실행해 단위 테스트, Markdown 검증과 HTML 변환이
모두 성공하는지 확인했습니다. 이때 Create or update WordPress drafts 단계는
건너뛰어졌으므로 WordPress 글을 생성하거나 수정하지 않았습니다.

그래도 실행되지 않을 때 확인할 정보

문제가 계속되면 아래 정보를 한곳에 모으면 원인을 훨씬 빨리 좁힐 수 있습니다.

  • workflow 파일 경로와 on: 부분
  • 실제로 push한 브랜치
  • 마지막 커밋에 포함된 파일 경로
  • 마지막 커밋 메시지
  • Actions 탭에 workflow가 표시되는지
  • 수동 실행은 가능한지
  • 사람이 push했는지 다른 workflow가 push했는지

Secrets의 실제 값은 화면이나 질문에 포함하지 마세요. 실행 기록이 생성된
뒤 401, 403, 패키지 설치 실패 같은 오류가 발생한다면 push 트리거
문제는 해결된 것입니다. 그때는 실패한 step의 로그를 기준으로 별도 원인을
확인해야 합니다.

정리

GitHub Actions가 push 후 아예 시작되지 않을 때는 다음 순서로 확인하면
됩니다.

  1. Actions에 실행 기록이 있는지 확인
  2. .github/workflows/ 파일 위치 확인
  3. 실제 push한 브랜치 확인
  4. branches와 paths 조건 확인
  5. 커밋 메시지의 실행 건너뛰기 문구 확인
  6. workflow와 저장소 Actions 활성화 확인
  7. GITHUB_TOKEN 자동 push 여부와 수동 실행 결과 확인

이 순서로 확인하면 workflow가 시작되지 않는 문제와, 시작된 workflow의
작업이 실패하는 문제를 섞지 않고 진단할 수 있습니다.

관련 키워드

· ·

TOOLSOLVE GUIDE

가장 빠른 해결법부터
순서대로 설명합니다.

실제 확인 과정과 주의사항을 함께 정리해 같은 문제를 다시 검색하는 시간을 줄입니다.

최신 해결 글

다른 문제를 찾고 있나요?

ToolSolve

AI·IT 도구를 더 쉽게 사용하는 방법

© ToolSolve. 직접 확인한 문제 해결 가이드.

Toolsolve에서 더 알아보기

지금 구독하여 계속 읽고 전체 아카이브에 액세스하세요.

계속 읽기