Github Actions 기본적인 사용법

이전에 프로젝트에서 Github Actions을 사용해 CI/CD를 구현한 적이 있었다. 그 당시에 굉장히 간단하게 이를 구현할 수 있어서 추후에도 계속 사용해볼 생각이었다. 그러다 이번에 일하게 된 회사에서 기존 젠킨스로 진행하던 CI 플로우를 Github Actions로 이관하는 작업을 맡게되었다. Github Actions은 꽤나 다양한 기능들이 있지만 은근히 설명이 찾기힘들어서 이번에 간단하게나마 정리해보고자 한다.

이번에는 Github Actions의 기본적인 사용법을 정리하려 한다.

Github Actions?

Github Actions은 레포지토리 페이지에서 상단의 Actions 탭에서 확인할 수 있다. Github Actions에서 Workflow란 하나 혹은 여러 개의 Job으로 이루어져 있는 프로세스라고 생각하면 된다. 예를 들면 CI Workflow와 CD Workflow라는 것이 있다고 생각할 수 있다. 위 사진에서는 아무런 Workflow가 없기에 해당 페이지가 나온다.

만약 한개 이상의 워크플로우가 있다면 위 사진과 같은 페이지를 볼 수 있다.

Github Actions에서는 .yml 형식의 설정 파일을 작성하여, 워크플로우를 만든다. 이 설정 파일의 간단한 사용법과 문법에 대해 알아보자.

Workflow file

위에서 말했듯이 Github Actions은 .yml 또는 .yaml 형식의 워크플로우 파일에 설정과 동작들을 정의한다. 해당 파일은 프로젝트 루트의 .github/workflows 디렉토리에 위치해야 한다.

위 사진처럼 .github/workflows 디렉토리에 원하는 파일명으로 만들어주자.

name: Github Actions Workflow Test

on:
  push:
    branches: [dev, main]

env:
  NODE_VERSION: 16.14.0

jobs:
  test:
    runs-on: ubuntu-latest
    name: 프로젝트 Lint Test
    steps:
      - uses: actions/checkout@v2

      - uses: actions/setup-node@v2
        with:
          node-version: ${{ env.NODE_VERSION }}

      - name: Install Dependencies
        run: npm install

      - run: npm run lint

해당 파일은 위처럼 작성하였다. yml 파일은 인덴트가 중요하므로, 잘 지켜주자. 프로젝트는 NodeJs로 작성했으며, 해당 워크플로우는 eslint 테스트를 진행한다. 이제 위 파일의 문법들을 하나씩 설명해 보겠다.

name

name: Github Actions Workflow Test

name 속성의 값은 해당 워크플로우의 이름이다. 위 예시에서는 Github Actions Workflow Test으로 워크 플로우의 이름을 지은 것이다.

워크 플로우의 이름은 위 사진처럼 Github Actions 탭에서 나타난다.

name 속성이 없다면, 워크플로우 파일의 상대경로가 표시된다.

on

워크플로우의 실행 트리거이다. 해당 속성에 정의된 이벤트들이 발생하면, 해당 워크플로우가 실행된다.

on: push

한개의 트리거만 간단하게 사용할 때는 위처럼 기입할 수 있다. 위 예시에서는 어떤 브렌치든 push 이벤트가 발생하면 워크플로우가 실행된다.

on: [push, pull_request]

위처럼 배열의 형태로 여러개의 트리거를 설정할 수 있다. 위 예시에서는 어떤 브렌치든 push 혹은 PR 이벤트가 발생하면 트리거된다.

on:
  push:
    branches: [dev, main]

첫 예시에서처럼 필터를 적용할 수도 있다. 위 예시의 경우 dev 브렌치와 main 브렌치에 Push 이벤트가 발생하면 트리거된다.

on:
  push:
    branches: main
  pull_request:
    branches: [dev, main]

물론 위처럼 여러개의 이벤트에 필터를 적용할 수 도 있다.

위에서 언급한 push, pull_request 말고도 더 많은 이벤트들이 있다. 추후에 몇몇 이벤트는 게시글로 정리할 예정이지만, 모든 이벤트들을 확인해보고 싶다면 다음 Events that trigger workflows 문서를 참고하자.

env

env:
  NODE_VERSION: 16.14.0

워크플로우 내에서 사용할 환경변수를 설정한다. 위 예시에서는 NODE_VERSION 환경변수에 16.14.0을 할당해준 것이다.

- uses: actions/setup-node@v2
  with:
    node-version: ${{ env.NODE_VERSION }}

workflow 내에서 해당 값을 꺼내고 싶다면, 위처럼 ${{ env.변수명 }}의 형식으로 기입해주면 된다. ${{ }}는 Github에서 사용하는 expression syntax이다. 내부의 표현식을 분석/실행하여 해당하는 값을 반환해준다. 위 예시에서는 env.NODE_VERSION의 값을 반환해주는데, 해당 값은 16.14.0이므로 이 값을 반환해준다.

jobs

jobs:
  <job id>:
    <job 설정>
    steps:
      <step들>

위에서 워크플로우는 하나 혹은 여러개의 Job으로 이루어진다고 했다. jobs에서 이 Job들을 정의해준다. 위처럼 <job id> 구문으로 하나의 Job을 만들어주고, 내부에 해당 Job의 설정이나 각 단계(steps)을 정의해준다.

jobs:
  test:
    runs-on: ubuntu-latest
    name: 프로젝트 Lint Test
    steps:
      생략

처음의 예시에서는 job id가 test인 Job을 하나 만들어 준 것이다.

runs-on은 해당 Job을 실행하는 환경을 정해주는 것이다. 여기서는 ubuntu-latest를 사용한다. Actions Docs - runs-on에서 더 많은 환경을 볼 수 있다. 참고로 위와 같이 Github에서 제공해주는 환경 말고도 Self-Hosted Runner라는 것을 사용하여 내가 직접 실행할 러너를 만들어서 사용할 수도 있다.

name은 해당 Job의 이름을 정해준다. 해당 이름은 위처럼 Github Actions 탭의 워크플로우 내에서 볼 수 있다. 자세한 내용은 후술하겠다.

jobs:
  test:
    runs-on: ubuntu-latest
    name: 프로젝트 Lint Test
    steps:
      생략
  docker-build:
    runs-on: ubuntu-latest
    name: Docker build
    steps:
      생략

위처럼 여러개의 Job을 설정해줄 수도 있다.

jobs.<job_id>.steps

Job은 steps으로 불리는 일련의 작업들로 이루어져 있다. 이 스텝은 커맨드나 Setup Task등을 실행할 수 있다. 혹은 깃헙 레포지토리나 도커 레지스트리에 올라가있는 Action들을 실행할 수도 있다. 하나의 Job 내의 스텝들은 순차적으로 실행된다. 같은 Job의 스텝들은 동일한 러너에서 실행되기에 파일시스템을 공유한다. 하지만 Job의 각 스텝은 자체 프로세스를 가지기에, 한 스탭이 환경변수를 변경해도 이를 각 스텝들간 유지되지 않는다.

steps:
  - uses: actions/checkout@v2

  - uses: actions/setup-node@v2
    with:
      node-version: ${{ env.NODE_VERSION }}

  - name: Install Dependencies
    run: npm install

  - run: npm run lint

위처럼 steps 내에 수행할 명령들을 정의해줄 수 있다. 위 예시에서는 먼저 체크아웃을 한 뒤, node를 셋업하고 디펜던시를 설치해준 다음, eslint test를 진행한다.

실행하는 명령의 종류는 run과 uses 두개로 나누어 볼 수 있다. 우선 run부터 알아보자.

- name: Install Dependencies
  run: npm install

- run: npm run lint

run은 실행할 shell command를 정의해준다. 위 예시에서는 실행할 커맨드로 npm install이나 npm run lint를 지정해준 것이다. 여기서 name 속성으로 스텝의 이름을 정해줄 수 있다.

- name: Install Dependencies & Lint Test
  run: |
    npm install
    npm run lint

만약 여러 줄의 명령어를 입력하고 싶을 경우 |을 넣어주고 다음 줄부터 명령어를 입력하면 된다. 단, 이때도 인덴트가 중요하므로 주의하자.

- uses: actions/checkout@v2

- uses: actions/setup-node@v2
  with:
    node-version: ${{ env.NODE_VERSION }}

uses는 github 레포지토리나 도커 레지스트리에 정의되어 있는 Actions을 실행하라고 정의해준다. 위 예시에서는 actions/checkpout@v2 Action을 실행하라고 했는데, 해당 액션은 https://github.com/actions/checkout에서 볼 수 있듯이 레포지토리에 정의되어있다. 이처럼 uses를 통해 이미 정의된 액션을 사용함으로써 매우 간편하게 내가 원하는 일들을 할 수 있다.

그리고 with 구문을 통해 해당 액션에서 필요로 하는 Input 파라미터를 넘겨줄 수 있다. 위 예시에서는 설치할 노드 버전을 넘겨주었다.

Github Actions 확인

처음 예시에서 트리거 이벤트를 main 혹은 dev 브렌치의 Push로 정의해주었다. 실제로 동작하는지 확인해보자.

위처럼 dev branch에 push를 해주었다.

이후 Actions 페이지로 가보면, 위처럼 해당 워크플로우가 실행 중인 것을 확인할 수 있다. 더 자세히 보기 위해 해당 workflow run을 클릭해보자.

그러면 위 사진처럼 실행되고 있는 Jobs과 상태를 확인할 수 있다. 프로젝트 Lint Test Job의 각 step에 대한 상태를 보고 싶다면, 해당 Job을 클릭해주면 된다.

그러면 위 사진처럼 각 step의 상태를 볼 수 있다.

왼쪽의 화살표를 클릭해 터미널 출력도 확인해볼 수 있다.

워크플로우의 실행이 정상적으로 끝났다면 위처럼 초록불을 볼 수 있다.

워크플로우의 실행 중 에러가 발생하는 경우 위처럼 빨간불을 볼 수 있다. 테스트 실패도 에러로그를 뱉기때문에, 에러로 판단된다. 위 사진처럼 Summary에서 에러로그를 간단하게 볼 수도 있으며, 자세히 보고 싶다면 해당 step의 로그를 확인하자.

워크플로우의 실행 결과는 연결된 커밋이나 PR등에서도 확인할 수 있다.

총총

굉장히 간단한 내용들만 설명했지만, 이 내용들만 가지고도 대부분의 작업들을 수행할 수 있을 것이다. 각 요소에 대한 자세한 설명은 추후에 정리할 예정이다,