GitHub Actions 활용하기

안녕하세요, 네이버 페이에서 프론트엔드를 개발하고 있는 이창재입니다.

네이버 파이낸셜에서는 GitHub를 통해 코드를 관리하고 있고, 자연스레 GitHub Actions를 활용하여 효율성을 더하고 있습니다.

이번 글에서는 실제 사용중인 GitHub Actions 중 간단한 예시와 함께 해당 개념에 대해 소개하고자 합니다.
시작에 앞서 기본 개념을 짚고 넘어가겠습니다.

👀 GitHub Actions?

GitHub Actions란 GitHub 저장소를 기반으로 워크플로우를 자동화 할 수 있는 도구, GitHub가 제공하는 완전관리형 CI/CD 툴입니다.

✒️ CI/CD?

참고 자료 : RedHat 문서 — CI/CD란?

📄 CI(Continuous Integration) — 지속적인 통합
* PR이나 push된 코드를 빌드 및테스트하는 프로세스를 자동화하고, 이러한 프로세스를 거친 후 코드를 merge해 주는 자동화 프로세스입니다.
* 이 과정에서 충돌이나 Lint, 정상 동작 등 자동화된 테스트를 실행하여 변경 사항을 검증합니다.

📄 CD(Continuous Delivery, Deployment) — 지속적인 제공 및 배포
* Delivery(지속적 제공) : CI를 거친 후 레포에 업로드되는 것을 의미합니다.
* Deployment(지속적 배포) : 배포과정을 자동으로 처리해주는 것을 의미합니다.

📄 CI/CD의 목적
반복적인 일(빌드, 테스트, 배포 작업 등)을 처리하고 그 과정에서 이슈 발생 시 경고해주는 등, 자동화된 파이프라인을 통해 코드 변경과 배포 단계를 원활하게 진행할 수 있도록 해 줍니다.
이 과정에서 시간 절약 및 사람이 직접적으로 처리할 때 발생하는 실수, 즉 휴먼에러를 방지할 수 있습니다.

🎯GitHub Actions 특징

* 컨테이너(도커) 기반으로 동작합니다.
* 개발자는 워크플로우를 작성하여 다양한 이벤트 기반으로 실행시킬 수 있습니다.
* 워크플로우는 Runners라 불리는 인스턴스에서 리눅스, 맥, 윈도우 환경에서 실행됩니다. (동시 테스트도 가능!)
* GitHub 마켓 플레이스에서 필요한 Workflow를 찾아 사용할 수 있고, 직접 만들어 마켓 플레이스에 공유할 수도 있습니다.

😄GitHub Actions의 장점

* 다른 CI/CD툴(ex. 젠킨스)처럼 별도 서버 설치와 같은 복잡한 절차 없이 사용이 가능합니다.
* 즉 GitHub에서 제공하는 완전 관리형 서비스이므로 설정이 매우 간편하고 GitHub API에도 쉽게 접근할 수 있습니다.
* 비동기적 병렬 실행이 가능한 CI/CD입니다.
* GitHub 마켓플레이스를 통해 필요한 워크플로우를 내려 받거나 공유할 수 있습니다.

🤔GitHub Actions의 단점

* 서버에 장애가 일어나거나 리소스를 초과할 경우 개발자가 직접 문제를 해결해야 합니다.

⚙️GitHub Actions 핵심 개념

참고자료 : GitHub Docs — GitHub Actions 이해

Workflows
* GitHub Actions의 기본 구성 단위로써 가장 최상위 개념입니다.
* 자동화된 프로세스가 정의되어 있는 파일로 YAML 파일에 정의됩니다.
* 하나 이상의 작업을 포함할 수 있으며 해당 파일을 실행할 규칙, 동작 등이 작성되어 있습니다.

Events
* 워크플로우를 시작하는 트리거(push, PR 등)로써, 워크플로우 파일 내에 정의됩니다.

Jobs
* 워크플로우 내에서 실행되는 개별 작업입니다.
* 이벤트로 워크플로우가 실행되면 Job에 작성된 명령들이 Runner에서 실행됩니다.
* 기본적으로 Job들은 병렬로 실행되지만, 서로 의존관계를 가질 수도 있고 직렬로 실행할 수도 있습니다.
* Job은 자신의 환경 설정과 Steps를 가지고 있습니다.

Steps
* Job내 작업의 가장 작은 단위입니다.
* 각 step들은 스크립트나 명령어 또는 액션을 실행할 수 있습니다.

Actions
* 작업 흐름에서 공유 및 결합할 수 있는 재사용 가능한 코드 단위입니다. 컴포넌트라고 볼 수 있습니다.
* 마켓에 등록되어 있는 Action을 가져오거나, 별도 레포에 작성하여 해당 레포의 이름으로 워크플로우의 파일에서 참조할 수 있습니다.

Runners
* 워크플로우가 실행되는 가상 머신 또는 자체 호스팅 환경입니다.
* 기본적으로 GitHub에서 워크플로우를 구동할 리눅스, 윈도우, 맥OS 운영체제의 Runner를 제공하며, 필요시 self-hosted-runner를 등록할 수도 있습니다.

GitHub Actions에는 도커(Docker) 컨테이너 액션, 복합(Composite) 액션, 그리고 자바스크립트를 활용한 액션, 이렇게 3가지 종류의 액션이 존재합니다.
그 중 이번 글에서는 자바스크립트를 활용한 액션 예시를 준비했습니다.
아래는 해당 예시를 위한 특정 상황입니다.

정기배포 이후 릴리즈 브랜치를 alpha나 beta와 같은 기존 작업 브랜치에 머징해야 할 필요성이 있습니다.
하지만 해당 PR 생성 후 Lint나 Unit Test와 같은 테스트 워크플로우들이 모두 실행 완료될때까지 기다리기엔 너무나도 귀찮습니다.
가끔 일에 치여 머징하는걸 깜빡하고 한참 후에 최근 릴리즈 브랜치가 반영되지 않았다는 것을 깨닫기도 합니다.
따라서 특정 워크플로우 체킹이 완료된 후 source branch가 `release/`로 시작하면 머징을 진행하는 자동화된 워크플로우가 있으면 좋겠다는 생각을 하게 됩니다.

해당 예시의 전체적인 레포 구조는 위와 같습니다.

📑action.yaml
가장 먼저 action에 대해 작성할 필요가 있습니다.
기본적으로 해당 action의 설명과 필요한 파라미터를 기술하는 부분으로 크게 name, description, inputs, runs, branding 5가지 섹션으로 나누어져 있습니다.
이 중 name, description, runs는 필수로 작성해주어야 합니다.

name: Auto merge when head branch starts with 'release/'
description: 'Prevent merging if a specific label is attached to a PR'
inputs:
    token:
        description: 'Github token'
        required: true
    workflow:
        required: true
        description: 'File name of the workflow you wanna wait for'
    interval:
        description: 'The interval between workflow checks (default is 3s)'
runs:
    using: 'node16'
    main: 'dist/index.js'

📄inputs
inputs.<input_id> — token, workflow, interval
필요한 input 파라미터의 변수명을 지어줍니다. 이 변수명은 나중에 js 코드상으로 불러올때 필요하기에 의미에 맞게 작성할 필요성이 있습니다.

inputs.<input_id>.description
input 파라미터에 대한 설명을 적어줍니다.

inputs.<input_id>.required
필수 파라미터 여부를 표시해줍니다.

inputs.<input_id>.default
필요 시 디폴트 값을 설정해 줍니다. 이때 무조건 string 값만 사용할 수 있습니다.

📄runs
runs.using
코드를 실행시킬 환경을 설정합니다. (필수)

runs.main
실행할 필수 작업 코드가 포함된 파일의 main path를 지정합니다. (필수)

runs.env
필요한 환경변수를 지정합니다

📄branding
마켓플레이스 배포 시 표시될 아이콘을 설정해 줍니다.

📑src/index.ts
본격적인 action 작업코드를 작성하는 파일입니다.
해당 자바스크립트 코드 작성 도와주는 다양한 툴킷이 존재합니다.
여기서는 @actions/core와 @actions/github을 사용하여 개발을 진행하였습니다.
* @actions/core: workflow에 대한 inputs, outputs, logging 등의 함수를 제공합니다.
* @actions/github : 인증된 Octokit client를 제공해줍니다.

import * as core from '@actions/core'
import * as github from '@actions/github'

async function run(): Promise<void> {
    const workflows: string[] = core
        .getInput('workflow', {
            required: true,
        })
        .split('|')
        .map((item) => item.trim())
    const interval: number = +core.getInput('interval') * 1000 || 3000
    const token: string = core.getInput('token', {
        required: true,
    })
    const memes = [
        '잘했어요 밈1',
        '잘했어요 밈2',
        '잘했어요 밈3',
        '잘했어요 밈4',
        '잘했어요 밈5',
        '잘했어요 밈6',
    ]
    const octokit = github.getOctokit(token)
    const {pull_request} = github.context.payload
    const {owner, repo} = github.context.issue
    const pr_number = pull_request?.number
    const head_ref = pull_request?.head?.ref || ''

    try {
        for (const workflow of workflows) {
            core.info(`Waiting until workflow ${workflow} ends`)

            let workflowIsRunning
            do {
                await new Promise((resolve) => setTimeout(resolve, interval))
                workflowIsRunning = await checkIfWorkflowIsRunning(workflow)
            } while (workflowIsRunning)
        }

        if (pr_number && head_ref.startsWith('release/')) {
            await octokit.rest.pulls.createReview({
                owner,
                repo,
                pull_number: pr_number,
                body: memes[Math.floor(Math.random() * memes.length)],
                event: 'APPROVE',
            })

            await octokit.rest.pulls.merge({
                owner,
                repo,
                pull_number: pr_number,
                merge_method: 'merge',
            })
            core.info('LGTM & Merge')
        } else {
            core.info(`Check exist PR number : ${pr_number} or source branch(${head_ref}) starts with release/`)
        }
    } catch (error) {
        if (error instanceof Error) {
            core.setFailed(error.message)
        }
    }
}

run()

async function checkIfWorkflowIsRunning(workflow: string): Promise<boolean> {
    const token: string = core.getInput('token', {
        required: true,
    })
    const octokit = github.getOctokit(token)
    const {owner, repo} = github.context.issue
    const {
        data: {workflow_runs},
    } = await octokit.rest.actions.listWorkflowRuns({
        owner,
        repo,
        workflow_id: workflow,
        per_page: 5,
    })

    return workflow_runs.some(
        (workflow_run) => workflow_run.status === 'queued' || workflow_run.status === 'in_progress',
    )
}

📄input값 가져오기
위 action.yaml에서 지정한 input값의 경우 core.getInput({input_변수명})으로 불러올 수 있습니다.

input값을 가져오는 방법만 안다면 나머지 로직의 경우 개발자가 원하는 대로 작성할 수 있습니다.
위 예시에서처럼 github의 기능(pull request 작성, apporve, merge 및 owner, repo등 값 추출 등)을 사용하고 싶다면 octokit document를 참고하여 작성해 주면 됩니다. 😎

🚀만든 액션 사용해보기

위와 같이 작성된 액션은 사용하고자 하는 레포의 ./github/workflows 폴더 내에 워크플로우를 작성하여 사용할 수 있습니다.

# 워크플로우의 이름입니다.
name: test-workflow

# 워크플로우를 동작하게 하는 트리거입니다.
# 해당 트리거의 종류는 아래 GitHub Docs에서 확인할 수 있습니다.
# https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request
on:
  # 여기서는 alpha, beta 브랜치를 대상으로 pull reqeust가 발생할 때 트리거링되도록 작성되었습니다.
  pull_request:
    branches:
        - alpha
        - beta

# 위에서 서술한 jobs의 핵심 개념과 동일한 개념입니다.
jobs:
 # 여기서는 call-workflow라는 하나의 job을 작성하였습니다.
 call-workflow:
    # 구동 환경입니다. 여기서는 리눅스 환경에서 실행합니다.
    runs-on: ubuntu-latest
    # 위에서 서술한 steps의 핵심 개념과 동일한 개념입니다.
    # 상세 내용은 아래 GitHub Docs에서 확인할 수 있습니다.
    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idsteps
    steps:
        - name: check PR
          # 사용할 액션 위치입니다. 소유자/저장소@브랜치 형태로 가리켜주면 됩니다.
          uses: common/auto-release-merge-action@main
          # with 키워드를 통해 action에 값을 전달할 수 있습니다.
          # 이전 작성한 액션에서 token, workflow 파라미터를 필수 필요로 했으므로 해당 값을 전달해 줍니다.
          with:
            token: ${{ secrets.ACTION_TOKEN }}
            workflow: 'ci.yaml | lint.yaml'

여기서 token의 secrets 값의 경우 레포 세팅 탭에서 설정할 수 있습니다.

Settings > Secrets and Variables > Actions 에서 환경변수를 생성하여 secrets.환경변수명 으로 호출할 수 있습니다.
GitHub Actions를 사용할 때 민감한 정보의 경우는 여기서 관리하면 좋습니다.

네이버 파이낸셜에서 사용중인 GitHub Actions 중 간단한 예시를 개념과 함께 살펴보았습니다.

GitHub Actions은 이 글에서 설명된 작업 말고도 훨씬 다양한 상황에서 사용될 수 있습니다. 여러분들의 레포에서 단순 반복되는 작업이 존재한다면 이번 기회에 GitHub에게 맡겨보는 건 어떨까요? 😊

이 포스트가 여러분들께 조금이나마 도움이 되었으면 합니다. 읽어주셔서 감사합니다 🙇‍♂️

🔖참고 자료

* RedHat 문서 — CI/CD란?
* Github Actions or Jenkins? Making the Right Choice for You
* GitHub Docs — GitHub Actions
* Octokit Document