Github Actions入门：新手必读教程

概述

本文详细介绍了如何使用Github Actions进行自动化任务，如持续集成（CI）和持续部署（CD）。通过编写YAML文件，开发者能够定义和执行从代码提交到构建、测试、部署等各个阶段的自动化流程。本文不仅提供了创建和配置第一个工作流的步骤，还介绍了如何利用条件判断和任务依赖来控制工作流的执行。此外，文章还涵盖了最佳实践和小技巧，以帮助读者更好地利用Github Actions提高开发效率。

Github Actions简介

什么是Github Actions

Github Actions 是 Github 提供的一项自动化工作流服务。通过编写 YAML 文件，开发者可以定义一系列自动化任务，涵盖从代码提交、构建、测试、部署到环境监控等各个方面。其核心优势在于高度的灵活性和可定制性，允许开发者在合适的时间点自动执行特定操作，从而提高软件开发的效率和质量。

Github Actions的作用和优势

Github Actions 的主要作用是自动化软件开发的各个阶段，从代码提交到构建、测试、部署，再到后期的维护。它能够显著减少人为错误，加速开发和部署流程，并提高软件质量。以下是使用 Github Actions 的一些主要优势：

1. 持续集成/持续部署（CI/CD）：通过自动执行构建、测试和部署，确保每次代码提交都经过严格的检查，提高代码质量，加快软件发布。
2. 环境自动化管理：自动设置和配置开发、测试和生产环境，确保所有环境的一致性。
3. 事件触发的自动化：任何 Github 仓库中的事件（如代码推送、发布标签、打开问题等）都可以触发 Github Actions 的工作流执行。
4. 灵活的配置和扩展：通过编写 YAML 文件定义工作流，可以轻松地添加或修改任务，灵活地适应不同的项目需求。
5. 集成丰富的 Actions 库：Github 提供了一个庞大的 Actions 库，包含各种预定义的任务，如代码扫描、依赖管理等，这些都可以方便地集成到工作流中。
6. 易于监控和调试：工作流的执行过程可以清晰地记录日志，便于监控和调试自动化任务。

总之，Github Actions 是一种强大的自动化工具，它结合了灵活性、可配置性和丰富的资源，帮助开发者实现高效的软件开发和部署流程。

开始使用Github Actions

创建第一个Github Actions工作流

创建第一个 Github Actions 工作流是一个简单的过程。首先，需要在项目的根目录下创建一个名为 .github/workflows/ 的目录，并在其中添加一个 YAML 文件。该文件定义了工作流的配置和具体任务执行的步骤。

下面是一个简单的例子，用于执行基本的代码构建和测试：

1. 在仓库根目录下创建 .github/workflows 文件夹。
2. 在该文件夹中创建一个名为 hello-world.yml 的文件。
3. 编辑 hello-world.yml 文件，添加以下内容：

name: Hello World

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - name: Check out repository code
      uses: actions/checkout@v2

    - name: Run a script
      run: echo "Hello world!"

该配置文件包含了以下几个关键部分：

• name: 定义了工作流的名称。
• on: 指定了触发工作流的事件。在这个例子中，当 main 分支有任何代码推送时，会触发工作流。
• jobs: 包含了工作流的具体任务。每个任务在 jobs 下定义，可以包含多个步骤。
• runs-on: 指定了工作流运行的环境。这里使用的是最新的 Ubuntu 环境。

在这个例子中，创建工作流的目标是输出一条消息。当代码提交到 main 分支时，工作流会被触发，执行以下步骤：

1. 使用 actions/checkout@v2 动作检查出仓库代码。
2. 使用 run 命令执行一个简单的脚本，输出 "Hello world!"。

这个工作流在每次代码推送时都会自动运行，确保每次代码提交后都能得到相应的提示。

配置Github Actions的环境设置

在定义工作流时，有时需要配置各种环境变量、软件包、工具或依赖。这可以通过在工作流文件中设置来实现。下面将介绍如何在工作流中设置环境变量、安装依赖以及配置工具。

设置环境变量

环境变量是工作流运行时可以访问的配置选项。可以通过 env 键来设置环境变量。例如，若要设置一个名为 MY_ENV_VAR 的环境变量，可以使用以下代码：

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      MY_ENV_VAR: "my-value"

    steps:
    - name: Check out repository code
      uses: actions/checkout@v2

    - name: Print environment variable
      run: echo "The value of MY_ENV_VAR is: ${{ env.MY_ENV_VAR }}"

在这个例子中，环境变量 MY_ENV_VAR 被设置为 "my-value"，然后在运行步骤中通过 echo 命令打印该变量的值。

安装依赖

在运行工作流之前，有时需要确保安装特定的软件包或工具。可以通过 actions/setup-node 等动作来安装这些依赖。例如，若要安装 Node.js 和一些 npm 包，可以使用以下代码：

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - name: Check out repository code
      uses: actions/checkout@v2

    - name: Set up Node.js
      uses: actions/setup-node@v2
      with:
        node-version: '14.x'

    - name: Install dependencies
      run: npm install

    - name: Run npm test
      run: npm test

在这个例子中，使用了 actions/setup-node@v2 动作来安装 Node.js 版本 14.x。然后通过 npm install 命令安装项目依赖，并运行 npm test 命令执行测试。

配置工具

有时，可能需要预装一些工具以便在工作流中使用。这可以通过使用特定的 actions 来实现。例如，若要安装并使用 Docker，可以如下配置：

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - name: Check out repository code
      uses: actions/checkout@v2

    - name: Set up Docker
      uses: docker/setup-buildx-action@v1

    - name: Build Docker image
      run: docker build -t my-docker-image .

    - name: Run Docker image
      run: docker run -it my-docker-image

在这个例子中，使用了 docker/setup-buildx-action@v1 动作来设置 Docker。然后通过 docker build 命令构建 Docker 镜像，并通过 docker run 命令运行该镜像。

通过上述配置，可以确保工作流在执行时拥有正确的环境设置，包括环境变量、依赖项和工具的预装状态。

Github Actions常用操作

Github Actions工作流中的基础命令

在 Github Actions 的工作流中，常常会用到一些基础命令来完成任务。这些命令通常用于执行脚本、检查代码、构建项目等。下面是一些常用的命令示例：

运行脚本

在工作流的步骤中，可以使用 run 命令来执行各种脚本。这些脚本可以是简单的命令行命令，也可以是复杂的 shell 脚本。例如：

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - name: Check out repository code
      uses: actions/checkout@v2

    - name: Run a simple script
      run: echo "This is a simple script."

    - name: Run a more complex script
      run: |
        echo "This is a more complex script."
        ls -la
        echo "Directory listing complete."

在上面的示例中，第一个步骤运行了一个简单的 echo 命令，输出一条消息。第二个步骤则运行了一个多行脚本，使用 ls -la 命令列出当前目录的内容，并在脚本结束时输出一条消息。

安装和使用依赖

在工作流中，常常需要安装并使用各种依赖。可以通过 actions/setup-node 等动作来安装和配置依赖。例如，安装 Node.js 和运行 npm 脚本：

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - name: Check out repository code
      uses: actions/checkout@v2

    - name: Set up Node.js
      uses: actions/setup-node@v2
      with:
        node-version: '14.x'

    - name: Install dependencies
      run: npm install

    - name: Run npm test
      run: npm test

在这个示例中，通过 actions/setup-node@v2 动作安装了 Node.js 版本 14.x。然后运行 npm install 来安装项目依赖，最后运行 npm test 执行测试。

使用预设的动作

Github Actions 提供了大量的预设动作，可以直接用于工作流中。例如，可以使用 actions/checkout@v2 动作来检出仓库代码，使用 actions/upload-artifact@v2 动作来上传构建产物等。这些动作简化了工作流的编写过程，使开发者可以专注于业务逻辑。

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - name: Check out repository code
      uses: actions/checkout@v2

    - name: Set up Node.js
      uses: actions/setup-node@v2
      with:
        node-version: '14.x'

    - name: Install dependencies
      run: npm install

    - name: Run npm test
      run: npm test

    - name: Upload artifact
      uses: actions/upload-artifact@v2
      with:
        name: my-artifact
        path: ./dist

在上面的示例中，使用了 actions/upload-artifact@v2 动作来上传构建产物。这里上传了位于 ./dist 目录下的文件，并将其命名为 my-artifact。

通过使用这些基础命令和动作，可以灵活地定义工作流中的各种任务，以实现高效的自动化流程。

了解事件触发与操作执行流程

Github Actions 的工作流可以被多种事件触发，包括代码提交、发布标签、打开问题、拉取请求等。了解这些触发事件有助于更好地设计和管理自动化任务。下面将详细介绍一些常见的触发事件和它们的执行流程。

代码推送

代码推送是最常见的触发事件，当代码被推送到仓库的某个分支时，可以触发工作流执行相应的任务。例如，当代码被推送到 main 分支时，可以配置工作流来执行构建和测试任务。以下是定义代码推送触发事件的示例：

on:
  push:
    branches:
      - main

在这个示例中，当代码被推送到 main 分支时，工作流会被触发。这样可以在每次代码提交时自动执行构建和测试任务。

发布标签

除了代码推送，发布标签也是一种常见的触发事件。当仓库中的代码被发布成一个新的标签时，可以触发特定的任务，如构建新的发布版本或上传新版本到远程仓库。以下是定义发布标签触发事件的示例：

on:
  push:
    tags:
      - v*

在这个示例中，当代码被推送到包含 v 前缀的标签时（如 v1.0.0），工作流会被触发。可以利用这种方式来处理新版本的发布。

拉取请求

拉取请求也是一种重要的触发事件，当有新的拉取请求被创建或更新时，可以自动执行代码审查、测试等任务。例如，可以在拉取请求被创建或更新时执行自动化测试，确保新的代码变更不会引入问题。以下是定义拉取请求触发事件的示例：

on:
  pull_request:
    branches:
      - main

在这个示例中，当有新的拉取请求被创建或更新时，且这些拉取请求涉及 main 分支，工作流会被触发。可以利用这种方式来自动化代码审查和测试过程。

事件触发的执行流程

事件触发后，工作流会被执行，按照定义的步骤逐一完成任务。工作流的执行流程通常包括以下几个步骤：

1. 初始化：当触发事件发生时，Github Actions 会开始初始化工作流。这包括准备环境、拉取代码等。
2. 步骤执行：初始化完成后，工作流会按照定义的步骤依次执行。每个步骤可以调用不同的动作或运行脚本。
3. 环境清理：在所有步骤完成后，工作流会清理环境，确保运行资源被正确释放。

例如，下面是一个完整的示例工作流，展示了如何在代码推送时触发自动化构建和测试任务：

name: Automated Build and Test

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - name: Check out repository code
      uses: actions/checkout@v2

    - name: Set up Node.js
      uses: actions/setup-node@v2
      with:
        node-version: '14.x'

    - name: Install dependencies
      run: npm install

    - name: Run npm test
      run: npm test

    - name: Upload artifact
      uses: actions/upload-artifact@v2
      with:
        name: my-artifact
        path: ./dist

在这个示例中，当代码被推送到 main 分支时，工作流会被触发。工作流首先检查出代码，安装 Node.js 和依赖，然后运行测试并上传构建产物。通过这种方式，可以确保每次代码提交时都会自动执行构建和测试任务，从而提高代码质量。

通过理解这些触发事件和执行流程，可以更好地控制工作流的执行逻辑，从而实现高效和可靠的自动化流程。

Github Actions的小技巧与最佳实践

保持工作流的简洁与可读性

编写简洁且可读性强的工作流文件可以提高代码的维护性。以下是一些小技巧：

1. 使用环境变量：通过环境变量传递配置信息，可以简化工作流文件的编写，使文件更加可读。

2. 使用复用的工作流：通过复用已有的工作流文件，可以减少代码重复，提高代码的复用性。

3. 使用条件判断：通过条件判断来控制任务的执行，可以避免不必要的任务执行，提高代码效率。

避免常见的错误和陷阱

1. 避免在工作流文件中硬编码敏感信息：使用加密的环境变量来存储敏感信息，例如 API 密钥等。

2. 避免频繁触发工作流：频繁触发工作流可能导致资源浪费和执行时间过长。可以设置更合理的时间间隔或条件来触发工作流。

3. 避免任务间依赖设置不当：确保任务之间的依赖关系设置正确，避免任务执行顺序错误导致的失败。

具体案例分析

设置任务间的依赖关系

在 Github Actions 中，可以通过 dependsOn 关键字来设置任务间的依赖关系。这使得可以确保某些任务只有在其他任务成功完成后才会执行。这样可以保证任务的执行顺序和依赖关系，避免任务间的相互干扰。下面将详细介绍如何使用 dependsOn 关键字。

基本使用示例

dependsOn 关键字可以用于定义一个任务依赖于另一个任务的完成。例如，可以定义一个任务 test 依赖于另一个任务 build 的完成。以下是一个示例：

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - name: Check out repository code
      uses: actions/checkout@v2

    - name: Set up Node.js
      uses: actions/setup-node@v2
      with:
        node-version: '14.x'

    - name: Install dependencies
      run: npm install

  test:
    runs-on: ubuntu-latest
    dependsOn: build

    steps:
    - name: Run tests
      run: npm test

在这个示例中，test 任务依赖于 build 任务的完成。这意味着 test 任务只有在 build 任务成功完成后才会执行。这样可以确保测试任务在构建后的环境中运行，避免由于构建未完成而导致的测试失败。

复杂任务依赖关系

在更复杂的场景中，可以设置多个任务之间的依赖关系。例如，可以定义多个任务相互依赖：

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - name: Check out repository code
      uses: actions/checkout@v2

    - name: Set up Node.js
      uses: actions/setup-node@v2
      with:
        node-version: '14.x'

    - name: Install dependencies
      run: npm install

  test:
    runs-on: ubuntu-latest
    dependsOn: build

    steps:
    - name: Run tests
      run: npm test

  deploy:
    runs-on: ubuntu-latest
    dependsOn: test

    steps:
    - name: Deploy application
      run: npm run deploy

在这个示例中，test 任务依赖于 build 任务的完成，而 deploy 任务又依赖于 test 任务的完成。这样可以确保部署任务在构建和测试成功之后才会执行，避免在未通过测试的情况下部署代码。

多分支和多环境的依赖关系

在多分支或多环境的场景中，可以设置更复杂的依赖关系。例如，可以定义一个任务在多个分支上运行，依赖于另一个任务在不同分支上的完成：

jobs:
  build:
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'

    steps:
    - name: Check out repository code
      uses: actions/checkout@v2

    - name: Set up Node.js
      uses: actions/setup-node@v2
      with:
        node-version: '14.x'

    - name: Install dependencies
      run: npm install

  test:
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    dependsOn: build

    steps:
    - name: Run tests
      run: npm test

  deploy:
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    dependsOn: test

    steps:
    - name: Deploy application
      run: npm run deploy

在这个示例中，build、test 和 deploy 任务都在 main 分支上运行，并且相互依赖。这确保了在 main 分支上的所有任务按照正确的顺序执行。

总结

通过使用 dependsOn 关键字，可以有效地控制任务的执行顺序和依赖关系。这确保了工作流中的任务按照预定的顺序执行，避免了任务间的相互干扰。同时，通过条件判断和依赖关系的合理设置，可以创建出更灵活和高效的工作流。

使用条件判断执行任务

在 Github Actions 中，可以使用条件判断来控制任务的执行。这使得工作流可以根据特定的条件来决定是否执行某个步骤或任务。常用的关键字包括 if 和 env，它们允许在工作流文件中设置条件来控制脚本的执行。

使用 if 控制任务的执行

if 关键字可用于根据条件判断是否执行某个步骤。例如，可以在工作流文件中定义一个条件，使得只有在特定分支推送代码时，才会执行某些步骤。下面是一个示例，展示了如何在条件判断中使用 if：

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - name: Check out repository code
      uses: actions/checkout@v2

    - name: Run tests if main branch
      if: github.ref == 'refs/heads/main'
      run: npm test

    - name: Run deployment script
      if: github.ref == 'refs/tags/v*'
      run: npm run deploy

在这个示例中，使用了 if 关键字来判断是否执行某些任务。第一个任务只有在代码推送到 main 分支时才会执行 npm test 命令，第二个任务只有在代码推送到带有 v 前缀的标签时才会执行 npm run deploy。

使用 env 设置环境变量

env 键可以用来设置环境变量，这些变量可以在整个工作流中使用。例如，可以设置一个环境变量，决定是否运行特定的任务。下面是一个示例，展示了如何使用 env 来控制任务的执行：

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      SHOULD_RUN_TESTS: "true"

    steps:
    - name: Check out repository code
      uses: actions/checkout@v2

    - name: Run tests if SHOULD_RUN_TESTS is true
      if: env.SHOULD_RUN_TESTS == 'true'
      run: npm test

在这个示例中，定义了一个名为 SHOULD_RUN_TESTS 的环境变量，并设置为 "true"。只有当 SHOULD_RUN_TESTS 为 "true" 时，才会执行 npm test 命令。

通过这些条件判断方法，可以灵活地控制工作流中的任务执行，确保只有在满足特定条件时才会执行相关任务。

Github Actions的输出与调试

查看工作流运行日志

在 Github Actions 中，每个任务的执行都会生成日志，这些日志可以帮助开发者了解任务的执行情况。日志记录了每个步骤的详细信息，包括执行的时间、输入输出、环境变量等。查看这些日志对于定位和解决任务执行中的问题非常重要。下面是具体的查看日志步骤：

1. 导航到仓库页面：在 Github 中打开想要查看的日志的仓库。
2. 进入工作流页面：点击仓库页面顶部的 "Actions" 按钮。
3. 选择工作流：在工作流页面，选择想要查看的日志的工作流。可以按时间、状态或特定任务筛选工作流。
4. 查看日志：点击特定工作流运行的时间戳，进入到该运行的详细页面。在这个页面中，可以查看每个步骤的日志，包括输出的文本、环境变量等。

例如，假设有一个名为 build-and-test.yml 的工作流文件，以下是查看该文件运行时的日志步骤：

name: Automated Build and Test

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - name: Check out repository code
      uses: actions/checkout@v2

    - name: Set up Node.js
      uses: actions/setup-node@v2
      with:
        node-version: '14.x'

    - name: Install dependencies
      run: npm install

    - name: Run npm test
      run: npm test

    - name: Upload artifact
      uses: actions/upload-artifact@v2
      with:
        name: my-artifact
        path: ./dist

当代码推送触发这个工作流运行时，可以在工作流页面查看每个步骤的日志。例如，可以点击 Check out repository code 步骤来查看代码检出过程的日志，点击 Run npm test 步骤来查看测试执行的日志。

通过这些日志，可以详细地了解每个步骤的执行情况，包括输出的文本、环境变量设置等，有助于调试和优化工作流。

调试Github Actions中的错误

在 Github Actions 中，如果任务执行失败，通常会在日志中显示错误信息。这些错误信息可以帮助开发者理解问题所在，并采取相应的措施进行修复。下面将详细介绍如何使用日志来调试 Github Actions 中的错误。

查找错误日志

当 Github Actions 的任务执行失败时，日志中会显示详细的错误信息。这些信息通常包括错误代码、错误消息和错误发生的位置。例如，假设在 npm test 步骤中发生了错误，可以在该步骤的日志中找到具体的错误信息：

name: Automated Build and Test

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - name: Check out repository code
      uses: actions/checkout@v2

    - name: Set up Node.js
      uses: actions/setup-node@v2
      with:
        node-version: '14.x'

    - name: Install dependencies
      run: npm install

    - name: Run npm test
      run: npm test

    - name: Upload artifact
      uses: actions/upload-artifact@v2
      with:
        name: my-artifact
        path: ./dist

假设在 Run npm test 步骤中发生了错误，可以在该步骤的日志中查找具体的错误信息。例如，日志中可能包含以下错误信息：

npm ERR! Test failed.
npm ERR! Exit with error code: 1

分析错误信息

根据错误信息，可以进一步分析具体的问题。例如，如果错误信息显示 npm ERR! Test failed，意味着测试脚本执行失败。可以查看测试脚本的输出，了解具体的测试用例失败原因：

npm ERR! Test error:
npm ERR! Error in test case 'test/unit/test1.js'
npm ERR! Error: Test assertion failed

通过查看测试脚本的具体输出，可以定位到具体的测试用例 test1.js 失败的原因，并进行相应的修复。

修复错误

根据分析到的错误信息，可以进行相应的修复。例如，如果测试用例 test1.js 失败，可以修改该测试用例或修复被测试的代码：

// 修改测试用例 test1.js
it('should pass', () => {
  expect(1).toBe(1);
});

重新触发工作流

修复错误后，可以重新触发工作流来验证修复是否有效。可以在 Github 的仓库页面，通过重新推送代码或手动触发特定的工作流来测试修复效果。例如，重新推送代码到 main 分支触发 build-and-test.yml 工作流：

name: Automated Build and Test

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - name: Check out repository code
      uses: actions/checkout@v2

    - name: Set up Node.js
      uses: actions/setup-node@v2
      with:
        node-version: '14.x'

    - name: Install dependencies
      run: npm install

    - name: Run npm test
      run: npm test

    - name: Upload artifact
      uses: actions/upload-artifact@v2
      with:
        name: my-artifact
        path: ./dist

重新推送代码后，可以在工作流页面查看新触发的工作流运行情况，确保修复后的代码通过了所有测试。

通过以上步骤，可以有效地调试和修复 Github Actions 中的错误，确保工作流的稳定性和可靠性。