這篇文章會分享設計上要注意的細節，以及實戰過程踩過的坑，不會特別說明基礎資訊，想更深入理解的朋友可以參考官網文件；如果讀者有更好的方案，或對名詞有更精準的定義，歡迎留言分享。

文章大綱

▋ GitLab CI 資料夾結構設計
▋ 在 .gitlab/.default.gitlab-ci.yml 定義要執行 pipeline 的 Branchs
▋ 根據專案需求定義對應的 Stages
▋ 想在不同 stage 傳遞資料時，artifacts 跟 cache 的使用時機
▋ 讓 stage 下的 job 並行執行 or 順序執行
▋ notify 階段建議要有的資訊
▋ Dockerfile 多階段構建
▋ 其他的坑（套件安裝、相容性、單元測試）

GitLab CI 資料夾結構設計

Project
├── .gitlab-ci.yml
└── .gitlab
    ├── stages
    │   ├── 1.xxx.yml
    │   └── 2.xxx.yml
    ├── .default.gitlab-ci.yml
    └── docker-bake.hcl

下面說明一下資料夾結構下各檔案要負責的任務：

• .gitlab-ci.yml: 定義有要執行的 stages，以及參考的 yml 檔案（ex: .gitlab/.default.gitlab-ci.yml）。
• .gitlab: 存放 GitLab 設定檔的資料夾。
• .gitlab/stages: 存放各 stage 的資料夾，讓邏輯更容易維護。
• .gitlab/stages/xxx.yml: 定義 stage 下各 jobs 要執行的任務。
• .gitlab/.default.gitlab-ci.yml: 用來定義默認的設定，避免重複性的工作（ex: 設定通用的 variables、定義要執行 pipeline 的 branchs）。
• .gitlab/docker-bake.hcl: 定義 Build Docker Image 的資訊（ex: 支援多平台、傳遞參數）。

在 .gitlab/.default.gitlab-ci.yml 定義要執行 pipeline 的 Branchs

僅管我們期待每次 Push 一版都會觸發 pipeline，但有時也會有一些例外狀況（ex: 需要高頻率 Push 測試一些特殊功能）。

以下面的設計來說，就是僅允許「merge_request_event」以及「release/、hotfix/、feature/*」，還有 Default Branch（ex: master、develop）會觸發 pipeline。

workflow:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH =~ /^release\/.*$/'
    - if: '$CI_COMMIT_BRANCH =~ /^hotfix\/.*$/'
    - if: '$CI_COMMIT_BRANCH =~ /^feature\/.*$/'
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'

根據專案需求定義對應的 Stages

筆者習慣設計下面 5 個 Stages:

• init: 在這個階段做套件安裝的任務（ex: npm install）。
• analysis: 如果 init 順利才會進入這個階段，會在這裡進行單元測試(test)、Coding Style 檢查(lint)，並將對應的 report 保存到 artifacts 當中。
• build_image: 如果前面都通過才會 Build Docker Image，並將 $TARGET_IMAGE:$TAG 保存到 artifacts/tags.txt 當中（要在 notify 階段使用）。
• notify: 我將它設定為 always 執行，用來傳送 pipeline 成功/失敗的訊息到對應的 Chanel（ex: Zoom、Teams、Line）。
• deploy: 根據實際需求設計部署流程。

想在不同 stage 傳遞資料時，artifacts 跟 cache 的使用時機

上個 stage 做完的事情，在下個 stage 是不會知道細節的。

想要傳遞資訊就需要透過 artifacts 或 cache，而這兩者的用途不太一樣：

• artifacts: 記錄這次 pipeline 獨有的資訊，像是 test report、image_id 這類的，建議要設定對應的 expire_in 時間，否則資料會永久保存消耗硬碟空間。

analysis:
  artifacts:
    paths:
      - reports
    expire_in: 1 day

• cache: 這個專案經常使用的資料，比如 node_modules 這類保存套件的資料夾。

analysis:
  cache:
    key: "${CI_PROJECT_PATH_SLUG}"
    paths:
      - node_modules

讓 stage 下的 job 並行執行 or 順序執行

如果沒有特別設計，stage 下的 job 默認都是並行執行的（比如 unit test & lint 可以同時進行）；如果想要順序執行，可以透過 needs 來設定，範例如下：

job1:
  stage: build
  script:
    - echo "Executing job1"
job2:
  stage: build
  script:
    - echo "Executing job2"
  needs:
    - job1  # 等待 job1 完成後執行

notify 階段建議要有的資訊

GitLab CI 通常要跑幾分鐘的時間（通常跟 unit test 多寡有關），所以要設計 notify 的機制來傳遞資訊，建議包含的內容如下：

• project: $PROJECT_NAME，方便了解執行的專案。
• branch: $CI_COMMIT_REF_NAME，了解哪個 branch 更新了。
• result: 會包含成功與失敗的詳細資訊。
• pipeline_link: $PIPELINE_LINK，出問題時點擊連結可以看到最直接的資訊。
• image_id: 從 artifacts 裡面讀取。

Dockerfile 多階段構建

下面用一個範例來說明如何用多階段構建（multi-stage build）來減少 Docker Image 大小並提高效率（COPY –from=builder 的作用是從第一階段複製文件到第二階段）。

# 第一階段：使用 Node.js 安裝套件，並進行打包
FROM node:23.3-alpine as builder
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm install
COPY . .
RUN npm run build

# 第二階段：使用 Nginx 部署靜態文件
FROM nginx:alpine3.20
COPY --from=builder /app/dist /usr/share/nginx/html
WORKDIR /usr/share/nginx/html
COPY ./build/nginx/default.conf /etc/nginx/conf.d/default.conf

透過這個方案，最終的 Image 只有靜態文件跟 Nginx，不包含 Node.js 開發工具；不但減少 Image 大小，還減少了潛在攻擊面向。

其他的坑（套件安裝、相容性、單元測試）

• 套件無法順利安裝: 如果套件是經由私有庫來安裝的，就需要設定對應的網路環境；如果在 Dockerfile 裡面安裝，請記得將 .npmrc 這類設定 COPY 到對應的位置。
• qemu-user-static 相容性錯誤: 有些專案需要指定對應的 platform 才能順利 build 出來（Dockerfile from 的 image 可能僅支持 arm 或 amd）。
• 單元測試錯誤突然暴增: 如果在 local 環境測試起來正常，但在 GitLab CI 時出現錯誤，那通常是「非同步」的問題，可以先用 await 拉長等待時間，並搭配 log 來釐清狀況。

有段時間沒發純技術的文章了，希望能幫助到有相關需求的朋友們，也歡迎大家分享自己在 GitLab CI 的使用經驗。

但這時會遇到一個問題：「每個人對專案的認知有差異，且文字表達能力不同。」

這會導致 Code Review 的人需要花更多的時間來理解程式，甚至浪費寶貴的時間在溝通上；有些交代不清楚的 Merge Request 如果被合併了，也容易在未來發現 Bug 時難以釐清問題。

而解決上面問題的方式也很簡單：「建立 Template（模板）」

如果大家都按照模板撰寫，就能保證每個 MR 都有一定的品質。

Merge Request 要有哪些資訊？

筆者個人建議一個好的 Merge Request 要包含以下元素：

1. 概要 & 背景：簡短描述這次 Merge Request 的目的，讓 Code Review 的人可以快速理解前因後果。
2. 相關資訊：放上專案需求規格連結、關聯的 Project/branch、會議紀錄等資訊。
3. 變更內容：說明新增/修改/移除了什麼內容，如果邏輯複雜可以簡述演算法。
4. 測試步驟：描述如何驗證這次的變更，包括需要運行的測試和預期結果。

大家可以參考我的 Merge Request Template 格式（Markdown 語法）：

# 概要 & 背景

# 相關資訊

- 需求規格: 
- 關聯的 Project/branch: 
- 任務 Ticket/會議紀錄: 

# 變更內容

- [新增] xxx
- [修改] yyy
- [移除] zzz

# 測試步驟

### 測試項目 1

- STEP 1: 
- STEP 2: 
- STEP 3: 

預期結果:

英文版：

# Summary & Background

# Relevant Information

- Requirement Specifications: 
- Associated Project/Branch: 
- Task Ticket/Meeting Notes: 

# Changes

- [Added] xxx
- [Modified] yyy
- [Removed] zzz

# Testing Steps

### Test Case 1

- STEP 1: 
- STEP 2: 
- STEP 3: 

Expected Result:

在 Gitlab 建立 Merge Request Templates 的步驟

STEP 1: 選擇 Project default branch，建立存放 Templates 的資料夾

我們要先在根目錄下建立 .gitlab/merge_request_templates/ 的資料夾。

小提醒：一定要在「default branch（ex: main、develop）」下建立，否則是沒有效的。

STEP 2: 在資料夾下建立「.md」的 Templates

你可以直接複製筆者在前面提供的 Markdown Template，這邊我將檔案命名為「merge.md」。

這邊我開一個測試的 branch 來做 Merge request，大家可以看到在 Description 旁邊有一個下拉選單，裡面的 merge 就是我們剛剛新增的模板。

選擇後就能看到剛剛建立的 Merge request Template：

相信一個好的 Merge request Template 能提高專案的品質，並加速團隊的協作流程，減少不必要的溝通成本。

軟體工程 Edit description dean-lin.medium.com

因為過去在使用的路上遇到各式各樣的問題，我把相關經驗整合在這裡，希望看到文章的朋友可以順利跨過這些難關，如果我的文章幫你解決問題歡迎多按幾次拍手。

此Gitlab安裝時的ubuntu版本為16.4，指令如有不同，請自行google，如果你願意，也非常歡迎回覆在下方分享您的經驗。

建議硬體需求

RAM至少4GB，以百人公司規模來說建議8GB以上大家使用上會順暢很多(如果你用官方建議2GB可能會連安裝都卡住，這部分有親自體驗過)

安裝前置作業

1. 因為git在連線時需要使用ssh連線進行安全性驗證 所以需要openssh-server ca-certificates
2. gitlab支援寄信通知或是驗證功能所以需要信箱伺服器支援需要postfix

curl openssh-server ca-certificates postfix
sudo apt-get install curl openssh-server ca-certificates postfix

安裝gitlab

1. gitlab下載目前運行版本指令

curl -s https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash
sudo apt-get install gitlab-ce=11.1.4-ce.0

2. 單純下載封包

wget — content-disposition https://packages.gitlab.com/gitlab/gitlab-ce/packages/ubuntu/trusty/gitlab-ce_11.1.4-ce.0_amd64.deb/download.deb

建議要備份下載的deb檔案到自己的硬碟，如果日後災難復原時會用上，像我是備份到公司的NAS Server上面

gitlab環境配置

sudo gitlab-ctl reconfigure

如果環境沒問題，上面這個指令會順順的過去；但如果做了版本升級或是降級，所有的環境都可能會產生或大或小的bug，官方並沒有提供一個很健全的解決方案，建議未來的使用者除非很有把握不然建議不要隨意升級。

筆者在之後新版的gitlab有更新成功，但是舊版直接升級會遇到許多問題整理部份如下

Gitlab 500 Error: PG::ConnectionBad:

https://gitlab.com/gitlab-org/omnibus-gitlab/issues/1637

/opt/gitlab/embedded/bin/bundle:23:in `<main>’

https://gitlab.com/gitlab-org/omnibus-gitlab/issues/3185

輸入以下指令可獲得版本資訊:

sudo gitlab-rake gitlab:env:info

設定對外網址

輸入下面指令後尋找external_url，將其修改成自己的url與開放的port

sudo vi /etc/gitlab/gitlab.rb

external_url 'https://domain.com'.  //你自己的url

registry_nginx['redirect_http_to_https'] = true   //是否自動轉址為https
mattermost_nginx['redirect_http_to_https'] = true
nginx['enable'] = true
nginx['redirect_http_to_https'] = true
nginx['redirect_http_to_https_port'] = 80
nginx['ssl_certificate'] = "/etc/your_path/ssl/gitlab.xxxxx.com.crt"   //如果你的gitlab為https請設定ssl的路徑
nginx['ssl_certificate_key'] = "/etc/your_path/ssl/gitlab.xxxxx.com.key"

原始碼：gitlab.rb（GitHub Gist）

每次修改過這個檔記得要重新配置才會生效

sudo gitlab-ctl reconfigure

(到這一部已經可以使用gitlab了，但是如果要寄信相關還要做如下設定)

寄信相關設定

sudo vi /etc/gitlab/gitlab.rb

把下面這些貼到最下面後sudo gitlab-ctl reconfigure就生效了

//下面的是email信箱設定(此為gmail範例)
gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "smtp.gmail.com"
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_user_name'] = "your@gmail.com"
gitlab_rails['smtp_password'] = "your_password"
gitlab_rails['smtp_domain'] = "smtp.gmail.com"
gitlab_rails['smtp_authentication'] = "login"
gitlab_rails['smtp_enable_starttls_auto'] = true
gitlab_rails['smtp_tls'] = false
gitlab_rails['smtp_openssl_verify_mode'] = 'peer' # Can be: 'none', 'peer', 'client_once', 'fail_if_no_peer_cert', see http://api.rubyonrails.org/classes/ActionMailer/Base.html
gitlab_rails['smtp_ca_path'] = "/etc/ssl/certs"
gitlab_rails['smtp_ca_file'] = "/etc/ssl/certs/ca-certificates.crt"

原始碼：gitlab_gmail.rb（GitHub Gist）

可下指令測試是否設定成功

sudo gitlab-rails console
Notify.test_email(‘email@example.com’, ‘test’, ‘test’).deliver_now

但是當gitlab的server有設定雙網卡（同時有內網以及外網）的時候就有可能出現email無法寄送的狀況，這個時候你要確定你外網的優先權必須要高於內網。

看mail錯誤log

vi /var/log/mail.log

改mail postfix設定

vi /etc/postfix/main.cf
postfix reload

ssh對外設定

如果你對外網址的22 port已經被其他專案佔用了（ex:我公司），所以要將預設ssh的22 port改為轉址的223 port(或是其他你希望的)，一樣是在sudo vi /etc/gitlab/gitlab.rb設定，這樣在gitlab才能用ssh下載

gitlab_rails[‘gitlab_shell_ssh_port’] = 223

nginx設定

nginx['enable'] = true
nginx['redirect_http_to_https'] = true
nginx['redirect_http_to_https_port'] = 80
nginx['ssl_certificate'] = "/etc/your_path/ssl/gitlab.xxxxx.com.crt"   //如果你的gitlab為https請設定ssl的路徑
nginx['ssl_certificate_key'] = "/etc/your_path/ssl/gitlab.xxxxx.com.key"

原始碼：gitlab_nginx.rb（GitHub Gist）

讓Gitlab可通內網外網

在gitlab分配兩張網卡後需要完成以下步驟

先看新增的網卡名稱

cd /proc/sys/net/ipv4/conf

確認完網卡後將他們編輯加入

sudo vi /etc/network/interfaces
auto ethXXX
iface ethXXX inet dhcp

改完後

sudo /etc/init.d/networking restart

用ifconfig查看是不是抓到

設定路由可以透過閘道連通

sudo /sbin/route add 10.1.1.1(目標內網ip) gw 10.1.1.254(內網閘道) dev ens192(網卡)

設定NAS上此共享資料夾必須符合NFS設定可參閱這篇文章

http://blog.xuite.net/tolarku/blog/495291815-Qnap+%E8%A8%AD%E5%AE%9A+NFS+%E5%88%86%E4%BA%AB%E8%A8%AD%E5%AE%9A+-+nfs+export

確認是否可連通，並觀看有哪些資料夾

sudo apt install nfs-common
showmount -e 10.1.1.1(目標內網ip)

將NAS上的共享資料夾掛載到ubuntu上面

sudo mount -t nfs 10.1.1.1(目標內網ip):ServerGit /home/your_path/gitlab_backup

確認是否掛載

df -h

gitlab定時自動備份到NAS的設定

在/etc/gitlab/gitlab.rb設定gitlab的備份路徑

gitlab_rails[‘backup_path’]=”/home/your_path/gitlab_backup/”

每個月1日創建本月的資料夾的script

now_month=”$(date +’%Y%m’)”
#echo “$now_month”
cd /home/your_path/gitlab_backup
mkdir $now_month

將產生的backup檔案轉移到月份資料夾底下的script,並刪除比較久的資料

mv /home/your_path/gitlab_backup/*.tar /home/your_path/gitlab_backup/$(date +’%Y%m’)
find /home/your_path/gitlab_backup/$(date +’%Y%m’) -name “*gitlab_backup.tar” -mtime +3 -exec rm -rf {} \;
find /home/your_path/gitlab_backup/$(date “+%Y%m” -d ‘1 month ago’) -name “*gitlab_backup.tar” -mtime +3 -exec rm -rf {} \;

排程設定

sudo crontab -e
1 0 1 * * sh /home/your_path/script/mkdir.sh
1 1 * * * /opt/gitlab/bin/gitlab-rake gitlab:backup:create
1 2 * * * sh /home/your_path/script/mv_to_month.sh

Gitlab 的學問博大精深，希望這篇文章讓初學者上手時更加輕鬆。