原文 https://devblogs.microsoft.com/dotnet/dotnet-loves-github-actions/
嗨朋友們，我整理了一些帖子，我將向您介紹GitHub Actions平臺的基礎知識。在這篇文章中，您將瞭解 GitHub Actions 如何改善您的 .NET 開發體驗和團隊生產力。我將向您展示如何使用它們通過工作流組合來自動化常見的 .NET 應用程序開發場景。
GitHub Actions 簡介
使用 GitHub 管理其 git 存儲庫的開發人員在 GitHub Actions 的幫助下擁有強大的持續集成 (CI) 和持續交付 (CD) 功能。一個常見的開發人員場景是開發人員建議對mainGitHub 存儲庫的默認分支（通常是 ）進行更改。這些更改雖然經常受到審閱者的審查，但可以進行自動檢查以確保代碼編譯和測試通過。
GitHub Actions 允許您直接從https://github.com上的源代碼存儲庫構建、測試和部署代碼。GitHub 操作由 GitHub 工作流使用。GitHub 工作流是 GitHub 存儲庫中的 YAML（.yml或.yaml）文件。這些工作流文件位於存儲庫根目錄下的.github/workflows/目錄中。工作流將一個或多個 GitHub 操作作爲一系列指令一起引用，其中每條指令執行特定任務。
GitHub Action 術語
爲了避免錯誤地錯誤地使用其中一些術語，讓我們定義它們：
- GitHub Actions：GitHub Actions是一個持續集成和持續交付 (CI/CD) 平臺，可讓您自動化構建、測試和部署管道。
- 工作流：工作流是一個可配置的自動化過程，將運行一個或多個作業。
- 事件：事件是存儲庫中觸發工作流運行的特定活動。
- 作業：作業是工作流中在同一運行器上執行的一組步驟。
- action：action是 GitHub Actions 平臺的自定義應用程序，它執行復雜但經常重複的任務。
- runner：runner是一個服務器，當它們被觸發時運行你的工作流。
GitHub 工作流文件內部
工作流文件定義了一個序列jobs及其對應steps的遵循。每個工作流都有一name組觸發器或要執行的事件on。您必須至少指定一個觸發器才能運行您的工作流，除非它是可重用的工作流。一個常見的 .NET GitHub 工作流程是在推送更改或有針對默認分支的拉取請求時構建和測試您的 C# 代碼。考慮以下工作流文件：
name: build and test
on:
push:
pull_request:
branches: [ main ]
paths-ignore:
- 'README.md'
env:
DOTNET_VERSION: '6.0.x'
jobs:
build-and-test:
name: build-and-test-${{matrix.os}}
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-latest, windows-latest, macOS-latest]
steps:
- uses: actions/checkout@v2
- name: Setup .NET
uses: actions/setup-dotnet@v1
with:
dotnet-version: ${{ env.DOTNET_VERSION }}
- name: Install dependencies
run: dotnet restore
- name: Build
run: dotnet build --configuration Release --no-restore
- name: Test
run: dotnet test --no-restore --verbosity normal
我不會假設您對這個工作流程有深入的瞭解，雖然它不到 30 行，但仍有很多東西需要解壓。我整理了一個序列圖（由Mermaid提供支持），它顯示了開發人員如何可視化這個工作流程。
這是相同的工作流文件，但這次它使用內聯註釋進行擴展以添加上下文（如果您已經熟悉工作流語法，請隨意跳過此內容）：
# The name of the workflow.
# This is the name that's displayed for status
# badges (commonly embedded in README.md files).
name: build and test
# Trigger this workflow on a push, or pull request to
# the main branch, when either C# or project files changed
on:
push:
pull_request:
branches: [ main ]
paths-ignore:
- 'README.md'
# Create an environment variable named DOTNET_VERSION
# and set it as "6.0.x"
env:
DOTNET_VERSION: '6.0.x' # The .NET SDK version to use
# Defines a single job named "build-and-test"
jobs:
build-and-test:
# When the workflow runs, this is the name that is logged
# This job will run three times, once for each "os" defined
name: build-and-test-${{matrix.os}}
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-latest, windows-latest, macOS-latest]
# Each job run contains these five steps
steps:
# 1) Check out the source code so that the workflow can access it.
- uses: actions/checkout@v2
# 2) Set up the .NET CLI environment for the workflow to use.
# The .NET version is specified by the environment variable.
- name: Setup .NET
uses: actions/setup-dotnet@v1
with:
dotnet-version: ${{ env.DOTNET_VERSION }}
# 3) Restore the dependencies and tools of a project or solution.
- name: Install dependencies
run: dotnet restore
# 4) Build a project or solution and all of its dependencies.
- name: Build
run: dotnet build --configuration Release --no-restore
# 5) Test a project or solution.
- name: Test
run: dotnet test --no-restore --verbosity normal
前面的工作流文件包含許多註釋，以幫助詳細說明工作流的每個區域。您可能已經注意到定義了 GitHub Actions 或簡單命令的steps各種用法。runGitHub Action 和消費 GitHub 工作流之間的關係是工作流消費動作。GitHub Action 僅與消費工作流一樣強大。工作流可以定義任何東西，從簡單的任務到複雜的組合以及介於兩者之間的一切。有關爲 .NET 應用程序創建 GitHub 工作流的更多信息，請參閱以下 .NET 文檔資源：
我希望你問自己，“爲什麼這很重要？” 當然，我們可以創建 GitHub Actions，並且我們可以編寫使用它們的工作流——但爲什麼這很重要？！答案是 GitHub 狀態檢查🤓。
GitHub 狀態檢查
使用工作流的主要好處之一是定義可以確定性地使構建失敗的條件狀態檢查。可以將工作流配置爲拉取請求 (PR) 的狀態檢查，如果工作流失敗，例如拉取請求中的源代碼無法編譯 - 可以阻止 PR 被合併。考慮下面的屏幕截圖，它顯示了兩個檢查失敗，從而阻止了 PR 被合併。
作爲負責審查 PR 的開發人員，您會立即看到拉取請求的狀態檢查失敗。您將與提出 PR 的開發人員合作，以通過所有狀態檢查。以下是顯示“綠色構建”的屏幕截圖，該構建的所有狀態檢查均已通過。
有關更多信息，請參閱GitHub 文檔：GitHub 狀態檢查。
.NET 開發者應該知道的 GitHub Actions
作爲 .NET 開發人員，您可能熟悉.NET CLI。.NET CLI 包含在 .NET SDK 中。如果您還沒有 .NET SDK，可以下載 .NET 6 SDK。
使用之前的工作流文件作爲參考點，有五個步驟 - 每個步驟都包含runoruses語法：
| 動作或命令 | 描述 |
|---|---|
uses: actions/checkout@v2 |
此操作在 下籤出您的存儲庫$GITHUB_WORKSPACE，以便您的工作流程可以訪問它。有關更多信息，請參閱操作/結帳 |
uses: actions/setup-dotnet@v1 |
此操作設置用於操作的 .NET CLI 環境。有關詳細信息，請參閱操作/setup-dotnet |
run: dotnet restore |
恢復項目或解決方案的依賴項和工具。有關詳細信息，請參閱dotnet restore |
run: dotnet build |
構建項目或解決方案。有關詳細信息，請參閱dotnet 構建 |
run: dotnet test |
運行項目或解決方案的測試。有關詳細信息，請參閱dotnet 測試 |
一些steps依賴 GitHub Actions 並使用uses語法引用它們，而另一些則使用run命令。有關差異的更多信息，請參閱 GitHub Actions 的工作流語法：uses和run.
.NET 應用程序依賴於 NuGet 包。您可以通過緩存不經常更改的各種依賴項（例如 NuGet 包）來優化您的工作流。例如，您可以使用緩存 NuGet 包：actions/cache
steps:
- uses: actions/checkout@v2
- name: Setup dotnet
uses: actions/setup-dotnet@v1
with:
dotnet-version: '6.0.x'
- uses: actions/cache@v2
with:
path: ~/.nuget/packages
# Look to see if there is a cache hit for the corresponding requirements file
key: ${{ runner.os }}-nuget-${{ hashFiles('**/packages.lock.json') }}
restore-keys: |
${{ runner.os }}-nuget
- name: Install dependencies
run: dotnet add package Newtonsoft.Json --version 12.0.1
總結
在這篇文章中，我解釋了 GitHub Actions 和 GitHub 工作流之間的主要區別。我解釋並仔細檢查了示例工作流文件中的每一行。然後，我向您展示了開發人員如何將 GitHub 工作流的執行可視化爲序列圖。我分享了一些你可能不知道的額外資源。有關更多信息，請參閱.NET 文檔：GitHub 操作和 .NET。
這只是有關使用 .NET 的 GitHub Actions 的博客的開始。在以後的文章中，我將展示如何使用 .NET 創建 GitHub Actions。我將引導您升級現有的 .NET GitHub 操作，該操作用於在存儲庫的根目錄中自動維護_CODE METRICS.md文件。代碼度量分析目標存儲庫的 C# 源代碼，以確定諸如圈複雜度和可維護性指數等內容。除了這些指標之外，我們還將添加生成Mermaid 類圖的功能，現在 GitHub 風格的 Markdown 原生支持該功能。