GitHub Actions¶

建置並執行規格¶

為了持續測試我們的範例應用程式 -- 無論何時推送提交以及有人開啟 pull request，請加入這個最小的工作流程檔案

.github/workflows/ci.yml

on:
  push:
  pull_request:
    branches: [master]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Download source
        uses: actions/checkout@v2
      - name: Install Crystal
        uses: crystal-lang/install-crystal@v1
      - name: Run tests
        run: crystal spec

若要開始使用 GitHub Actions，請將此 YAML 檔案提交至您 Git 儲存庫中的 .github/workflows/ 目錄下，將其推送至 GitHub，並觀察 Actions 索引標籤。

快速入門

查看 install-crystal 動作的 Configurator，以快速取得您需要的 CI 功能設定。或繼續閱讀以瞭解更多詳細資訊。

這會在 GitHub 的預設「最新 Ubuntu」容器上執行。它會從儲存庫本身下載原始碼（直接到目前目錄中），透過 Crystal 的官方 GitHub Action 安裝 Crystal，然後執行規格，假設它們位於 spec/ 目錄中。

如果任何步驟失敗，建置將顯示為失敗，通知作者，並且如果是推送，則將專案的整體建置狀態設定為失敗。

提示

為了更健康的程式碼庫，請考慮對 crystal spec 使用這些旗標
--order=random --error-on-warnings

沒有規格？¶

如果您的測試覆蓋率不太好，請考慮至少新增一個範例程式，並將其建置為 CI 的一部分

對於函式庫

          - name: Build example
            run: crystal build examples/hello.cr

對於應用程式（即使您有規格，也強烈建議這麼做）

          - name: Build
            run: crystal build src/game_of_life.cr

使用不同 Crystal 版本進行測試¶

預設情況下，會安裝最新發布的 Crystal 版本。但您可能還想使用 Crystal 的「nightly」版本進行測試，以及一些您仍然支援專案的舊版本。請如下變更工作流程的頂部

jobs:
  build:
    strategy:
      fail-fast: false
      matrix:
        crystal: [0.35.1, latest, nightly]
    runs-on: ubuntu-latest
    steps:
      - name: Download source
        uses: actions/checkout@v2
      - name: Install Crystal
        uses: crystal-lang/install-crystal@v1
        with:
          crystal: ${{ matrix.crystal }}
      - ...

所有這些版本將會同時測試。

透過指定 Crystal 的版本，您甚至可以選擇不支援最新版本（這確實是一個變動的目標），而只支援特定的版本。

在多個作業系統上測試¶

通常，開發人員只在 Ubuntu 上執行測試，如果沒有平台相關的程式碼，這還可以。但很容易將另一個系統加入測試矩陣中，只需在您的作業定義頂部附近新增以下內容

jobs:
  build:
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - ...

安裝 Shards 套件¶

大多數專案都會有外部相依性，「shards」。在 shard.yml 中宣告它們之後，只需將安裝步驟新增至您的工作流程中（在 install-crystal 之後，任何測試之前）

      - name: Install shards
        run: shards install

最新或鎖定的相依性？¶

如果您的儲存庫中有一個已簽入的 shard.lock 檔案（通常對於應用程式來說是好的），請考慮這對 CI 的影響：shards install 將永遠安裝該檔案中指定的確切版本。但如果您正在開發函式庫，您可能希望成為第一個發現是否有新版本的相依性破壞您的函式庫安裝的人 -- 否則使用者將會如此，因為鎖定不會以遞移方式套用。因此，強烈建議執行 shards update 而不是 shards install，或者不要簽入 shard.lock。然後新增排程執行到您的儲存庫中是有意義的。

安裝二進位相依性¶

我們的應用程式或某些 shards 可能需要外部函式庫。安裝它們的方法可能差異很大。典型的方式是使用 Ubuntu 中的 apt 命令安裝套件。

在開頭附近的某處新增安裝步驟。例如，使用 libsqlite3

      - name: Install packages
        run: sudo apt-get -qy install libsqlite3-dev

強制程式碼格式化¶

如果您想要驗證您的所有程式碼都已使用 crystal tool format 格式化，請在工作流程結尾附近新增相應的檢查步驟。如果有人推送格式不正確的程式碼，這會像測試失敗一樣中斷建置。

      - name: Check formatting
        run: crystal tool format --check

也考慮將此檢查新增為您自己的 Git pre-commit hook。

使用官方 Docker 映像檔¶

我們一直使用一個「action」將 Crystal 安裝到 GitHub 提供的預設作業系統映像檔中。這有多個優點。但您也可以選擇使用 Crystal 的官方 Docker 映像檔，儘管這僅適用於 Linux。

基本設定會變成這樣：

.github/workflows/ci.yml

jobs:
  build:
    runs-on: ubuntu-latest
    container:
      image: crystallang/crystal:latest
    steps:
      - name: Download source
        uses: actions/checkout@v2

      - name: Run tests
        run: crystal spec

其他容器的選項包括 crystallang/crystal:nightly、crystallang/crystal:0.36.1、crystallang/crystal:latest-alpine。

快取¶

每次執行時，下載和安裝相依性（特別是 shards）的過程都是從頭開始的。藉由 GitHub Actions 中的快取，我們可以節省一些重複的工作。

安全的方法是新增 actions/cache 步驟（在使用了 shards 的步驟之前），定義如下：

      - name: Cache shards
        uses: actions/cache@v2
        with:
          path: ~/.cache/shards
          key: ${{ runner.os }}-shards-${{ hashFiles('shard.yml') }}
          restore-keys: ${{ runner.os }}-shards-
      - name: Install shards
        run: shards update

重要

您必須使用分開的 key 和 restore-keys。如果僅使用靜態的 key，快取只會儲存第一次執行後的狀態，然後永遠重複使用它，無論是否有任何變更。

但這只為我們節省了最初下載儲存庫所花費的時間。

一個比較「大膽」的方法是快取 lib 目錄本身，但這只有在您完全依賴 shard.lock 的情況下才有效（請參閱最新或鎖定的相依性？）

      - name: Cache shards
        uses: actions/cache@v2
        with:
          path: lib
          key: ${{ runner.os }}-shards-${{ hashFiles('**/shard.lock') }}
      - name: Install shards
        run: shards check || shards install

請注意，我們也讓安裝的條件取決於 shards check。這可以再節省一點時間。

發佈可執行檔¶

如果您的專案是一個應用程式，您可能希望將其以可執行（「二進位」）檔案的形式發佈。對於 Linux x86_64 的情況，目前最受歡迎的選擇是在 Alpine Linux 上建立並靜態連結。這表示您無法使用 GitHub 的預設 Ubuntu 容器和安裝 action。請改為使用官方容器：

.github/workflows/release.yml

jobs:
  release_linux:
    runs-on: ubuntu-latest
    container:
      image: crystallang/crystal:latest-alpine
    steps:
      - uses: actions/checkout@v2
      - run: shards build --production --release --static --no-debug

這些步驟之後會有一些 action 來發佈產生的可執行檔 (bin/*)，透過以下兩種方式之一（或兩者都）：

作為發佈的一部分：請參閱完整範例。
然後在您的 README 中，您可以使用類似 https://github.com/:username/:reponame/releases/latest 的 URL 連結到最新版本。
作為每次 commit 的 CI 的一部分，透過 actions/upload-artifact。
然後考慮使用外部服務 https://nightly.link/ 連結到最新的「每夜」建置版本。

也可以發佈 macOS 的可執行檔（搜尋範例）和 Windows 的可執行檔（搜尋範例）。