Github Action을 이용해 AWS Lightsail CI/CD 파이프라인 구축하기 2편

서론

1편까지 Github Action과 Lightsail을 연결하기 위한 환경설정을 했다. 이번 편에서 실제로 Github Action에서 yml을 이용해 워크플로우를 만든뒤, Lightsail 인스턴스에 접근하고 배포를 자동화 해보자.

동작 방식

Github Action은 workflow를 실행하기 위해 러너라는 가상환경을 제공한다.우리는 이 러너 위에서 다음과 같은 작업들을 순차적으로 수행한다.

1. 코드 변경 감지 (main 브랜치에 push 또는 PR 발생 시)
2. Node.js 환경 구성 및 빌드
3. 빌드 파일을 Lightsail로 전송
4. Lightsail 서버에서 pm2로 서버 재시작

전체 흐름 요약

name: CI CD

on:
  push:
    branches: ['main']
  pull_request:
    branches: ['main']

env:
  LIGHTSAIL_SSH_KEY: ${{ secrets.LIGHTSAIL_SSH_KEY }}
  LIGHTSAIL_HOST: ${{ secrets.LIGHTSAIL_HOST }}
  LIGHTSAIL_USERNAME: bitnami
  AWS_REGION: ap-northeast-2

이 설정은 main 브랜치에 푸시되거나 PR이 생성될 때 워크플로우를 실행한다. 배포 대상은 AWS Lightsail이며, 필요한 정보는 모두 GitHub Secrets에 미리 등록되어 있어야 한다.

---

⚙️ 각 단계별 설명

1. 코드 체크아웃

- name: 해당 브랜치로 체크아웃
  uses: actions/checkout@v2

GitHub Actions의 러너에 현재 브랜치의 코드를 다운로드한다.

---

2. Node.js 설치

- name: 노드 설치
  uses: actions/setup-node@v1
  with:
    node-version: 14

CI/CD 환경에서 Node.js 기반 프로젝트를 실행하기 위한 환경을 구성한다.

---

3. 프로젝트 디펜던시 설치

- name: 프로젝트 디펜던시 설치
  run: yarn

package.json에 명시된 의존성을 설치를 한다.
(※ npm을 사용하는 경우에는 npm install로 대체)

---

4. 프로젝트 빌드

- name: 프로젝트 빌드하기
  run: yarn build

Next.js, Vite, Express 등 각 프로젝트에 맞는 빌드 명령어를 실행한다.
이 과정에서 최종 결과물인 dist/ 폴더가 생성된다

---

5. 빌드 결과 확인

- name: 빌드 파일 생성 체크
  run: ls -la

빌드가 정상적으로 완료되었는지 디렉토리 목록을 확인하게 하였다. (디버깅용)

---

6. AWS 인증

- name: AWS 인증하기
  uses: aws-actions/configure-aws-credentials@v1
  with:
    aws-region: ${{ env.AWS_REGION }}
    aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
    aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

GitHub 러너가 AWS CLI를 사용할 수 있도록 인증을 진행한다.
이 인증은 이후 ssh 접속과 배포 과정에 필수이다.

---

7. 인증 테스트

- name: AWS Lightsail에 연결되었는지 확인
  run: aws configure list

인증 정보가 제대로 반영되었는지 확인.

---

8. 빌드 파일 전송

- name: 배포 자동화
  uses: appleboy/scp-action@master
  with:
    host: ${{ secrets.LIGHTSAIL_HOST }}
    username: ${{env.LIGHTSAIL_USERNAME}}
    key: ${{ secrets.LIGHTSAIL_SSH_KEY }}
    source: 'dist/*'
    strip_components: 1
    target: '/home/bitnami/{project-name}/dist'

빌드된 파일(dist/)을 Lightsail 인스턴스의 프로젝트 디렉토리로 복사한다.
이때 SSH 키 기반 인증을 사용한다.

---

9. PM2 프로세스 재시작

- name: Restart PM2 process
  uses: appleboy/ssh-action@master
  with:
    host: ${{ secrets.LIGHTSAIL_HOST }}
    username: ${{env.LIGHTSAIL_USERNAME}}
    key: ${{ secrets.LIGHTSAIL_SSH_KEY }}
    script: pm2 restart app

전송한 파일을 적용하기 위해 pm2 프로세스를 재시작한다.
이 스크립트는 Lightsail에 SSH 접속해 직접 실행된다.

---

배포 자동화를 위한 플러그인 선택

GitHub Actions에는 수많은 플러그인(Action)이 존재하는데, 프로젝트 성격에 따라 알맞은 Action을 선택하는 것이 중요하다.
이번 CI/CD 구성에서는 다음과 같은 플러그인들을 사용했다:

aws-actions/configure-aws-credentials@v1: GitHub Actions 러너가 AWS CLI를 사용할 수 있도록 인증해주는 플러그인이다. Lightsail에 접근하기 위해 필수로 사용했다.

appleboy/scp-action@master: 빌드된 결과물(dist/ 폴더)을 SSH 기반으로 Lightsail 인스턴스에 복사한다.

appleboy/ssh-action@master: 복사된 프로젝트를 pm2로 재시작하기 위한 SSH 원격 실행용 플러그인이다.

Github Actions에는 다양한 플러그인이 존재하는데 자기에게 알맞는 플러그인을 찾아서 잘 사용해보자. 나는 aws-actions/configure-aws-credentials@v1를 사용해 AWS-Lightsail에 연결해주었다.

빌드 결과물 배포

Node.js 프로젝트를 yarn build로 빌드하면 dist/폴더가 생성된다.
이 폴더를 Lightsail 인스턴스의 /home/bitnami/{project-name}/dist 경로로 전송한다.
전송 후에는 해당 디렉토리에 있는 파일로 서비스를 실행해야 하므로, 서버에 SSH로 접속해 pm2 restart 명령어를 실행한다.

참고로 pm2는 Lightsail 인스턴스에 미리 설치해두었고, 프로젝트 시작 시에도 pm2 start로 앱을 등록해둔 상태다

마무리

이처럼 GitHub Actions를 활용하면, 기존에 매번 터미널에서 수동으로 수행하던 반복 작업을 완전히 자동화할 수 있었다.
CI/CD가 도입된 이후 배포 실수는 줄었고 배포 속도는 체감상 80% 이상 빨라졌다.