워크플로 파일은 저장소 루트의 .github/workflows/ 아래에 두고, 확장자는 .yml 또는 .yaml 입니다. 파일 하나가 워크플로 하나입니다.
| 키 | 의미 |
|---|---|
name |
Actions 탭에 표시할 워크플로 이름 |
on |
어떤 이벤트에서 실행할지(트리거) |
jobs |
워크플로 안의 잡(job) 목록 |
runs-on |
잡을 실행할 러너 환경(예: ubuntu-latest) |
steps |
잡 안에서 순서대로 실행할 작업 목록 |
잡은 기본적으로 서로 다른 러너에서 병렬로 실행되고, 같은 잡 안의 스텝은 위에서 아래로 순서대로 실행됩니다.
러너는 빈 가상 머신으로 시작하므로 저장소 코드가 없어, actions/checkout@v4 스텝이 현재 커밋을 러너 작업 폴더로 내려받습니다. actions/setup-java@v4 는 distribution·java-version 으로 지정한 JDK 를 설치하고 PATH 에 등록하며, 이 두 스텝이 거의 모든 자바 워크플로의 첫머리에 옵니다.
on: 아래에 이벤트를 하나 이상 적습니다. 이벤트마다 세부 조건(브랜치·경로 등)을 더 좁힐 수 있습니다.
| 트리거 | 발생 시점 |
|---|---|
push |
지정한 브랜치에 커밋을 올릴 때 |
pull_request |
PR 을 열거나 새 커밋을 추가할 때 |
workflow_dispatch |
Actions 화면에서 수동으로 실행 버튼을 누를 때 |
schedule |
cron 표현식으로 정한 시각마다(UTC 기준) |
push·pull_request 는 branches: 로 대상 브랜치를 좁히고, workflow_dispatch 는 사람이 원할 때, schedule 은 정기 점검처럼 시간 기반으로 실행할 때 씁니다.
| 구분 | run |
uses |
|---|---|---|
| 실행 대상 | 러너 셸의 명령어 | 마켓플레이스의 재사용 액션 |
| 예시 | run: javac -d out src/Main.java |
uses: actions/checkout@v4 |
| 로컬 재현 | 미니 러너로 그대로 실행 가능 | 러너 전용 기능이라 건너뜀 |
run: 은 셸 스크립트 한 줄(또는 | 로 여러 줄)을 그대로 실행합니다. uses: 는 다른 저장소에 공개된 액션을 버전 태그와 함께 불러와 실행합니다.
env: 는 잡·스텝 범위의 일반 환경변수를 정의합니다. 값이 로그에 그대로 남아도 되는 값(예: APP_ENV)에 씁니다.
secrets: 는 저장소 설정(Settings → Secrets)에 등록한 값으로, 워크플로에서는 ${{ secrets.이름 }} 으로만 참조합니다. GitHub 는 시크릿 값이 로그에 출력되면 자동으로 *** 로 마스킹합니다.
시크릿은 코드에 직접 적지 않고, 값을 아는 사람도 워크플로 로그에서는 원문을 볼 수 없습니다. 이 레슨의 미니 러너도 같은 마스킹을 sed 로 흉내 냅니다.
strategy.matrix 는 같은 잡을 여러 조합으로 반복 실행합니다. 예를 들어 java: [17, 21] 이면 잡이 두 번(Java 17용, Java 21용) 병렬로 돕니다.
매트릭스 값은 ${{ matrix.java }} 로 스텝 안에서 참조합니다. 지원 버전을 넓힐 때 잡을 복사하지 않고 배열 원소만 추가하면 됩니다.
actions/cache@v4 는 path(캐시할 폴더)와 key(캐시 식별자)를 받습니다. key 에 hashFiles('**/pom.xml') 처럼 파일 해시를 넣으면 의존성 파일이 바뀔 때만 새 키가 생겨 캐시가 자동 갱신됩니다.
빌드 산출물(jar, 테스트 리포트 등)은 러너가 끝나면 사라지므로, 남기려면 actions/upload-artifact@v4 로 업로드합니다. name 은 화면에 보일 이름, path 는 올릴 파일·폴더이며, 다른 잡에서 actions/download-artifact 로 이어받을 수 있습니다.
인터넷이 없는 환경이라 실제 화면 대신 텍스트로 재현합니다. 매트릭스 두 개가 병렬로 도는 모습입니다.
Actions ▸ CI ▸ #12 (workflow_dispatch by kim)
✔ build (java 17) 1m 02s
✔ build (java 21) 1m 05s
build (java 21)
✔ actions/checkout@v4 · setup-java@v4 · cache@v4 Cache restored: m2-3a9f1c
✔ 자바 버전 확인 Java 버전: 21
✔ 배포 토큰 확인 token=***
✔ 컴파일 · 실행 CI build ok
✔ actions/upload-artifact@v4 Uploaded build-output (1 file)체크 표시는 성공한 스텝, 시간은 잡 전체 소요 시간입니다. 스텝을 펼치면 그 스텝의 로그만 볼 수 있습니다.
uses: 스텝은 GitHub 러너 전용이라 로컬에서 그대로 실행할 수 없지만, run: 스텝은 결국 셸 명령이라 로컬 bash 로 재현할 수 있습니다.
이 레슨의 run_workflow 함수가 그 역할을 합니다. yml 파일에서 run: 으로 시작하는 줄만 grep·sed 로 뽑고, ${{ matrix.java }}·${{ secrets.DEPLOY_TOKEN }} 같은 표현식을 실제 값으로 바꿔 한 줄씩 실행합니다.
푸시하기 전에 스텝 순서와 명령어 오타를 로컬에서 먼저 잡을 수 있어, 워크플로를 고칠 때마다 커밋을 반복하지 않아도 됩니다.