在 raspberrypi 上的 gitlab runner 安裝，註冊，Trouble shooting.md

簡介

Gitlab runner 是 gitlab CI 架構下的一部分。在專案內會用到是因為有些子專案是跑在 raspberrypi 上，需要編出 arm 架構的 image。（x86 部分已經有 Jenkins ） 有兩個作法可以實現 arm 上的 CI，

• 再架一個 Jenkins 在 arm 上 https://hub.docker.com/r/wouterds/rpi-jenkins/ 可以嘗試跑這個 image
• gitlab runner (https://docs.gitlab.com/runner/)

gitlab runner 是以單一專案的形式設定，而multi runner 可以支援在同一台機器上設定多個 runner 來服務各自的專案。gitlab server 上收到更新時，會依據條件去通知 runner，runner 收到通知之後依照開發者設定的流程去測試，發佈。

環境：

• Runner:9.2.0
• Machine: Raspberry Pi
• OS: GNU/Linux 8.0
• GitLab Server: 9.2.5 6f2e590

使用 gitlab runner 需要以下的設定：

• 安裝 gitlab runner
• 向 gitlab server 註冊 runner
• 設定 runner

安裝 gitlab runner (https://docs.gitlab.com/runner/install/index.html)

這裡選用 linux 版本安裝，沒有遇到什麼問題

向 gitlab server 註冊 runner（https://docs.gitlab.com/runner/register/index.html）

最後一步會問要使用什麼 Executors，這裡我選用 shell。

Executors 指的是在收到來自 gitlab 通知時，要用什麼樣的 Executor 執行後面設定的 .gitlab-ci.yml。如果要選用 docker 的話，記得要先設定好要執行環境的 image。

例如我們專案內會使用到 node 環境，測試之後希望打包成 docker image，那上述的 docker image 就要包含 node & docker 兩個套件。這樣的好處是之後換機器當成 CI 主機時，不需要多花時間去弄環境。當然這比起 shell 是複雜了一些，也要使用到 docker in docker，有安全上的考量。

這個步驟有另外遇到幾個問題，詳細內容列在最後的 Trouble shooting。

設定 runner

主要有兩個設定檔

• .gitlab-ci.yml
• /etc/gitlab-runner/config.toml （https://gitlab.com/gitlab-org/gitlab-ci-multi-runner/blob/master/docs/configuration/advanced-configuration.md）

.gitlab-ci.yml（https://docs.gitlab.com/ee/ci/yaml/）

在專案的根目錄底下新增 .gitlab-ci.yml，這個檔案描述收到 server 更新通知之後需要做的事情，對應到 jenkins 就是 project configure。

variables:
  GIT_SSL_NO_VERIFY: "1"
  GIT_SUBMODULE_STRATEGY: recursive
	
before_script:
  - npm install
  - npm install --only=dev  
  - git submodule sync --recursive
  - git submodule update --init --recursive

stages:
  - test
  - deploy

test:
  stage: test
  script:
    - bash test.sh
  only:
    - master
  tags:
    - runner-pi

deploy:
  stage: deploy
  script:  
    - docker build -t {your tag} .
    - docker push {your repo}
  only:
    - master
  tags:
    - runner-pi

GIT_SUBMODULE_STRATEGY: https://gitlab.com/gitlab-org/gitlab-ci-multi-runner/issues/2075 這個專案裡有 git submodule，要設定 GIT_SUBMODULE_STRATEGY，不然會遇到下面問題

Checking out ddd4a923 as develop...
Updating/initializing submodules recursively...
Synchronizing submodule url for {your submodule}
Cloning into {your submodule url}..
error: cannot run ssh: No such file or directory
fatal: unable to fork

如果 submodule 放在同個 gitlab 上，在專案內 .gitsubmodule 可以用相對路徑去指。這可以避免認證問題。 https://docs.gitlab.com/ce/ci/git_submodules.html

Trouble shooting

註冊的時候首先遇到憑證問題（x509）

這問題主要是 runner 這台機器不信任 gitlab server 用的憑證。
到 /etc/ssl/certs/ca-certificates.crt 加入 gitlab 的 ca.crt 就能解決

ERROR: Registering runner... forbidden (check registration token) runner={my token}

主要是我填錯 access token，誤用成 {your_gitlab_url}/profile/personal_access_tokens 
應該要填 {your_gitlab_url}/{your_project}/settings/ci_cd 頁面 CI/CD Pipelines > Runner token