Claude Code로 GitHub Actions Slack 알림봇 1시간 만에 만들기
배포가 깨졌다는 걸 늦게 아는 날
GitHub Actions가 실패했는데 한참 뒤에 확인하는 날이 있습니다. 오전에 배포가 틀어졌는데 점심 지나서야 로그를 열어보면, 고치는 시간보다 놓친 시간이 더 아깝게 느껴지죠. 오늘 만드는 GitHub Actions Slack 알림봇은 그 공백을 줄이는 데 초점을 둡니다. 실패한 워크플로 이름, 브랜치, 링크를 Slack 한 장짜리 메시지로 보내게 만들면 됩니다. 지난 편에서 화면 쪽을 만졌다면 이번에는 터미널에서 바로 써먹는 자동화 하나를 붙이는 흐름입니다.
준비물은 많지 않다
이번 작업은 Claude Code로 진행하면 속도가 잘 납니다. /init으로 작업 규칙을 먼저 남기고, /review로 빠진 부분을 짚고, /schedule로 반복 실행까지 붙이는 흐름이 자연스럽습니다. 필요한 것도 단순합니다. GitHub 프로젝트 하나, Slack Incoming Webhook URL 하나, 빈 폴더 하나면 시작할 수 있습니다. 처음부터 파일을 여러 개 벌리면 손이 바빠지기 쉬우니, Python 한 파일로 시작하는 편이 정리하기 좋습니다.
먼저 조회부터 붙이면 덜 헤맨다
이 프롬프트를 먼저 넣는 이유는 범위를 초반에 고정하기 위해서입니다. Claude Code는 처음 지시가 넓으면 파일을 늘리거나 구조를 크게 잡는 쪽으로 흘러가기 쉽습니다. 반대로 대상 프로젝트, 중복 금지 규칙, Slack 문구 길이 정도만 미리 적어두면 뒤에서 판단이 흔들리지 않습니다. 여기서 만들어지는 CLAUDE.md도 길 필요는 없습니다. 다시 열었을 때 "아, 이 폴더는 실패 알림 하나만 만드는 자리구나"가 바로 보이면 충분합니다.
처음 5분은 메시지를 보내는 것보다 실패 목록이 제대로 잡히는지 확인하는 시간으로 쓰는 편이 낫습니다. 콘솔에 failed run 이름과 브랜치가 보이면 조회 쪽은 통과입니다. 여기서 비어 있으면 Slack을 붙여도 원인을 나누기 어렵습니다. 반대로 조회가 먼저 잡히면 다음 단계는 거의 연결 작업에 가깝습니다.
이 순서가 좋은 이유는 문제를 작게 나눌 수 있기 때문입니다. GitHub 조회, Slack 전송, 중복 저장을 한 번에 묶어버리면 어디가 꼬였는지 파악하는 데 시간이 더 듭니다. 그래서 첫 버전은 일부러 담백하게 두는 편이 좋습니다. 터미널에 실패한 작업만 정리돼도 이미 자동화의 뼈대는 올라온 상태입니다.
여기서 먼저 챙길 건 state.json입니다. 이 파일이 빠지면 같은 실패를 10분마다 다시 보게 됩니다. 알림 문구도 짧게 두는 편이 낫습니다. 워크플로 이름, 브랜치, 실행 시간, 링크만 있어도 Slack에서 바로 눌러서 이동할 수 있습니다. 긴 설명보다 문제 화면으로 빨리 넘어가게 만드는 쪽이 실제 운영에는 더 맞습니다.
이 단계까지 오면 GitHub Actions Slack 알림봇이 제 역할을 시작합니다. 실패가 생기면 채널에서 바로 보고, 링크를 눌러 원인 화면으로 넘어가면 됩니다. 메시지가 짧아서 휴대폰으로 보기에도 부담이 적고, 브랜치가 같이 적혀 있으면 어느 작업선에서 터졌는지도 한눈에 들어옵니다. 한 파일짜리 도구지만 놓친 배포를 늦게 발견하는 일은 꽤 잘 줄여줍니다.
이 구간에서는 새 기능을 더하는 것보다 이미 만든 파일을 덜 위험하게 다듬는 게 우선입니다. /review를 이렇게 짧게 걸면 응답도 짧게 돌아와서 수정 포인트가 선명하게 남습니다. 환경변수 누락 처리, 네트워크 타임아웃, state.json 저장 위치처럼 실제로 문제를 만들 수 있는 부분을 빠르게 확인하기 좋습니다.
검수 결과가 여러 줄로 와도 한 번에 전부 넣을 필요는 없습니다. 지금 당장 알림이 빠지거나 중복될 수 있는 항목부터 반영하면 됩니다. 예를 들어 웹훅 주소가 비어 있으면 바로 종료하게 만들고, 요청 실패 시 1회 재시도를 넣는 정도만 해도 운영 안정감이 많이 올라갑니다. 봇을 크게 만드는 것보다 같은 문제로 다시 시간을 쓰지 않게 하는 쪽이 더 중요합니다.
여기까지 왔으면 손으로 실행하는 구간을 줄일 차례입니다. 평일 오전 9시부터 오후 7시까지 10분마다 돌리면 업무 시간대 감시로는 충분한 편입니다. 일정 설정을 붙일 때 환경변수 확인 단계를 같이 두는 이유도 분명합니다. GITHUB_TOKEN이나 SLACK_WEBHOOK_URL이 비어 있으면 조용히 실패할 수 있는데, 그 상태로 며칠 지나가면 알림이 없는 건지 봇이 죽은 건지 헷갈리기 쉽습니다.
이렇게 연결해두면 GitHub Actions Slack 알림봇은 평소에는 조용하다가 실패가 생겼을 때만 움직입니다. 알림이 필요 없는 날에는 채널을 어지럽히지 않고, 문제가 생긴 순간에는 바로 신호를 줍니다. 작은 자동화지만 배포 확인 습관을 바꾸는 데는 이 정도 구성이 오히려 다루기 편합니다.
막히는 지점은 대개 세 군데다
Slack에 아무 메시지도 안 오면 전송 경로부터 좁혀보면 됩니다. bot.py는 끝까지 돌았는데 채널이 비어 있으면 웹훅 주소가 잘렸거나 다른 워크스페이스 주소가 들어간 경우가 많습니다. 이럴 때는 Claude Code에 테스트 payload 하나만 보내는 작은 함수를 추가해달라고 요청하면 됩니다. 본 알림 로직보다 먼저 테스트 메시지를 보내보면 전송 문제인지 조회 문제인지 빠르게 나뉩니다.
GitHub API가 403을 내거나 결과가 비어 있으면 권한과 대상 이름을 먼저 봐야 합니다. private repo를 읽으려면 GITHUB_TOKEN에 필요한 권한이 들어 있어야 하고, owner/repo 표기가 틀려도 바로 막힙니다. 실패 목록이 없다고 해서 봇이 잘못됐다고 단정할 필요는 없습니다. 최근 실행 중에 실제 failed 항목이 없는 경우도 있으니, 조회 범위를 다시 확인하는 편이 빠릅니다.
같은 실패가 계속 다시 오면 state.json 저장이 꼬였을 가능성이 큽니다. 읽기 전용 폴더에서 돌렸거나 상대경로가 예상과 다르게 잡히면 run id가 남지 않습니다. 이때는 실행 뒤에 state.json 수정 시간이 바뀌는지만 보면 됩니다. 파일이 갱신되지 않으면 저장 경로를 스크립트 기준으로 고정해달라고 다시 요청하면 정리가 됩니다.
다음 단계는 하나만 붙이면 된다
여기까지 만들었으면 다음 확장은 한 번에 하나만 붙이는 편이 좋습니다. main 브랜치만 따로 보게 하거나, 마지막 로그 한 줄만 같이 보내게 하는 정도면 충분합니다. 처음부터 오류 요약, 담당자 태그, 여러 프로젝트 감시를 전부 넣기 시작하면 1시간 안에 끝날 작업이 바로 길어집니다. 오늘 목표는 큰 시스템이 아니라 GitHub Actions Slack 알림봇 하나로 실패를 늦게 보는 습관을 줄이는 것입니다. 이 기준만 지키면 블로그 글을 따라가면서 만든 첫 버전도 바로 운영에 올릴 수 있습니다.
이런 글도 있어요
관련 검색어
- 🔍 Claude Code 사용법
- 🔍 Claude Code 비교
- 🔍 GitHub Actions Slack 알림봇 사용법
- 🔍 GitHub Actions Slack 알림봇 비교
- 🔍 GitHub Actions 사용법
- 🔍 GitHub Actions 비교
