GitHub Actions —
내 저장소에
'자동화 로봇'을 두는 법

제가 처음 GitHub Actions를 봤을 때의 기분을 아직도 기억합니다. 코드를 고치고, 늘 하던 대로 git push 한 번 눌렀는데, 잠시 뒤에 저장소 화면에 노란 점이 뱅글뱅글 돌더니 초록색 체크 표시가 하나 뜨더라고요. "테스트 통과". 저는 아무것도 안 했는데 말이죠. 누가 대신 제 코드를 받아서, 프로그램을 설치하고, 테스트를 돌려보고, "이상 없습니다" 하고 도장을 찍어준 겁니다.

솔직히 조금 무서웠어요. "내가 모르는 사이에 뭔가가 자동으로 돌아가고 있다"는 게요. 코딩을 늦게 시작한 사람 입장에서는, 이런 자동화가 뭔가 대단한 회사의 전문가들만 쓰는 거창한 시스템처럼 느껴졌거든요. 그런데 알고 보니 이건 GitHub 저장소만 있으면 누구나, 심지어 저 같은 초보도 몇 줄만 적으면 켤 수 있는 기능이었습니다.

앞선 글 CI/CD 이야기에서 "코드를 자동으로 검사하고 배포까지 이어주는 컨베이어 벨트"라는 개념을 다뤘죠. 그 개념을 실제로 굴리는 대표 도구가 바로 오늘의 주인공, GitHub Actions입니다. 개념이 '무엇을 왜'였다면, 오늘은 '어떻게'에 해당하는 이야기예요.

GitHub Actions는 내 저장소 안에 사는 자동화 로봇(알바생)입니다. 여러분이 지시서 한 장을 붙여두면, 그 로봇은 "이런 일이 생기면(트리거) → 이 순서대로 해라(워크플로)"를 24시간 지켜보다가, 조건이 맞는 순간 도미노처럼 착착 일을 처리합니다.

이 비유 하나만 머릿속에 넣고 시작하세요. 오늘 나오는 모든 용어는 결국 "그 로봇에게 시키는 방법"의 세부 항목일 뿐이니까요. 겁먹지 마세요. 저도 그랬지만, 한 바퀴 돌고 나면 별거 아니었구나 하실 겁니다.

GitHub Actions가 대체 뭔가요

한 문장으로 말하면, GitHub Actions는 GitHub 안에 내장된 자동화 도구입니다. 여러분이 코드를 올려두는 그 GitHub, 바로 거기 안에 붙어 있어요. 별도의 서버를 사거나, 다른 사이트에 회원가입하거나, 복잡한 프로그램을 설치할 필요가 없습니다.

비유를 이어가 볼게요. 여러분의 GitHub 저장소가 하나의 '작업장'이라고 합시다. 예전에는 이 작업장에서 벌어지는 자잘한 일들 — 테스트 돌리기, 오탈자 검사, 서버에 올리기 — 을 전부 사장님(여러분)이 손으로 직접 했습니다. 퇴근도 못 하고요. GitHub Actions는 이 작업장에 성실한 알바 로봇을 한 명 붙여주는 것과 같습니다. 이 로봇은 잠도 안 자고, 월급도 안 밀리고(무료 한도 안에서는), 시킨 일을 정확히 순서대로 합니다.

이 로봇의 특징은 "스스로 나서지 않는다"는 겁니다. 시키지 않으면 가만히 있어요. 대신 여러분이 정해준 특정 사건이 저장소에서 벌어지면, 그 순간 벌떡 일어나 지시서에 적힌 일을 처리합니다. 코드가 올라왔다든지, 누가 수정 제안(Pull Request)을 열었다든지, 매일 새벽 3시가 됐다든지 하는 사건들이요.

왜 이런 게 필요할까 — 손으로 다 하던 시절의 고통

자동화의 가치는 "자동화가 없을 때 얼마나 괴로운가"를 알아야 실감이 납니다. 제가 초보 시절 겪은 하루를 재현해 볼게요.

코드를 조금 고쳤습니다. 이제 다른 사람들에게 보여주기 전에 확인해야 할 게 한둘이 아니에요. 먼저 테스트를 돌려서 안 깨졌는지 봐야 하고, 코드 스타일이 규칙에 맞는지 검사(린트)해야 하고, 최종 결과물을 만드는 빌드도 해봐야 하고, 문제가 없으면 서버에 올리는 배포까지 해야 합니다. 이걸 매번 손으로 했습니다. 한 번에 대여섯 개 명령어를요.

문제는 사람이라 실수한다는 겁니다. 급할 때는 테스트를 건너뛰고 그냥 배포해버려요. 그러다 한밤중에 서비스가 터집니다. 또 어떤 날은 "내 컴퓨터에선 잘 됐는데" 하며 올렸더니 남의 컴퓨터에선 안 돌아가요. 환경이 미묘하게 달라서요. 이런 일이 반복되면 팀 전체가 배포를 무서워하게 됩니다.

GitHub Actions는 이 고통을 정확히 겨냥합니다. "매번 똑같이 반복하는 일"을 로봇에게 넘기는 거예요. 로봇은 급하다고 테스트를 건너뛰지 않습니다. 늘 정해진 순서대로, 늘 똑같이 깨끗한 환경에서 일합니다. 사람의 실수가 끼어들 틈이 없어지는 거죠. 이게 바로 CI/CD가 말하는 "자동화의 힘"이고, Actions는 그걸 손에 잡히게 만들어주는 도구입니다.

핵심 용어를 비유로 정리하기

Actions를 처음 배울 때 가장 헷갈리는 건 용어입니다. Workflow, Job, Step, Runner, Action, Event... 다 비슷해 보이고 다 영어라 머리가 아파요. 그런데 이걸 "로봇에게 일 시키는 상황"으로 바꿔놓으면 순식간에 정리됩니다. 표부터 보시죠.

여기서 이름이 헷갈리는 지점 하나만 짚을게요. 서비스 전체 이름이 "GitHub Actions"이고, 그 안에서 부품 하나를 "Action(액션)"이라고도 부릅니다. 같은 단어라 처음엔 헷갈리지만, 문맥으로 구분됩니다. 큰 개념(자동화 도구 전체)을 말할 땐 Actions, 작은 부품(재사용 조각)을 말할 땐 Action이에요.

다시 한 번 계층으로 정리하면 이렇습니다. 워크플로(지시서 한 장) 안에 여러 개의 Job(임무)이 있고, 각 Job은 여러 개의 Step(단계)으로 이뤄집니다. 각 Step은 직접 명령어를 실행(run)하거나, 남이 만든 Action(부품)을 갖다 씁니다(uses). 그리고 이 모든 게 실제로 돌아가는 컴퓨터가 Runner고요. 지시서가 언제 발동될지는 이벤트가 정합니다.

전체 흐름 한눈에 보기

말로만 들으면 여전히 뜬구름 같으니, 로봇이 한 번 일하는 과정을 순서도로 그려보겠습니다. push 한 번에 무슨 일이 벌어지는지를요.

하나씩 풀어볼게요. 먼저 여러분이 코드를 올리면(이벤트), GitHub가 "어, 지시서에 push 나오면 일하라고 돼 있네" 하고 알아챕니다. 그러면 깨끗한 새 컴퓨터(Runner)를 한 대 켭니다. 여기서 '깨끗한'이 중요해요. 여러분 노트북에 뭐가 깔려 있든 상관없이, 매번 아무것도 없는 상태에서 시작하기 때문에 "내 컴퓨터에선 됐는데" 문제가 사라집니다.

켜진 컴퓨터 위에서 로봇은 지시서에 적힌 Step을 위에서부터 하나씩 실행합니다. 보통 첫 단계는 "내 코드를 이 컴퓨터로 내려받기(체크아웃)"고, 그다음 "필요한 프로그램 설치", "테스트 실행", (문제없으면) "배포" 순이에요. 마치 도미노처럼, 앞 단계가 성공해야 다음으로 넘어갑니다.

모든 단계가 끝나면 로봇은 결과를 보고합니다. 다 통과하면 초록색 체크(✓), 중간에 하나라도 실패하면 빨간 X(✗)를 저장소나 Pull Request 화면에 띄워줍니다. 그래서 PR 코드리뷰를 할 때, 사람이 눈으로 보기 전에 "로봇이 먼저 기본 검사를 통과시켜준" 상태로 리뷰를 시작할 수 있는 거예요. 그리고 일이 끝나면 그 컴퓨터는 미련 없이 꺼집니다. 다음에 또 이벤트가 오면 새 컴퓨터를 다시 켜고요.

아주 쉬운 예시 — "main에 push되면 테스트 실행"

이제 실제 지시서를 딱 하나만 보겠습니다. 겁먹지 마세요. 아래 코드는 "읽으라고" 보여드리는 거지 지금 외우라는 게 아닙니다. 한 줄씩 옆에서 통역해 드릴 테니 그냥 "아 이런 모양이구나" 정도만 느끼시면 됩니다.

이 파일은 저장소 안 .github/workflows/test.yml 위치에 둡니다. 폴더 이름과 위치가 정해져 있어서, 여기에 넣어야 GitHub가 "아, 이게 지시서구나" 하고 알아챕니다.

name: 테스트 실행
on:
  push:
    branches: [ main ]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install
      - run: npm test

이제 한 줄씩 통역합니다.

어때요? 코드라고 부르기도 민망할 만큼 짧죠. 핵심은 딱 세 덩어리입니다. 언제(on), 어디서(runs-on), 무엇을 순서대로(steps). 이 뼈대만 잡으면 나머지는 살을 붙이는 일입니다. 처음엔 이런 예시를 하나 복사해다가 조금씩 바꿔가며 익히는 게 정석이에요. 저도 그렇게 배웠습니다.

처음 워크플로 만들어보기 — 손으로 따라 하기

이론은 충분히 봤으니, 실제로 첫 로봇을 채용하는 과정을 순서대로 그려볼게요. 겁먹지 마세요. 저장소 하나만 있으면 됩니다.

딱 여기까지만 해보셔도 "아, 내가 방금 자동화 하나를 켰구나"라는 감이 옵니다. 저는 이 과정을 처음 끝냈을 때, 별것 아닌데도 괜히 뿌듯해서 커피 한 잔 마셨어요. 작은 성공이 다음 걸음을 만들어줍니다.

실제로 뭘 자동화하나 — 로봇에게 시킬 수 있는 일들

"테스트만 돌리는 거면 그렇게 대단한가?" 싶으실 텐데, Actions로 시킬 수 있는 일은 훨씬 넓습니다. 반복되는 일이라면 거의 다 넘길 수 있다고 보시면 돼요. 대표적인 것들을 표로 정리했습니다.

여기서 schedule(정기 작업)만 조금 더 설명할게요. 아까 예시에서는 on: push로 "코드가 올라오면"이라고 했지만, on: schedule로 바꾸면 "매일 새벽 3시에" 같은 시간 조건으로도 로봇을 깨울 수 있습니다. 이걸 크론(cron)이라고 부르는데, 아무도 push하지 않아도 정해진 시각에 알아서 일하는 거죠. 정기 리포트나 백업에 아주 유용합니다.

중요한 건, 이 모든 걸 처음부터 다 할 필요는 없다는 겁니다. 저는 "테스트 자동 실행" 하나만 켜두는 것으로 시작했어요. 그것만으로도 push할 때마다 마음이 든든해졌습니다. 익숙해지면 린트를 붙이고, 그다음 배포를 붙이고... 이렇게 하나씩 늘려가는 게 정신 건강에 좋습니다.

시크릿(secrets) — 비밀번호를 코드에 넣지 마세요

이 섹션은 정말 중요합니다. 밑줄 세 번 긋고 싶어요. 배포를 자동화하려면 로봇에게 "서버 접속 비밀번호"나 "배포용 열쇠(토큰)" 같은 비밀 정보를 줘야 합니다. 그런데 초보들이 여기서 크게 사고를 칩니다. 비밀번호를 그냥 지시서 파일(.yml)이나 코드에 그대로 적어버리는 거예요.

왜 큰일이냐면, 코드는 GitHub에 올라가는 순간 (공개 저장소라면) 전 세계 누구나 볼 수 있기 때문입니다. 비밀번호를 코드에 적는 건, 현관 비밀번호를 대문에 큼지막하게 써 붙이는 것과 똑같아요. 실제로 이렇게 노출된 열쇠를 자동으로 긁어가는 나쁜 프로그램들이 돌아다닙니다. 노출되는 순간 몇 분 만에 악용될 수 있어요.

그래서 GitHub는 시크릿(Secrets)이라는 금고를 따로 마련해뒀습니다. 저장소 설정(Settings) 안의 Secrets 메뉴에 비밀 정보를 넣어두면, GitHub가 그걸 암호화해서 안전하게 보관합니다. 지시서에서는 실제 값 대신 이름표로만 불러다 씁니다. 예를 들어 ${{ secrets.DEPLOY_KEY }}처럼요. 실제 값은 로봇이 일할 때만 잠깐 금고에서 꺼내 쓰고, 화면 로그에도 ***로 가려져서 안 보입니다.

혹시 이미 실수로 비밀번호를 코드에 올려버렸다면? 파일에서 지운다고 끝이 아닙니다. Git은 과거 기록을 전부 보관하기 때문에, 이력에 남아 있어요. 이럴 땐 그 열쇠 자체를 폐기하고 새로 발급받는 게 제일 확실합니다. 노출된 열쇠는 이미 위험하다고 보는 게 안전해요.

요금과 한도 감각 잡기

돈 이야기를 안 할 수 없죠. 로봇이 일하려면 실제 컴퓨터(Runner)가 돌아가야 하고, 컴퓨터가 도는 시간에는 비용이 발생합니다. 다만 겁먹을 필요는 없어요. 감각만 잡아드릴게요.

큰 틀에서, 공개(퍼블릭) 저장소는 대체로 넉넉하게, 무료에 가깝게 쓸 수 있는 경향이 있습니다. 오픈소스처럼 누구나 볼 수 있는 코드에는 GitHub가 관대한 편이에요. 반면 비공개(프라이빗) 저장소는 사용량 기반으로, "로봇이 실제로 일한 시간"만큼 무료 한도가 있고 그걸 넘으면 과금되는 구조입니다.

여기서 아주 중요한 안내를 드립니다. 구체적인 무료 시간, 요금 단가, 플랜별 차이 같은 숫자는 제가 여기서 지어내지 않겠습니다. 이런 값은 정책에 따라 자주 바뀌고, 여러분의 계정 종류(개인/팀/기업)에 따라서도 달라지거든요. 잘못된 숫자를 외우는 것보다, GitHub 공식 요금·사용량(billing) 문서를 직접 확인하는 습관이 훨씬 안전합니다. 저장소나 계정 설정의 Billing 메뉴에서 현재 내 사용량도 실시간으로 볼 수 있어요.

초보가 흔히 하는 실수 & 해결법

제가 직접 겪었거나, 옆에서 숱하게 본 실수들입니다. 미리 알아두면 똑같은 함정을 피할 수 있어요.

특히 YAML 들여쓰기는 초보의 90%가 한 번은 겪는 일이에요. 저도 "왜 안 돌지?" 하며 30분을 헤맨 적이 있는데, 알고 보니 칸 하나가 안 맞았더라고요. 실망하지 마세요. 이건 능력 문제가 아니라 그냥 이 형식의 특성이고, 몇 번 겪으면 눈에 들어옵니다.

그리고 실패 로그를 여는 걸 무서워하지 마세요. 처음엔 알 수 없는 영어가 잔뜩 나와서 압도되지만, 대개 빨간 글씨로 "여기서 이게 없어서 멈췄다"고 친절히 알려줍니다. 그 문장 하나만 검색해도 답이 나오는 경우가 많아요. 요즘은 AI에게 그 로그를 붙여넣고 물어보는 것도 아주 좋은 방법이고요.

Marketplace — 남이 만든 로봇 부품 갖다 쓰기

Actions의 진짜 매력은 "다 직접 만들 필요가 없다"는 데 있습니다. 앞서 예시에 나온 actions/checkout 기억나시죠? 그건 GitHub와 수많은 개발자들이 미리 만들어둔 부품(Action)이었어요. 이런 부품들을 한데 모아놓은 장터가 바로 GitHub Marketplace입니다.

비유하자면, 가구를 만들 때 나사와 경첩을 직접 깎을 필요가 없는 것과 같아요. 이미 잘 만들어진 표준 부품을 사다가 조립만 하면 되죠. "슬랙으로 알림 보내기", "특정 클라우드에 배포하기", "코드 보안 취약점 검사하기" 같은 흔한 작업은 이미 누군가 부품으로 만들어뒀습니다. 여러분은 지시서에 uses: 한 줄로 그 부품을 불러오기만 하면 돼요.

다만 아무 부품이나 덥석 쓰진 마세요. 부품도 결국 남의 코드라, 나쁜 부품을 쓰면 내 시크릿이 새어나갈 수도 있습니다. 그래서 공식(GitHub 인증 마크가 붙은) 부품이나 별(star)이 많고 관리가 활발한 부품을 고르는 게 안전합니다. 그리고 @v4처럼 버전을 명확히 지정해서, 부품이 갑자기 바뀌어 내 워크플로가 깨지는 일도 막는 게 좋아요.

자주 묻는 질문 (FAQ)

Q. 저는 개발자도 아닌데, Actions를 꼭 알아야 하나요?
A. '깊이' 알 필요는 없지만 '개념'은 알아두면 큰 도움이 됩니다. 요즘은 코드를 몰라도 만든 결과물을 GitHub에 올리고 자동 배포하는 경우가 많거든요. 최소한 "초록 체크는 통과, 빨간 X는 실패"만 읽을 줄 알아도, 무슨 일이 벌어지는지 파악할 수 있습니다. 겁먹지 마세요.

Q. 워크플로 파일을 잘못 만들면 뭔가 망가지나요?
A. 대부분은 그냥 "안 돌아갈" 뿐입니다. 지시서 형식이 틀리면 로봇이 못 읽고 조용히 멈추거나 에러를 표시해요. 진짜로 위험한 건 잘 도는 워크플로가 '나쁜 일'(예: 잘못된 배포, 시크릿 노출)을 하도록 시켰을 때입니다. 그래서 처음엔 배포 같은 위험한 작업 없이 테스트만 돌려보며 익히는 걸 권합니다.

Q. 다른 자동화 도구(Jenkins 등)도 있다던데, 왜 Actions인가요?
A. 가장 큰 이유는 "GitHub 안에 이미 들어 있다"는 편의성입니다. 별도 서버를 세우고 관리할 필요 없이, 코드가 있는 그 자리에서 바로 켜집니다. 초보자·개인·소규모 팀에게는 이 진입 장벽이 낮다는 점이 결정적이에요. 물론 아주 큰 조직은 다른 도구를 쓰기도 하지만, 시작은 Actions가 편합니다.

Q. 로봇이 일하는 동안 제 컴퓨터를 켜둬야 하나요?
A. 아니요. 기본값(GitHub 제공 Runner)을 쓰면 GitHub의 컴퓨터에서 돌기 때문에, 여러분은 push만 하고 컴퓨터를 꺼도 됩니다. 반대로 "내 컴퓨터에서 돌리고 싶다"면 셀프호스트 Runner를 등록할 수도 있는데, 그건 특별한 이유가 있을 때의 이야기예요.

Q. 실수로 워크플로가 계속 도는 것 같아요. 어떻게 멈추죠?
A. 저장소의 Actions 탭에 들어가면 현재 돌고 있는 작업 목록이 보이고, 거기서 실행 중인 워크플로를 취소(cancel)할 수 있습니다. 그리고 원인이 무한 루프라면, 문제의 워크플로 파일을 잠시 비활성화하거나 트리거 조건을 수정해서 근본 원인을 막아야 해요.

마무리 체크리스트

오늘 긴 여정을 함께 해주셨네요. 마지막으로 머릿속에 남길 것들을 정리합니다.

• ✅ Actions는 저장소 안에 사는 자동화 로봇 — "이벤트가 생기면 → 정해진 순서대로 실행".
• ✅ 핵심 용어 여섯 개: 워크플로(지시서), 이벤트(언제), Job/Step(무엇을 순서대로), Runner(어디서), Action(남이 만든 부품).
• ✅ 지시서는 .github/workflows/ 폴더 안의 .yml 파일. 뼈대는 on / runs-on / steps.
• ✅ 비밀번호·토큰은 절대 코드에 적지 말고 Secrets 금고에 넣어 secrets.이름으로 참조.
• ✅ 요금은 공개 저장소는 넉넉, 비공개는 사용량 기반. 구체 숫자는 공식 Billing 문서에서 확인.
• ✅ 처음엔 "테스트 자동 실행" 하나만. 익숙해지면 린트·빌드·배포를 하나씩 추가.
• ✅ 부품이 필요하면 Marketplace에서 공식·인기·버전 고정 기준으로 골라 쓰기.

코딩을 늦게 시작한 제가 감히 말하자면, 자동화는 "실력 있는 사람"의 전유물이 아닙니다. 오히려 실수 많은 초보일수록 로봇에게 반복 검사를 맡겨두면 훨씬 든든해져요. 저는 "테스트 자동 실행" 워크플로 하나를 켜둔 뒤로, push할 때마다 조마조마하던 마음이 확 줄었습니다. 여러분도 오늘 배운 그 짧은 예시 하나만 따라 해보시면, "아, 이래서 다들 쓰는구나" 하실 거예요.

다음 글에서는 한 걸음 더 나아가 보겠습니다. Actions가 정해진 순서대로 일하는 '성실한 알바 로봇'이었다면, 이제는 스스로 판단하고 코드를 고쳐주는 GitHub 코딩 에이전트 이야기, 그리고 "내 컴퓨터에선 됐는데"를 근본적으로 없애주는 컨테이너 이야기를 준비했어요. 전체 흐름이 궁금하시면 DevOps 시리즈 개요부터 다시 보셔도 좋습니다. 오늘도 한 걸음 나아가신 여러분, 정말 잘하고 계십니다.

(2026년 8월 기준 작성 — 화면·메뉴·요금 정책은 바뀔 수 있으니 GitHub 공식 문서를 함께 확인하세요.)

← 기술 블로그 목록으로