[Github Actions] Github Actions(CI/CD)로 Vercel 자동 배포하기 (feat. yarn)

 

월화수 추석 연휴라서 어제(월요일)는 쉬었고 오늘 오후부터 슬금슬금 다시 작업중인데, 하루 푹 쉬니까 컨디션이 좋다!

 

또 요새 개인적인 일로 가족이랑 시간보내는 걸 뒤로 미뤘는데, 이번 연휴에는 통으로 함께 보내게 되어서 행복하다😊 푹 쉬었으니 다시 작업하러 가보자고~~!

 

 

Github Pages에서 Vercel로 변경

---

저번주에 React에서 Next.js로의 마이그레이션을 마치고, 오늘은 Github Actions로 Vercel가 자동 배포 되도록 환경을 셋팅했다.

 

기존에는 github pages로 배포 했었는데, Next.js로 마이그레이션 하면서 Vercel로 배포하는 것으로 바꾸었다.

 

이유는 아무래도 Vercel이 Next.js에서 공식적으로 제공하는 호스팅 사이트이기 때문이다. 공식문서에도 Next.js로 작업하는 경우 Vercel로 배포하는 것을 권장해서 바꾸게 되었다. 

Deploying to Vercel is zero-configuration and provides additional enhancements for scalability, availability, and performance globally. However, all Next.js features are still supported when self-hosted.

- Vercel

 

 

 

Github Actions를 이용해서 Vercel 자동배포하기

---

Github Actions를 이용해 배포하는 방법은 공식문서에 친절하게 나와있다.

 

1. .github/workflows 폴더 생성

먼저 프로젝트의 루트에서 .github폴더를 생성한 뒤, 하위 폴더로 workflows 폴더를 생성한다.

착한 사람에게는 ISSUE_TEMPLATE 폴더가 안 보일것이다^^

 

 

 

2. YAML 파일 생성

.github/workflows 내에서 생성하는 파일은 YAML 파일로 생성해야 한다.

YAML은 이번에 처음 알게 됐는데, 아래에 간단하게 정리해보았다.

YAML이란?

'YAML'은 'YAML은 마크업 언어가 아니다(YAML Ain't Markup Language)' 또는 '또 다른 마크업 언어(Yet Another Markup Language)'의 약어이다.

간단히 말해서, YAML은 데이터를 저장하고 전달하기 위한 형식이다. YAML의 가장 큰 특징은 단순성과 가독성이며 사람이 읽기 쉽도록 설계되어 있다.

YAML은 주로 설정 파일을 작성할 때 사용되는데, .github/workflows 디렉토리에 있는 GitHub Actions의 워크플로우 파일도 YAML 형식으로 작성된다.

그렇다면 YAML을 사용하는 이유가 복잡한 CI/CD 파이프라인을 구성하는 데 적합하기 때문이라고 생각해도 되지 않을까? 😲

 

Xml, Json, Yaml을 비교한 사진이다. 가독성 측면에서 yaml이 좋은 것을 알 수 있다.

 

 

 

3. preview.yaml 파일 생성

보통 preview deployment 와 production deployment YAML 파일을 생성하는데, 우선 preview.yaml만 생성했다.

 

Vercel CLI은 프로젝트에서 yarn을 사용중이기 npm이 아닌 yarn으로 설치했고, actions/checkout은 최신버전이 릴리즈 되어서 actions/checkout@v4를 사용했다.

 

파일의 각 부분에 대한 설명은 주석으로 달아놓았다.

// workflow의 이름
name: Vercel Preview Deployment

// workflow에서 사용하는 모든 환경 변수
env:
  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}

// on: workflow가 자동으로 트리거되도록 하는 이벤트를 정의한다
on:
  push:
    branches-ignore:
      - main

// jobs: workflow에서 수행해야 하는 작업을 정의한다
jobs:
  Deploy-Preview:
    runs-on: ubuntu-latest
    
    // steps: 작업 내에서 수행되어야 하는 단계 또는 작업 목록이다.
    steps:
      // 저장소로 checkout 한다.
      - uses: actions/checkout@v4
      
      // 이후 yarn으로 Vercel CLI를 설치한다. (배포 시 필요하다)
      - name: Install Vercel CLI
        run: yarn global add vercel@latest
        
      // Vercel을 사용하여 프로젝트를 빌드하려면 먼저 GitHub Secrets에 저장된 토큰을 사용하여 Vercel에서 프리뷰 환경에 대한 구성을 가져와야 한다.   
      - name: Pull Vercel Environment Information
       	run: vercel pull --yes --environment=preview --token=${{ secrets.VERCEL_TOKEN }}
        
      // Vercel CLI를 사용하여 프로젝트를 빌드하는 vercel build를 실행한다. 
      // 또한 인증을 위해 토큰을 전달한다.
      - name: Build Project Artifacts
        run: vercel build --token=${{ secrets.VERCEL_TOKEN }}
        
      // 빌드된 프로젝트를 Vercel에 배포한다.
      - name: Deploy Project Artifacts to Vercel
       	run: vercel deploy --prebuilt --token=${{ secrets.VERCEL_TOKEN }}

 

 

 

4. 커밋 후 푸시

이후 변경 사항을 Github에 커밋하고 푸시하면 아래와 같이 배포가 실패한 것을 볼 수 있다.

이유는 위 workflow에서 필요한 변수를 아직 설정하지 않았기 때문이다. 이제 변수를 설정해보자.

 

 

 

5. 변수 설정하기

변수를 설정하려면 먼저 Vercel 계정을 만든 뒤, Account Settings > Tokens 로 이동해서 새로운 토큰을 생성해야 한다.

 

 

 

6. VERCEL_TOKEN 생성하기

토큰이 생성되었다면, 토큰을 복사 한 뒤 Github의 Settings으로 이동하자.

그리고 Secrets and variables > Actions로 이동하여 New repository secret 버튼을 클릭하고, VERCEL_TOKEN을 이름으로 지정한 뒤 토큰을 복붙하자.

 

 

다음으로는 Vercel 프로젝트를 생성할 차례이다. (얼마 안 남았다!)

7. Vercel CLI 설치

yarn global add vercel

 

 

8. Vercel 계정에 로그인

vercel login

 

 

9. Vercel 프로젝트 생성

vercel link

 

 

10. 이후 몇 가지 질문이 뜨는데 프로젝트에 맞게 답해주면 된다.

출처: https://ncodedsolutions.com/en/articles/automate-your-deployments-using-ci-cd-pipeline-with-vercel-and-git-hub-actions

 

vercel link의 결과물은 .vercel 의 하위 폴더이다.

.vercel 폴더의 하위 파일 중 하나인 project.json를 눌러보면 projectId와 orgId가 적혀있는 것을 볼 수 있다.

 

 

11. VERCEL_PROJECT_ID, VERCEL_ORG_ID 토큰 생성

위의 두 값(projectId와 orgId)을 복사한 뒤 아까 VERCEL_TOKEN이라는 토큰을 만든 것 처럼 VERCEL_PROJECT_ID, VERCEL_ORG_ID 토큰을 생성해주자.

 

 

12. 끝이다. 이제 테스트가 가능하다!

 

 

 

배포 테스트

---

1. 첫번째 에러

Error: Process completed with exit code 1.

 

위의 단계를 거쳐 커밋 후 푸시를 했는데, 배포가 계속 실패했다.

아무리봐도 어디가 잘못된지 모르겠는데.. 하던 찰나..

 

VERSEL...TOKEN? C가 아니라 S..?

 

오타 때문이라니.... 허무해🥹...

 

눈물을 머금고 VERCEL_TOKEN으로 고쳤다. 그리고 테스트를 해보니 이번엔 배포가 성공적으로 되었다!

 

 

 

Vercel Preview 배포 URL을 GitHub Pull Request에 자동으로 코멘트하기

---

다음으로는, 변경사항을 실시간으로 확인하고 싶어서 커밋 후 푸시 할 때 마다 해당 URL이 GitHub Pull Request에 자동으로 코멘트되도록 하고 싶었다. 아래처럼!

 

 

그러려면 먼저 배포 결과물에서 Preview URL을 추출해야한다. 이 부분은 Github 공식문서와 AI(Claude)의 도움을 받아 다음과 같이 구현했다.

- name: Deploy Project Artifacts to Vercel
  id: deploy
  run: echo "preview_url=$(vercel deploy --prebuilt --token=${{ secrets.VERCEL_TOKEN }})" >> $GITHUB_OUTPUT

 

 

 

코드의 각 부분을 자세히 살펴보자.

1. 고유 ID 부여

id: deploy

이 ID는 다음 단계에서 이 배포 단계의 출력을 참조할 때 사용된다. 따라서 고유 ID 값을 지정하지 않으면 다른 단계에서 이 단계의 결과를 참조할 수 없기 때문에 고유 ID를 부여해야 한다.

 

2. 출력 매개변수 설정

run: echo "PREVIEW_URL=$(vercel deploy --prebuilt --token=${{ secrets.VERCEL_TOKEN }})" >> $GITHUB_OUTPUT

 

여기서는 리눅스 명령어가 사용된다. 사용된 명령어는 아래와 같다.

echo: 주어진 텍스트를 화면에 출력하는 데 사용한다.
>>: 명령어 뒤에 나오는 파일에 추가할 때 사용한다.

 

이 명령은 아래와 같은 작업을 수행한다.

1. Vercel CLI를 사용하여 프로젝트를 배포한다.
2. 배포 결과로 반환된 URL을 'PREVIEW_URL'이라는 변수에 할당한다.
3. 이 변수를 GitHub Actions의 환경 파일인 $GITHUB_OUTPUT에 추가한다

참고로 $GITHUB_OUTPUT에 추가된 값은 이후 워크플로우의 다른 단계에서 참조할 수 있는 출력 변수가 된다.

 

그런데 궁금한 점은, Github Actions에서 왜 리눅스 명령어를 사용할까?

 

찾아보니 workflows 파일을 작성할 때 job의 실행환경을 지정하게 되는데, 대부분 우분투를 기본 실행 환경으로 선택한다.

jobs:
  Deploy-Preview:
    runs-on: ubuntu-latest
    ...

우분투는 리눅스의 배포판 중 하나인데, 결과적으로 Github Actions의 작업들은 리눅스 환경에서 실행되는 셈이다. 오호..CI/CD 파이프라인을 원하는대로 자유롭게 구축하려면 리눅스 명령어도 아는게 좋겠다..!

 

3. Pull Request에 Preview URL 코멘트하기

- name: Comment PR with Preview URL
  uses: thollander/actions-comment-pull-request@v2
  with:
    message: |
      🚀 Preview URL: ${{ steps.deploy.outputs.PREVIEW_URL }}

Preview URL을 추출한 후, Pull Request에 코멘트로 추가하기 위해 thollander/actions-comment-pull-request@v2 액션을 사용했다. 이 단계에서는 ${{ steps.deploy.outputs.preview_url }}를 통해 이전 단계에서 설정한 PREVIEW_URL 값을 참조한다.

 

이후 push를 해보니 Preview URL이 제대로 뜨는 것을 확인했다!

 

 

2. 두 번째 에러

하지만 Error: No issue/pull request in input neither in current context. 에러가 떴다.

 

음..필요한 Pull Request 컨텍스트가 없다는 의미가 뭘까 생각하다, on에 설정된 이벤트가 문제일 수 있다는 생각이 들었다.

 

이유는 처음에 공식문서에서 preview.yaml을 가져왔을 때, jobs 부분은 Preview URL을 설정하기 위해 각각 어떤 의미인지, 어떤 흐름인지 제대로 이해했는데 on에 해당하는 내용은 주의깊게 확인하지 않았기 때문이다.

 

그래서 확인하지 않은 부분에서 일어나는 문제라고 생각했다.

 

공식문서를 확인해보니 예상대로 관련 내용이 있었다!

The patterns defined in branches are evaluated against the Git ref's name. For example, the following workflow would run whenever there is a pull_request event for a pull request targeting

- Github Actions docs

 

 

결론적으로는 Pull Request에 대한 이벤트(코드 push)가 있을 때 마다 workflow가 실행되게 하려면 코드를 아래와 같이 작성해야 한다.

 

이렇게 작성해야 현재의 context를 Github Actions가 알 수 있다.

on:
  pull_request:
    branches: ['main']

 

 

기존에 작성했던 코드는(공식문서에 기재된 코드는) 아래와 같은데, 이 코드는 해당 Pull Request에 대한 context를 읽지 못하기 때문에 push를 해도 에러가 발생했던 것으로 생각된다.

on:
  push:
    branches-ignore:
      - main

 

이 경험으로 설정 파일의 각 부분이 어떤 식으로 동작하는지 제대로 확인하는 게 중요하다고 느꼈다.

 

또 공식문서를 확인하면서 다양한 설정을 할 수 있다는 것을 알게됐다. 나중에 추가적인 설정이 필요할 때 헤매는 시간을 단축할 수 있지 않을까?

 

아무튼.. 시간이 걸리더라도 꼼꼼하게 보자!

 

 

3. 세 번째 에러

하지만 또 다른 에러가 발생했다.

이번에 발생한 에러는 Error: Resource not accessible by integration 이다.

 

이 에러는 구글링 해보니 원인을 금방 알 수 있었다.

 

 

정확히는 권한을 설정해주기만 하면 되는 문제인데, 나는 button이 disabled 처리되어 있었다. 왜일까?

 

개발자들이 위 에러에 대해 의견을 공유하는 내용 중에서 답을 찾을 수 있었다.

(해당 내용은 링크를 클릭하면 확인할 수 있다.)

 

우선 Read and write permissions 버튼이 disabled 되어 있는 이유는 프로젝트를 Organizations 또는 Enterprise로 등록할 경우, 구성원이 선택할 수 있는 Github Actions 옵션을 제한적으로 두기 때문이다.

 

이 권한은 Organizations나 Enterprise 설정에서 전체적인 권한을 변경할 수 있다고 한다.

 

그런데 위 링크에서 어떤 분이 쓴 코멘트 중에 각 workflows 파일 내에서 permissions 키를 사용해서 필요한 권한만 최소한으로 설정하는 것이 베스트라고 한 것을 보았다.

(찾아보니 공식 문서에서도 GITHUB_TOKENS의 permissions를 개별 workflows 마다 설정할 수 있다고 나와있다.)

 

따라서 전체적으로 permissions을 허용하는 것 보다 개별적으로 허용하는 방법이 보안적으로 더 안전할 것이라 생각해서 workflows 내에 아래와 같이 최소한의 permissions 만 추가하는 방식을 선택했다.  (부여할 수 있는 permissions 목록은 링크에서 확인 할 수 있다.)

permissions:
  pull-requests: write
  contents: read

 

 

permissions까지 설정한 뒤의 결과는..

 

.

.

.

 

 

호우!!!11!! 배포 성공!😎

 

CI/CD 파이프라인 구축하기 전까지는 이렇게 오래걸릴 줄 몰랐는데.. 그래도 공부하고 나니 여러가지를 알게 되어서 기분이 좋다.

 

특히 배포 실패할 때 똑같은 에러를 계속 뱉는 경우는 짜증나기도 했는데, 새로운 에러를 뱉을 때는 이전 에러가 해결됐다는 거니까 한 발짝 앞으로 나아가는 느낌이 들어서 성취감이 느껴졌다.

 

에러 발생할 때 마다 해결하는 과정에서 정말 많은 것을 배운다.

 

+) 찾아보니 Vercel CLI를 쓰지 않고도 Preview URL 를 보여주는 액션도 있다. CLI 사용하는게 번거롭고 귀찮다 싶다면 추천한다! 👍

 

 

 

 

---

 

 

참고

 

https://nextjs.org/docs/pages/building-your-application/deploying

https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#setting-an-output-parameter

https://docs.github.com/ko/actions/writing-workflows/workflow-syntax-for-github-actions#example-including-branches

https://www.inflearn.com/community/questions/16184/yaml%ED%8C%8C%EC%9D%BC-%EC%9D%B4%EB%9E%80-%EB%AC%B4%EC%97%87%EC%9D%B8%EA%B0%80%EC%9A%94

https://ncodedsolutions.com/en/articles/automate-your-deployments-using-ci-cd-pipeline-with-vercel-and-git-hub-actions