GitHub Actions 和 .NET

在此概觀中,了解 GitHub Actions 在 .NET 應用程式開發中扮演的角色。 GitHub Actions 可讓您的原始程式碼存放庫自動化持續整合 (CI) 和持續傳遞 (CD)。 除此之外,GitHub Actions 會公開更進階的案例,提供程式碼檢閱、分支管理和問題分級自動化的勾點。 透過 GitHub 中的 .NET 原始程式碼,您可以透過許多方式運用 GitHub Actions。

GitHub 動作

GitHub Actions 代表獨立命令,例如:

  • actions/checkout - 此動作會在 $GITHUB_WORKSPACE 底下取出您的存放庫,因此您的工作流程可以存取。
  • actions/setup-dotnet - 此動作會設定用於動作的 .NET CLI 環境。
  • dotnet/versionsweeper - 此動作會清理不支援 .NET 目標版本的 .NET 存放庫。

雖然這些命令會與單一動作隔離,但透過工作流程組合而變得強大。 在工作流程組合中,您可以定義觸發工作流程的事件。 工作流程執行之後,系統會指示執行各種作業。 每個作業都會定義任意數目的步驟步驟會委派給 GitHub Actions,或呼叫命令列指令碼。

如需詳細資訊,請參閱 GitHub Actions 簡介。 將工作流程檔案視為代表各種應用程式建置、測試和/或發佈步驟的組合。 許多 .NET CLI 命令可供使用,大部分命令都可用於 GitHub Action 的內容中。

自訂 GitHub Actions

雖然 Marketplace 中有許多 GitHub Actions 可用,但您可能想要自行撰寫。 您可以建立執行 .NET 應用程式的 GitHub Actions。 如需詳細資訊,請參閱教學課程:使用 .NET 建立 GitHub Actions (部分機器翻譯)

工作流程檔案

GitHub Actions 是透過工作流程檔案使用。 工作流程檔案必須位於存放庫的 .github/workflows 目錄中,而且必須是 YAML (*.yml*.yaml)。 工作流程檔案會定義工作流程組合。 工作流程是由一個或多個作業所組成的可設定自動化流程。 如需詳細資訊,請參閱 GitHub Actions 的工作流程語法 (英文)。

範例工作流程檔案

有許多 .NET 工作流程檔案的範例會以教學課程快速入門的形式提供。 下列是一些良好的工作流程檔案名稱範例:

工作流程檔案名稱

說明

編譯 (或建置) 原始程式碼。 如果原始程式碼未編譯,這會失敗。

練習存放庫中的單元測試。 若要執行測試,必須先編譯原始程式碼,這實際上是建置和測試工作流程 (會取代 build-validation.yml 工作流程)。 失敗的單元測試會導致工作流程失敗。

封裝,並將原始程式碼發佈至目的地。

分析您的程式碼是否有安全性弱點和編碼錯誤。 任何探索到的弱點都可能造成失敗。

加密的袐密

若要在工作流程檔案中使用加密的祕密,您可以使用 secrets 內容物件的工作流程運算式語法來參考祕密。

${{ secrets.MY_SECRET_VALUE }} # The MY_SECRET_VALUE must exist in the repository as a secret

祕密值絕對不會列印在記錄檔中。 相反地,祕密名稱會以星號來列印,星號代表祕密值。 例如,每個步驟在作業內執行時,其使用的所有值都會輸出至動作記錄檔。 祕密值會轉譯如下:

MY_SECRET_VALUE: ***

重要

secrets 內容提供限定於存放庫、分支和動作的 GitHub 驗證權杖。 GitHub 會提供權杖,完全不需要任何使用者介入:

${{ secrets.GITHUB_TOKEN }}

如需詳細資訊,請參閱在工作流程中使用加密的祕密

事件

工作流程是由許多不同類型的事件所觸發。 除了最常見的 Webhook 事件之外,還有已排定事件和手動事件。

範例 Webhook 事件

下列範例示範如何指定工作流程的 Webhook 事件觸發程式:

name: code coverage

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main, staging

jobs:
  coverage:

    runs-on: ubuntu-latest

    # steps omitted for brevity

在上述工作流程中,pushpull_request 事件會觸發工作流程執行。

範例已排定事件

下列範例示範如何指定工作流程的已排定 (cron 作業) 事件觸發程式:

name: scan
on:
  schedule:
  - cron: '0 0 1 * *'
  # additional events omitted for brevity

jobs:
  build:
    runs-on: ubuntu-latest

    # steps omitted for brevity

在上述工作流程中,schedule 事件會指定 '0 0 1 * *'cron,這會觸發工作流程在每個月的第一天執行。 按照排程執行工作流程非常適合需要長時間執行的工作流程,或執行需要不太需要頻繁注意的動作。

範例手動事件

下列範例示範如何指定工作流程的手動事件觸發程式:

name: build
on:
  workflow_dispatch:
    inputs:
      reason:
        description: 'The reason for running the workflow'
        required: true
        default: 'Manual run'
  # additional events omitted for brevity

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: 'Print manual run reason'
        if: ${{ github.event_name == 'workflow_dispatch' }}
        run: |
          echo 'Reason: ${{ github.event.inputs.reason }}'

    # additional steps omitted for brevity

在上述工作流程中,workflow_dispatch 事件需要 reason 做為輸入。 GitHub 會以動態方式看到這一點及其 UI 變更,以提示使用者提供手動執行工作流程的原因。 steps 將列印使用者所提供的原因。

如需詳細資訊,請參閱觸發工作流程的事件

.NET CLI

.NET 命令列介面 (CLI) 是用於開發、建立、執行和發佈 .NET 應用程式的跨平台工具鏈。 在工作流程檔案中的個別 steps 中,.NET CLI 用來 run。 通用命令包括:

如需詳細資訊,請參閱 .NET CLI 概觀 (部分機器翻譯)

另請參閱

如需使用 .NET 的 GitHub Actions 有關的更深入探討,請參考下列資源: