Github Workflow on Jenny blog

如何設計與實作 Monorepo 的 Github Workflow?

Thu, 12 Jan 2023 14:56:21 +0800

如何設計與實作 Monorepo 的 Github Workflow?

前言

有鑑於越來越多人使用 monorepo，想研究一下，當只有針對某個 project 有程式碼的異動時，如何實踐 CI/CD

什麼是 monorepo?

顧名思義，mono 表示一個，repo 表示 repository，也就是一個 repository 包含多個 projects，並且清楚定義它們之間的關係
例如前後端開發，將前後端的程式都放在同一個 repository，就是 monorepo
結構大致上會呈現如下圖，這次舉例有兩個 app 在同一個 repository 中
想知道必用的原因、好處或採坑紀錄，可先參考 👇
- what-is-a-monorepo
- monorepo 之我見

如何設計 Github workflow?

參考Creating separate monorepo CI/CD pipelines with GitHub Actions，
以 project 來區分 workflows 檔案，有 db.yaml、gateway.yaml 以及worker.yaml，如下圖
- 當 gateway application 有程式碼異動，只能執行 gateway.yaml，測試或 build gateway image 等

實作

Github Workflow YAML 檔案中是以 on 定義，哪些 events 可以去 trigger 一個 workflow，因此我們需要在這邊動一些手腳，讓他只有在異動特定 application 時才會執行 workflow
利用 workflow syntax paths 指定範圍，當 pet app 底下的檔案有異動，執行這個 workflow
```
  paths:
    - 'apps/pet/**'
```
如果想要再加入指定環境呢?比如指定 stage 或 main，可以利用 branches 的 workflow syntax
```
  branches: ['stage']
```
結合以上，整個看起來應該會像這樣，指定在 stage 的 pet app 有程式碼變化時，執行這個 workflow
```
  on:
      push:
          branches: ['stage']
          paths:
              - 'apps/pet/**'
```

那如果是用 pull request 呢?

  on:
      push:
          branches: ['stage']
          paths:
              - 'apps/pet/**'
      pull_request:
          branches: ['stage']

我如何設計?

根據兩種環境 stage 與 main，以及兩種 app，總共會有 4 組 workflow yaml 檔案
- stage-app1.yml
- stage-app2.yml
- main-app1.yml
- main-app1.yml

注意事項

❗ “You must store workflow files in the .github/workflows directory of your repository.”
- Github Workflow 只支援第一層的 workflow yaml 檔案
- 也就是，以下圖的結構來放 workflow 檔案，Github 是不會執行的任何 workflow 的
- 官方文件說明

心得

經過這次，除了了解 monorepo 外，對於 Github Actions 的 Workflow syntax 更多的認識。

參考資料 👐

🍀 最後，若喜歡我的分享，可以免費幫我按讚，是對我最大的鼓勵! ✨ ✨ ✨

如何使用 Github Workflow 完成 CI/CD

Sat, 10 Dec 2022 18:33:05 +0800

Github Workflow 介紹

前言

為了利用 Github Workflow 完成 CI/CD，分成幾個部分來寫，分別是

Github Workflow 的基本設定
Github Workflow 中進行 CI
登入登出 AWS ECR 與 github container registry
build & upload image
更新 helm value 中的 image tag，後續讓 argocd 得以偵測到 helm values 的變化後，進行自動化部屬

基本設定

action 為 push 的時候，所有 branch 都會進行 github workflow
action 為 pull_request 的時候，只有 main branch 會進行 github workflow
types
paths

on:
  push:
    branches: ["*"]
  pull_request:
    branches: ["main"]
    types:
      - opened
    paths:
      - "**.js"

env 設定

設定方式如下，可以依照自身需求進行設定

env:
  AWS_DEFAULT_REGION: ap-southeast-1
  GIT_USER_NAME: jennyc

permissions 設定

設定方式如下，可以依照自身需求進行設定

permissions:
  id-token: write # This is required for requesting the JWT
  contents: read # This is required for actions/checkout

自動化測試 CI

checkout repository

使用 actions/checkout@v3 進行

- name: Checkout repository
  uses: actions/checkout@v3

執行 npm install

- name: Install dependencies
  run: npm install

執行 npm test

- name: Run tests
  run: npm run test

Build multi-platform images 並上傳至 AWS ECR

前言

這部分需要先設定 AWS Credential 才能使用 AWS ECR，
接著 build multi-platform image 並且上傳至 AWS ECR。

1. 設定 AWS Credential

設定 AWS Credential
- 使用 GitHub’s OIDC provider 方式取得 short-lived credentials
  - OpenID Connect (OIDC) 設定方式可以參考官方文件
  - 也可以參考這篇文章
- workflow 要怎麼寫?
  - env.AWS_DEFAULT_REGION 需要特別設定，與 AWS ECR 相同的 region
  - role-to-assume 填入 AWS role
  - role-session-name 預設是 GitHubActions，可以自行調整名稱
```
  - name: Configure AWS credentials
    uses: aws-actions/configure-aws-credentials@v1
    with:
        role-to-assume: arn:aws:iam::1234567890:role/example-role
        role-session-name: GitHubActionsWithAwsEcrUsingOIDCSession 
        aws-region: ${{env.AWS_DEFAULT_REGION}}
```

2. 登入 AWS private ECR

有兩種方式

Using access key id and secret access key to login

  - name: Configure AWS credentials
    uses: aws-actions/configure-aws-credentials@v1
    with:
      aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
      aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
      aws-region: ap-southeast-1

Using OpenID Connect (OIDC) to login

官方推薦使用此方式

  - name: Login to Amazon ECR
    id: login-ecr
    uses: aws-actions/amazon-ecr-login@v1

3. 登入 AWS public ECR

可參考官方說明

4. 登出 AWS ECR

- name: Logout of Amazon ECR
  if: always()
  run: docker logout ${{ steps.login-ecr.outputs.registry }}

5. 設定 short sha 為 image tag

設定以 7 digits 長度的 short sha 作為 image tag，原因可以參考:
- 7 digits are the Git default for a short SHA
- 附上其他參考文件 Chapter 7 of the Pro Git book
將 output 出去的參數命名為 sha_short

      - name: Set short sha outputs
        id: vars
        run: echo "sha_short=$(git rev-parse --short HEAD)" >> $GITHUB_OUTPUT

6. Build multi-platform images 並上傳 images 到 AWS ECR

建立多平台 docker images 的官方文件
IMAGE_TAG 會從步驟 5 取得 output 的變數 sha_short
--platform 可接上需要的 platform 參考，例如 linux/amd64, linux/arm64

  - name: Build, tag, and push docker image to Amazon ECR
    env:
        REGISTRY: ${{ steps.login-ecr.outputs.registry }}
        REPOSITORY: pet-app
        IMAGE_TAG: ${{ steps.vars.outputs.sha_short }}
    run: |
        docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
        ( 官方建議: docker run --privileged --rm tonistiigi/binfmt --install all )
        docker buildx create --name mybuilder --driver docker-container --bootstrap
        docker buildx use mybuilder
        docker buildx inspect
        docker buildx build --platform linux/amd64,linux/arm64 -t $REGISTRY/$REPOSITORY:$IMAGE_TAG --push .

為什麼需要 docker run --rm --privileged multiarch/qemu-user-static --reset -p yes ?
- 因為遇到 Error: while loading /usr/local/sbin/node: No such file or directory 問題
  - 先使用方式一 : 連接方式，結果還是有相同問題
```
  ln -s /usr/bin/node /usr/local/sbin/node
```
  - 後來使用方式二
    - 使用 docker buildx 指令前先執行以下命令
```
  docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
```
    - 詳細原因的 Stack Overflow 原始文章在這邊，以下是節錄部分
      
      ` When you ask the Linux kernel to run some executable file, it needs to know, how to load this specific file, and whether this file is compatible with current machine, or not. By default, the ELF binary compiled for, say, arm64v8 is rejected by the kernel, running on amd64 hardware.
      
      However, the binfmt_misc feature of the kernel allows you to tell it, how to handle the executables it cannot usually handle on its own - this includes the cases when the kernel does not know the binary format or considers it incompatible with current machine.
      `
    - github issue
官方建議使用以下命令解決 QEMU binaries 問題，官方文件
```
  docker run --privileged --rm tonistiigi/binfmt --install all
```

更新 helm value 的 image tag

前言

應用是以 terraform 方式部屬，並搭配使用 helm charts。而 docker image 的 tag 是寫在 helm values 內。
目標是更新 helm values 的 docker image tag 值，後續讓 argocd 得以偵測到 helm values 的變化後，進行自動化部屬。

需做到兩件事情:

checkout 私有 repository
設定與更新 image tag

1. 先 checkout 私有存放 helm value 的 repository

需要先設定 credential 才能 fetch private repository，有兩種設定的方式

設定 deploy key
- 步驟如下，可參考這篇
  1. Create a new SSH key pair for your repository. Do not set a passphrase.
  2. Copy the contents of the public key (.pub file) to a new repository deploy key and check the box to “Allow write access.”
  3. Add a secret to the repository containing the entire contents of the private key.
  4. As shown in the example below, configure actions/checkout to use the deploy key you have created.
- workflow 要怎麼寫?
  - ssh-key 填入 private key 的 secrets 名稱
  - path 設定 checkout 的 repo 會存在哪一個資料夾內
```
  - name: Checkout ${{env.TERRAFORM_REPOSITORY_NAME}} repo and push file to ${{env.TERRAFORM_REPOSITORY_NAME}}
    uses: actions/checkout@v3
    with:
      repository: ${{env.TERRAFORM_REPOSITORY_OWNER_NAME}}/${{env.TERRAFORM_REPOSITORY_NAME}}
      ssh-key: ${{ secrets.SSH_PRIVATE_KEY }}
      path: ${{env.TERRAFORM_REPOSITORY_NAME}}
```
設定 Personal access token (PAT)
- 建立 PAT 的方式，官方文件
- 將建立完成的 PAT 設定到 repository 的 secrets 中，設定的 secrets 名稱為 GH_PAT，官方文件
- workflow 要怎麼寫?
  - repository 設定為 owner/repository_name
  - token 填入 PAT 的 secrets 名稱，這邊是將 secrets 名稱為 GH_PAT 的內容設定為 PAT
```
- name: Checkout ${{env.TERRAFORM_REPOSITORY_NAME}} repo and push file to ${{env.TERRAFORM_REPOSITORY_NAME}}
    uses: actions/checkout@v3
    with:
        repository: ${{env.TERRAFORM_REPOSITORY_OWNER_NAME}}/${{env.TERRAFORM_REPOSITORY_NAME}}
        token: ${{ secrets.GH_PAT }}
```

2. 設定 image tag

設定以 7 digits 長度的 short sha 作為 image tag
- 7 digits are the Git default for a short SHA
- 附上其他參考文件 Chapter 7 of the Pro Git book

      - name: Set short sha outputs
        id: vars
        run: echo "sha_short=$(git rev-parse --short HEAD)" >> $GITHUB_OUTPUT

3. 更新 image tag

以 yq 的 github action 工具修改 yaml 檔內的 image tag 值
- yq 的官方文件
- yq 的 github
進行 git 操作，設定 user name, user email、commit 以及 push
tag 取上一個步驟 output 的參數 sha_short

      - name: Update image tag
        uses: mikefarah/yq@master
        with:
          cmd: yq -i '.pet_app_dashboard_site.image.tag = "${{ steps.vars.outputs.sha_short }}"' ./${{env.TERRAFORM_REPOSITORY_NAME}}/${{env.HELM_FILE_NAME}}
      - run: |
          cd ${{env.TERRAFORM_REPOSITORY_NAME}}
          git config user.name ${{env.GIT_USER_NAME}}
          git config user.email ${{env.GIT_USER_EMAIL}}
          git add ${{env.HELM_FILE_NAME}}
          git commit -m "update image tag to ${{ steps.vars.outputs.sha_short }}"
          git push origin main

若要將 docker image 上傳至 github container registry 該怎麼做?

1. 登入與登出 github container registry

需要設定 env.REGISTRY 為 ghcr.io

不需要另外設定 github.actor 與 GITHUB_TOKEN

    - name: Login to GitHub Container Registry
      uses: docker/login-action@v2
      with:
      registry: ${{ env.REGISTRY }}
      username: ${{ github.actor }}
      password: ${{ secrets.GITHUB_TOKEN }}

2. Extract metadata

      - name: Extract metadata (tags, labels) for Docker
        id: meta
        uses: docker/metadata-action@98669ae865ea3cffbcbaa878cf57c20bbf1c6c38
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}

3. Build and push docker image

labels 的值可以從步驟二取出 outputs labels 來使用

      - name: Build and push Docker image
        uses: docker/build-push-action@ad44023a93711e3deb337508980b4b5e9bcdc5dc
        with:
          context: .
          push: true
          tags: ${{ env.REGISTRY }}/${{ env.REPO }}:${{ steps.vars.outputs.sha_short }}
          labels: ${{ steps.meta.outputs.labels }}

參考資料

最後，若喜歡我的分享，可以免費幫我按讚，是對我最大的鼓勵!