【翻译】.NET 💜 GitHub Actions: .NET 的 GitHub Actions 简介

原文 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 文档资源：

• 创建构建验证工作流程
• 创建测试验证工作流程
• 创建部署工作流
• 创建 CodeQL 安全漏洞扫描 CRON 作业工作流

我希望你问自己，“为什么这很重要？” 当然，我们可以创建 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 原生支持该功能。