Cloudtype with Github Actions

Published in

cloudtype

13 min readJan 13, 2023

CI/CD 개요

우리가 사용하고 있는 서비스는 눈에 보이지 않는 업데이트가 매일 일어나고 있습니다. 새로운 기능이 추가되거나 버그를 수정하는 등의 작업이 반영되는 것인데요. 과거와 달리 이러한 업데이트의 주기는 굉장히 빨라졌습니다. 이렇게 짧은 주기로 업데이트를 진행할 수 있게된 것은 CI/CD의 자동화 파이프라인과 그 맥을 같이 하고 있습니다.

먼저 CI와 CD의 각 개념을 먼저 살펴보겠습니다. CI는 지속적 통합을 뜻하는 Continuous Integration의 약자로서, 구성원이 작업한 소스의 변경 사항이 프로젝트에 반영된 후 설계와 시나리오에 맞게 작동하는지를 확인하는 과정을 가리킵니다. 이때 소스의 변경사항은 공통의 저장소에 반영 및 병합되어 조직 구성원들의 작업 사항이 공유되어야 합니다. 특정 브랜치에서 발생한 액션을 감지하여 테스트를 진행하거나 어플리케이션을 빌드하는 등 후속 작업을 진행하는 것 역시 CI 과정에 포함되죠. 만약 여러 구성원의 소스를 수동으로 병합하게 된다면 발생하는 충돌 및 이슈에 대처하기 위해서 적지 않은 비용이 들어갈 것입니다.

CD는 지속적 전달(Continuous Delivery)과 지속적 배포(Continuous Deployment)를 가리키는 용어로 후자가 전자의 의미를 포함하는 개념으로 사용됩니다. 지속적 전달은 자동화 파이프라인 내에서 CI 과정을 거친 코드가 저장소에 업로드되는 것을 의미하며, 신속하게 새로운 기능 혹은 핫픽스를 배포하기 위한 중요한 절차 중 하나입니다. 지속적 배포는 검증이 완료된 버전의 어플리케이션을 자동으로 배포하는 것을 가리킵니다. 자동화된 소스 병합 및 테스트, 저장소 반영 등의 과정을 거쳐 이전에 비해 훨씬 빠른 주기로 사용자들이 개선된 버전의 어플리케이션을 사용할 수 있게 되었으며, 그에 따라 안정적인 CI/CD 파이프라인을 구축하는 툴도 크게 발전하게 되었습니다.

대표적인 CI/CD 툴로는 Jenkins, Github Actions, TravisCI, CircleCI, GitLab 등이 있으며 속한 조직의 가용 리소스에 따라 취사선택하여 사용합니다. 별도의 호스팅 없이 웹 상에서 손쉽게 구축할 수 있는 툴도 다수 출시되었고 Kubernetes와 같이 컨테이너 기반의 인프라에서 사용할수 있는 ArgoCD 등도 널리 사용되고 있습니다.

Github Actions

Github Actions는 github의 저장소에 손쉽게 연동할 수 있는 CI/CD 서비스입니다. 사용하고 있는 저장소에 yml 형식의 파일을 작성하여 추가하는 것만으로도 어플리케이션 빌드 및 레지스트리 저장, 배포까지 모두 가능한 것은 물론, Github Marketplace에 공개된 다양한 라이브러리를 활용하여 github 외의 서비스까지 파이프라인을 확장시킬 수 있습니다.

Github Actions에서는 여러 작업 단위를 구성한 자동화 파이프라인을 workflow라고 부릅니다. 이 workflow를 구성하기 위해서는 github 저장소의 루트 디렉토리 위치에 .github/workflows 디렉토리를 생성한 후 그 내부에 yaml 파일을 작성해주면 됩니다. yaml 파일 내부에는 세부작업 단위인 job이 작성되고 job 하위에 설정된 step이 순차적으로 수행됩니다.

💡 클라우드타입은 Github Actions과 연동하여 소스에 수정사항이 반영되었을 때 이를 바로 클라우드타입에 배포할 수 있는 Github 라이브러리를 공개하였으며, 손쉽게 CI/CD 파이프라인을 구축할 수 있도록 지원하고 있습니다.

Workflow 구조

클라우드타입과 Github Actions를 연동하기 위한 yaml 파일 예제입니다. 각 부분의 역할과 옵션에 대해 살펴보겠습니다.

name: Deploy to cloudtype
on:
  push:
    branches:
      - main
      - dev
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Source
        uses: actions/checkout@v2
      - name: Connect
        uses: cloudtype-github-actions/connect@v1
        with:
          token: ${{ secrets.CLOUDTYPE_TOKEN }}
          ghtoken: ${{ secrets.GHP_TOKEN }}
          scope: cloudtype-ex
      - name: Deploy
        uses: cloudtype-github-actions/deploy@v1
        with:
          token: ${{ secrets.CLOUDTYPE_TOKEN }}
          project: cloudtype-ex/react-abc
          yaml: |-
            name: vite-react
            app: web
            options:
              nodeversion: "16"
              docbase: /dist
            context:
              git:
                ref: ${{ github.ref }}
                url: git@github.com:${{ github.repository }}.git

1) name

name: Deploy to cloudtype
...

name 은 workflow의 이름을 정의하는 부분이며 저장소의 Actions 메뉴에서 확인할 수 있습니다.

2) on

...
on:
  push:
    branches: # main, dev 브랜치의 push 이벤트에 대해 workflow 실행
      - main
      - dev
...

on 은 개발자가 어떤 브랜치에 어떤 이벤트를 발생시켰을때 job을 수행할 지 정의하는 곳입니다. branches 의 하위에는 이벤트를 탐지할 브랜치를 작성하며, 여러 개의 브랜치를 적용하는 경우 예시와 같이 하단에 추가로 작성하면 됩니다. 만약 특정 브랜치에 대해 workflow가 자동으로 실행되지 않도록 하려면 branches-ignore 옵션을 사용하면 됩니다. push 는 branches 에 정의된 브랜치에 push 가 되었을때 job을 수행하도록 하는 옵션이며 경우에 따라 pull_request 를 정의할 수 있습니다.

3) jobs

...
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Source
        uses: actions/checkout@v2
      - name: Connect
        uses: cloudtype-github-actions/connect@v1
        with:
          token: ${{ secrets.CLOUDTYPE_TOKEN }}
          ghtoken: ${{ secrets.GHP_TOKEN }}
          scope: cloudtype-ex
      - name: Deploy
        uses: cloudtype-github-actions/deploy@v1
        with:
          token: ${{ secrets.CLOUDTYPE_TOKEN }}
          project: cloudtype-ex/react-abc
          yaml: |-
            name: vite-react
            app: web
            options:
              nodeversion: "14"
              docbase: /dist
            context:
              git:
                ref: ${{ github.ref }}
                url: git@github.com:${{ github.repository }}.git

jobs 는 Github Actions 서버에서 소스를 받아 이를 배포하는 과정이 job이라는 작업 단위로 구성되어 있는 곳입니다.

jobs 바로 하위의 작성된 deploy는 job을 나타내는 이름으로서 Actions 대시보드에서 확인할 수 있고 개발자가 환경에 맞게 자유롭게 설정할 수 있습니다.

runs-on 은 job이 실행되는 운영체제 환경을 지정하는 곳이며, 클라우드타입의 실행환경은 ubuntu-latest 로 세팅해주면 됩니다.

steps 는 job 내부에서 실행되는 세부 작업 단위이며 순차적으로 수행됩니다. name 에 작성된 Checkout Source 와 같은 이름 역시 job의 이름처럼 자유롭게 작성이 가능하며 대시보드에서 확인할 수 있습니다. uses 는 Github 에서 제공하는 라이브러리를 정의하는 부분인데, 클라우드타입에 소스를 배포하는 것 뿐만 아니라 특정 언어를 빌드하고 테스트하는 등 여러 작업을 손쉽게 추가할 수 있도록 해줍니다. steps 에 정의된 각 작업의 역할을 자세히 살펴보겠습니다.

1) 소스 체크아웃

...
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Source
        uses: actions/checkout@v2
...

CI/CD workflow가 실행되는 Github Actions 서버에서 현재 위치한 저장소의 소스를 내려받는 부분입니다. 이 때 actions/checkout@v2 라고 하는 라이브러리가 활용됩니다.

2) 클라우드타입 연결

...
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
...
      - name: Connect
        uses: cloudtype-github-actions/connect@v1
        with:
          token: ${{ secrets.CLOUDTYPE_TOKEN }}
          ghtoken: ${{ secrets.GHP_TOKEN }}
          scope: [스페이스명]
...

클라우드타입에 github 저장소를 연결하는 부분입니다. 클라우드타입에서 해당 저장소의 소스를 받아 컨테이너 이미지로 빌드하는 과정을 수행하기 때문에 접근에 필요한 토큰 발급이 필요합니다.

2)-1 클라우드타입 토큰 발급

2)-1-a 클라우드타입에 로그인 후 환경설정 버튼을 누릅니다.

2)-1-b 인증 메뉴로 접근합니다.

2)-1-c API 키 항목에서 새로운 API 키 생성 버튼을 누릅니다.

2)-1-d 생성된 API 키를 안전한 곳에 보관합니다. 창을 닫으면 다시 조회할 수 없으니 주의 부탁드립니다.

2)-2 Github Personal Access Token 발급

2)-2-a Github에 로그인 후 Settings 버튼을 클릭합니다.

2)-2-b 좌측 하단의 Developer settings 버튼을 클릭합니다.

2)-2-c Personal access tokens 하위의 Tokens(classic) 버튼을 클릭합니다.

2)-2-d Generate new token — Generate new token (classic) 을 클릭합니다.

2)-2-e 토큰의 이름과 만료기간을 적절히 작성한 후 토큰 사용 범위 중 repo, admin:public_key 를 체크하고 하단의 Generate Token 버튼을 누릅니다.

2)-2-f 표시한 부분의 토큰을 안전한 곳에 보관합니다.

2)-3 Github 저장소에 Secret 토큰 값 저장

2)-3-a Github 저장소의 Settings를 클릭합니다.

2)-3-b 좌측 탭 Secrets and variables 하위의 Actions 를 클릭합니다.

2)-3-c New repository secret을 클릭합니다.

2)-3-d 발급한 2개의 토큰을 Github Actions의 workflow 파일에서 로드하는 이름과 동일하게 하여 등록합니다.

          token: ${{ secrets.CLOUDTYPE_TOKEN }}
          ghtoken: ${{ secrets.GHP_TOKEN }}

2)-3-e 토큰이 잘 등록되었는지 확인합니다. 이 때 토큰값에 오타가 있거나 수정이 필요한 경우 기존에 등록된 토큰값은 조회할 수 없으며 새로운 값으로 덮어 쓰거나 삭제 후 재등록만 가능합니다.

3) 클라우드타입 배포

...
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
...
      - name: Deploy
        uses: cloudtype-github-actions/deploy@v1
        with:
          token: ${{ secrets.CLOUDTYPE_TOKEN }}
          project: [스페이스명]/[프로젝트명]
          yaml: |-
            name: [서비스명]
            app: web
            options:
              nodeversion: "14"
              docbase: /dist
            context:
              git:
                ref: ${{ github.ref }}
                url: git@github.com:${{ github.repository }}.git

Github 저장소의 소스를 클라우드타입에 배포 요청하는 부분입니다. project 에는 [스페이스명]/[프로젝트명] 을, yaml 하위의 name 에는 [서비스명] 을 입력해주세요.

app 과 options 는 각 언어별 버전이나 빌드/시작 명령어 등을 어플리케이션에 맞게 세팅할 수 있는 곳입니다.

4) workflow 실행결과

workflow를 실행한 결과는 이미지와 같이 저장소의 Actions 탭에서 확인할 수 있으며, X 표시가 발생한 것은 정상적으로 job이 수행되지 않은 것이기에 로그 확인 후 해당 step의 이슈를 해소해야 합니다. 정상적으로 workflow가 수행됐다면 해당 어플리케이션이 클라우드타입에서 잘 배포되었는지 확인합니다. 만약 배포된 서비스에 접근이 불가하거나 이슈가 발생한 경우 배포에 필요한 설정인 options 값이 잘못 작성되었을 가능성이 있어 검토가 필요합니다.

지금까지의 실습 내용은 다음의 영상 가이드를 통해 확인하실 수 있습니다. 감사합니다🙌