GitHub Actions 사용법: AI가 만든 코드 자동 검사 설정하기
AI에게 코드를 만들어 달라고 했더니 “완성했습니다”라는 답이 돌아왔습니다. 화면도 그럴듯해 보입니다. 그런데 이 코드가 다음에 수정되더라도 제대로 작동하는지, 또 누군가 실수로 기능을 망가뜨리지 않았는지는 어떻게 확인할까요? 그럴 때 쓸 수 있는 것이 GitHub Actions입니다. GitHub에 코드를 올리거나 변경 요청을 보내면 미리 정한 검사 명령을 자동으로 실행할 수 있습니다.
사람 대신 코드를 이해하고 보증하는 마법은 아니지만, 매번 수동으로 테스트 버튼을 누르는 반복 작업을 줄여 줍니다. 이번 글에서는 복잡한 앱 대신 숫자 두 개를 더하는 작은 JavaScript 프로그램을 만들어 실제로 실행 가능한 검사 구성을 익힙니다. 코딩을 처음 접한 독자를 위해 파일 위치부터 실패 로그 확인, 비용·보안까지 차근차근 설명합니다. 작성 기준: 2026년 10월 16일. GitHub 화면 이름과 Actions 버전은 바뀔 수 있습니다. 아래 예시는 공식 문서를 참고해 만든 실습용 코드이며, 작성자가 독자 계정에서 직접 실행해 확인한 기록은 아닙니다.
이 글의 순서
- 1. GitHub Actions는 무엇을 자동으로 해 주나요?
- 2. 알아둘 이름은 네 개뿐입니다
- 3. 준비물과 오늘 만들 파일
- 4. 첫 번째 파일: package.json 만들기
- 5. 두 번째 파일: 검사할 코드 만들기
- 6. 세 번째 파일: 맞는 답을 검사하는 테스트 만들기
- 7. 네 번째 파일: GitHub Actions 자동 검사 설정하기
- 8. 저장소에 올린 뒤 PASS/FAIL 확인하기
- 9. 오류를 일부러 만들어 자동 검사 원리 이해하기
- 10. 검사가 실패하면 Pull Request 합치기도 자동으로 막히나요?
- 11. 돈이 얼마나 들까요?
- 12. AI가 만든 코드를 자동 실행할 때 가장 중요한 보안 원칙
- 13. 초보자가 자주 만나는 오류와 해결법
- 14. AI에게 GitHub Actions 설정을 맡길 때 쓸 프롬프트
- 자주 묻는 질문(FAQ)
- 마무리: AI 코드 검증은 ‘한 번의 성공’보다 ‘반복 검사’가 중요합니다
1. GitHub Actions는 무엇을 자동으로 해 주나요?
GitHub는 인터넷에 코드를 보관하고 변경 이력을 관리하는 서비스입니다. GitHub Actions는 그 안에서 정해진 사건이 생겼을 때 실행할 작업을 지정하는 자동화 기능입니다. 예를 들어 “새 코드를 GitHub에 올리면 테스트해 줘”라고 설정할 수 있습니다. 그 뒤에는 보통 다음 순서가 진행됩니다.
코드 변경 → GitHub가 실행을 시작 → 가상 컴퓨터 준비 → 검사 명령 실행 → 결과 표시 코드가 제대로 동작하면 성공(Success), 테스트가 기대한 결과와 다르면 실패(Failure)로 표시될 수 있습니다. 다만 검사 자체가 잘못됐거나 검사 범위가 부족하면, 성공 표시가 떴어도 실제 앱에 문제가 남을 수 있습니다. 간단한 비유를 들어 볼까요? AI 코딩 도구가 요리사라면 GitHub Actions는 매번 정해진 항목을 점검하는 검사표입니다. 요리사의 모든 실수를 알아채는 것은 아니지만, 미리 만든 테스트 항목은 빠뜨리지 않고 반복 확인하게 할 수 있습니다.
2. 알아둘 이름은 네 개뿐입니다
| 용어 | 쉬운 뜻 | 오늘의 예시 |
|---|---|---|
| Workflow | 자동 검사 절차 전체 | 코드가 바뀌면 Node.js 테스트 수행 |
| Event | 작업을 시작하게 하는 계기 | push·pull_request |
| Job | 한 묶음의 검사 작업 | node-test |
| Step | 작업 안에서 실행하는 순서 | 코드 받기·Node 준비·테스트 |
YAML이라는 설정 파일로 이 규칙을 작성합니다. 직접 프로그램 전체를 만들 필요 없이, “어떤 작업을 언제 실행할지”를 정해 두는 것입니다. 처음에는 “코드를 올리면 npm test 실행”이라는 목표 하나만 잡아도 충분합니다.
3. 준비물과 오늘 만들 파일
필요한 것은 GitHub 계정, 새 GitHub 저장소, 텍스트 편집기입니다. 저장소는 GitHub 웹사이트에서도 새 파일을 만들어 연습할 수 있습니다. 우리가 완성할 폴더 구조는 다음과 같습니다.
my-first-ci/
├── package.json
├── src/
│ └── math.js
├── test/
│ └── math.test.js
└── .github/
└── workflows/
└── node-test.yml
주의: 폴더 이름의 점도 중요합니다. GitHub Actions가 자동 실행
규칙을 찾는 곳은 정확히 .github/workflows/입니다. 파일 확장자는
.yml 또는 .yaml을 사용합니다. 이 실습은 외부
패키지를 추가 설치하지 않습니다. 따라서 처음에는 npm 의존성 설치 단계 없이
Node.js에 내장된 테스트 기능을 사용합니다.
4. 첫 번째 파일: package.json 만들기
프로젝트 맨 위에 package.json 파일을 만들고 아래 내용을 넣습니다.
{
"name": "my-first-ci",
"version": "1.0.0",
"private": true,
"type": "module",
"scripts": {
"test": "node --test"
}
}
각 항목의 역할은 간단합니다. name은 프로젝트 이름,
private은 실수로 npm 패키지 공개를 시도하는 것을 막는 표시,
type은 JavaScript의 모듈 문법을 사용하겠다는 설정입니다. 오늘
가장 중요한 부분은 "test": "node --test"입니다. 이 설정 덕분에 npm test라는 짧은 명령으로 테스트 파일을
실행할 수 있습니다. Node.js 공식 문서는 node --test로 내장 테스트
러너를 실행하는 방식을 안내합니다. 별도의 테스트 프레임워크가 없는 이 예제에
알맞습니다.
5. 두 번째 파일: 검사할 코드 만들기
src/math.js 파일을 만들어 다음 코드를 적습니다.
export function add(a, b) {
return a + b;
}
이 함수는 숫자 두 개를 더합니다. 예를 들어 add(2, 3)은
5를 돌려주어야 합니다. 복잡한 홈페이지나 AI 앱도 결국 작은 함수와
작업의 조합입니다. 처음에는 이렇게
기대하는 결과를 분명하게 적을 수 있는 작은 코드부터 자동
검사를 붙이는 것이 쉽습니다.
6. 세 번째 파일: 맞는 답을 검사하는 테스트 만들기
test/math.test.js 파일을 만듭니다.
import test from 'node:test';
import assert from 'node:assert/strict';
import { add } from '../src/math.js';
test('2와 3을 더하면 5', () => {
assert.equal(add(2, 3), 5);
});
test('0과 7을 더하면 7', () => {
assert.equal(add(0, 7), 7);
});
첫 테스트는 2 + 3 = 5, 두 번째는 0 + 7 = 7인지 검사합니다. 실제 코드의 결과가 예상 값과 일치하면 통과하고, 일치하지 않으면 실패합니다. 여기서 중요한 사실 하나가 있습니다. 테스트는 미리 써 둔 질문에만 답합니다. 큰 숫자에서의 오류나 문자열 처리 문제 등 테스트하지 않은 상황은 놓칠 수 있습니다. 테스트 두 개가 통과한다고 프로그램 전체가 완벽해지는 것은 아닙니다. 컴퓨터에 Node.js가 설치돼 있다면 프로젝트 폴더에서 다음 명령을 실행할 수 있습니다.
npm test
정상적인 구성이라면 두 검사가 통과하도록 설계돼 있습니다. 이 글의 설명은 예상되는 동작을 보여 주는 것이며, 작성자가 실제 실행 로그를 확보한 것은 아닙니다.
7. 네 번째 파일: GitHub Actions 자동 검사 설정하기
이제 .github/workflows/node-test.yml 파일을 만들어 아래 내용을
입력합니다.
name: Check AI-generated code
on:
push:
branches: [main]
pull_request:
branches: [main]
permissions:
contents: read
jobs:
node-test:
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- name: Get source code
uses: actions/checkout@v6
- name: Set up Node.js
uses: actions/setup-node@v7
with:
node-version: '24'
package-manager-cache: false
- name: Run unit tests
run: npm test
내용은 길어 보이지만 한 줄씩 읽으면 이해하기 쉽습니다.
push는 main 브랜치에 코드를 올렸을 때,
pull_request는 main 브랜치에 합칠 변경 요청을 만들거나 업데이트할 때 검사를
시작한다는 뜻입니다. permissions: contents: read는 작업에서 사용하는 기본 토큰에 저장소 내용을 읽는 최소 권한을 부여합니다.
이 검사에는 코드를 수정하거나 저장소에 글을 게시하는 권한이 필요하지 않습니다.
actions/checkout@v6는 저장소의 코드를 작업 공간으로 가져옵니다.
actions/setup-node@v7는 Node.js를 준비합니다. GitHub 공식 Node.js 가이드는 2026년 10월 확인 시점에
이 버전 조합을 예제로 사용합니다.
node-version: '24'는 검사에 사용할 Node.js 주 버전입니다.
package-manager-cache: false는 이 초간단 예제에서 필요하지 않은 npm 자동 캐시를 끕니다.
npm test가 실제 검사 명령입니다.
다른 프로젝트에 복사할 때: 이미 테스트와 의존성이 있는 Node.js 앱이라면 보통
package-lock.json을 커밋하고, 워크플로에npm ci를 테스트 전에 추가합니다. 오늘의 작은 예제처럼 의존성이 없는 경우에는 별도의 설치 단계가 필요하지 않습니다. 아무 프로젝트에나 위 설정을 그대로 복사하면 맞지 않을 수 있습니다.8. 저장소에 올린 뒤 PASS/FAIL 확인하기
이제 네 개 파일을 GitHub 저장소에 저장합니다. 저장소 기본 브랜치가
main인지 확인하세요. 기본 브랜치 이름이 다르면 YAML의branches: [main]을 실제 이름에 맞춰 수정해야 합니다. 1단계. 네 파일과 정확한 폴더 위치를 확인합니다. 2단계. 파일을 GitHub에 커밋합니다. 이미 설정이 반영된 브랜치에push하거나, 변경 브랜치에서main대상으로 Pull Request를 만들면 조건에 맞는 실행이 시작될 수 있습니다.3단계. 저장소 상단의 Actions 탭을 엽니다. 4단계. Check AI-generated code라는 워크플로와 실행 기록을 확인합니다. 5단계. 실행을 클릭한 뒤 node-test 작업과 Run unit tests 단계를 열어 로그를 읽습니다. 성공했다면 검사 결과가 성공으로 표시됩니다. 실패했다면 어느 단계에서 멈췄는지, 코드 테스트의 실제 결과가 기대값과 어떻게 달랐는지 확인하세요.
처음부터 반드시 성공한다고 보장할 수는 없습니다. 저장소 설정, 브랜치 이름, 워크플로 문법, 계정의 Actions 실행 제한에 따라 작업이 시작되지 않거나 중간에 실패할 수 있습니다.
9. 오류를 일부러 만들어 자동 검사 원리 이해하기
연습용 브랜치에서
src/math.js를 다음처럼 잘못 고쳤다고 가정해 봅시다.
export function add(a, b) {
return a - b;
}
원래는 더하기 함수인데 빼기를 수행하도록 바뀌었습니다. 이제
add(2, 3)의 결과는 -1이므로, 테스트에 적힌 기대값
5와 다릅니다. 이 변경을 연습용 Pull Request로 올리면, 검사가
활성화된 저장소에서 실패 상태와 원인 로그가 나타나도록 설계돼
있습니다. 그 뒤 return a + b로 수정해 다시 커밋하면 통과하는지
확인할 수 있습니다. 중요: 실습을 위해 잘못된 코드를 바로 운영
중인 main에 올리지 마세요.
별도 브랜치와 Pull Request에서 먼저 확인하는 편이 안전합니다. 이 연습의 목적은 “AI가 만든 코드도 자동으로 검증할 수 있다”는 감각을 익히는 것입니다. 실패를 한 번 보는 것이 성공 표시만 보는 것보다 이해에 도움이 될 수 있습니다.
10. 검사가 실패하면 Pull Request 합치기도 자동으로 막히나요?
아닙니다. Actions에서 검사 결과가 실패했다고 해서 반드시
main에 합치는 작업이 차단되는 것은 아닙니다. 병합을 막으려면
저장소 설정에서
Branch protection rule 또는 Ruleset의 필수 상태 검사(Required status
checks)를 별도로 설정해야 합니다. 예를 들어 node-test 검사 통과를
요구하도록 정하면, 지정된 보호 규칙의 적용 범위에서는 검사에 실패한 Pull
Request가 병합되지 않도록 제한할 수 있습니다.
단, 설정할 권한과 저장소 공개·비공개 여부에 따른 기능 제공 범위가 다를 수 있습니다. GitHub 공식 도움말에서 자신의 플랜과 저장소 조건을 확인한 다음 적용하세요. 핵심 차이: GitHub Actions는 검사를 실행하고, 브랜치 보호 설정은 검사 결과에 따른 병합 규칙을 적용합니다.
11. 돈이 얼마나 들까요?
GitHub 공식 안내 기준으로 공개 저장소에서 표준 GitHub 호스팅 실행기를 사용하는 Actions 실행 시간은 무료입니다. 반면 비공개 저장소에는 플랜별 무료 실행 시간·저장 용량이 있고, 초과 사용이나 일부 실행기·저장 기능은 과금될 수 있습니다. 그래서 “GitHub Actions는 모두 무제한 무료”라고 안내하면 안 됩니다. 비공개 코드가 포함된 프로젝트에서 검사를 자주 돌리거나 스크린샷·빌드 결과물을 많이 저장하면 사용량이 누적될 수 있습니다. 오늘 예제는 테스트 두 개를 수행하는 소규모 워크플로지만, 실제 실행 시간과 비용은 계정·저장소·실행기 설정에 따라 다릅니다. GitHub에서 Billing / Actions 사용량과 한도를 확인하세요.
12. AI가 만든 코드를 자동 실행할 때 가장 중요한 보안 원칙
GitHub Actions는 테스트를 위해 실제 명령을 실행합니다. 따라서 출처를 모르는 코드나 외부 Pull Request의 코드를 실행할 때는 신중해야 합니다.
-
최소 권한: 필요 없는
write권한을 주지 말고, 읽기만 필요한 검사는contents: read로 제한합니다. - 비밀정보 보호: 비밀번호·API 키·토큰을 코드, YAML, 테스트 출력에 직접 적지 않습니다.
- 검사와 배포 분리: 테스트 워크플로에 불필요한 게시·배포 권한을 섞지 않습니다.
-
pull_request_target주의: 이 이벤트는 일반pull_request보다 높은 신뢰 권한으로 실행될 수 있습니다. 이해하지 못한 상태에서 외부 기여자의 코드를 체크아웃해 실행하지 마세요. - 액션 버전 고정: 이 글은 따라 하기 편하도록 공식 주 버전 태그를 사용했습니다. 보안이 중요한 실제 운영 저장소에서는 GitHub가 권장하는 검증된 전체 커밋 SHA 고정 등 더 엄격한 공급망 보호를 검토하세요. AI가 “테스트를 추가했습니다”라고 해도 권한이 늘었는지, 새 패키지가 추가됐는지, 비밀값이 로그에 출력되지 않는지는 사람이 검토해야 합니다.
13. 초보자가 자주 만나는 오류와 해결법
| 현상 | 먼저 확인할 점 |
|---|---|
| Actions 실행 기록이 없음 | YAML 경로·브랜치 이름·이벤트 조건·저장소 Actions 설정 |
npm test가 실패
|
package.json의 test 스크립트, 테스트 파일명·경로
|
| 코드를 찾지 못함 |
src/math.js 경로, import 상대경로, 대소문자
|
| YAML 문법 오류 | 들여쓰기, 탭 대신 공백, 올바른 콜론·파일 확장자 |
npm ci 오류
|
package-lock.json이 있는 프로젝트인지 확인
|
| 실패했는데 병합 가능 | 필수 상태 검사 규칙 설정 여부 |
코드가 실행되지 않을 때는 “GitHub Actions가 고장 났다”고 단정하기보다, Actions 탭에서 실패한 단계와 최초 오류 메시지를 확인하는 것이 좋습니다. 그래야 AI에게도 구체적인 오류를 설명하고 수정 요청을 할 수 있습니다.
14. AI에게 GitHub Actions 설정을 맡길 때 쓸 프롬프트
다음 예시는 이미 만들어진 저장소에 자동 검사를 추가할 때 사용할 수 있습니다.
“내 GitHub 저장소의 현재 언어·패키지 관리 방식·기존 테스트 명령·기본 브랜치를 먼저 확인해 줘. 이미 존재하는 워크플로를 중복 생성하지 말고, 필요한 경우에만 새 파일을 제안해 줘. Pull Request에서 코드를 자동 검사하되 배포·비밀키 접근·쓰기 권한은 추가하지 마. YAML과 테스트 명령의 근거를 설명하고, 실제 실행하지 않았다면 PASS라고 주장하지 마.
마지막에 사람이 확인해야 할 보안과 비용 체크리스트를 작성해 줘.” 여기서 “실행하지 않았다면 PASS라고 주장하지 마”라는 요청이 중요합니다. AI가 작성한 YAML이 문법상 그럴듯해 보여도, 저장소의 실제 패키지·브랜치·권한과 맞는지는 실행과 로그 검증이 필요합니다.
자주 묻는 질문(FAQ)
Q. GitHub Actions를 사용하려면 코딩 전문가여야 하나요?
아닙니다. 다만 자동으로 무슨 명령을 실행하는지, 어디에 권한을 주는지는 이해해야 합니다. 우선 단순한 테스트 하나로 시작하세요.
Q. 코드가 전혀 없는 HTML 블로그에도 쓸 수 있나요?
가능합니다. HTML 링크 확인, 파일명·문법 검사 같은 작업을 별도로 만들 수 있습니다. 다만 이 글의 Node.js 예제는 JavaScript 테스트용이므로 그대로 복사한다고 HTML 사이트가 검증되지는 않습니다.
Q. CI를 통과하면 보안도 안전한가요?
아닙니다. 해당 워크플로가 실제로 검사한 항목만 통과했다는 뜻입니다. 보안·성능·접근성·사용성 검사는 목적에 맞는 별도 도구와 사람이 필요합니다.
Q. GitHub Actions가 테스트를 통과하면 자동으로 배포되나요?
이 예제는 테스트만 수행하고 배포하지 않습니다. 배포하려면 별도의 단계와 권한·승인이 필요합니다.
Q. AI가 만든 코드가 틀려도 Actions가 성공할 수 있나요?
그렇습니다. 테스트에 없는 오류는 잡히지 않을 수 있습니다. 검사 항목의 품질도 사람이 확인해야 합니다.
Q. 파일을 GitHub에 올리면 모두에게 공개되나요?
저장소의 공개·비공개 설정에 따라 다릅니다. 테스트 로그나 업로드된 파일·아티팩트에도 기밀정보가 남지 않도록 주의하세요.
마무리: AI 코드 검증은 ‘한 번의 성공’보다 ‘반복 검사’가 중요합니다
AI가 코드를 빨리 만들어 주는 것은 큰 장점입니다. 하지만 빠르게 만들어진 코드를 사람이 매번 처음부터 확인하기는 어렵습니다. GitHub Actions는 코드가 바뀔 때마다 같은 검사를 반복 실행하도록 도와주는 도구입니다. 처음에는 오늘처럼 네 파일만 만들어 보세요. ①테스트할 코드 → ②예상 결과를 적은 테스트 → ③Actions 설정 → ④성공·실패 로그 확인 → ⑤PR 보호 규칙 검토의 순서를 익히면, 더 큰 AI 프로젝트에서도 점차 검증 범위를 넓힐 수 있습니다.
무엇보다 기억할 것은 한 가지입니다. 초록색 성공 표시가 ‘프로그램 전체의 안전 보증서’는 아닙니다. 어떤 것을 검사했는지 알고 사용하는 것이 자동화의 첫걸음입니다.
공식 참고 자료
함께 읽으면 좋은 글
- 코드란 무엇일까? — 프로그램 코드와 파일의 기본 개념
- 소프트웨어 테스트란? — PASS와 FAIL을 읽고 테스트 한계를 이해하기