Deploying with GitHub Actions

Prerequisites

You should be familiar with the syntax for GitHub Actions. For more information, see 写入工作流.

Using environments

环境用于描述常规部署目标，例如 production、staging 或 development。当 GitHub Actions 工作流部署到某个环境时，该环境将显示在存储库的主页上。可以使用环境来要求审批作业以继续，限制可以触发工作流的分支，使用自定义部署保护规则控制部署，或限制对机密的访问权限。有关创建环境的详细信息，请参阅“管理部署环境”。

You can configure environments with protection rules and secrets. When a workflow job references an environment, the job won't start until all of the environment's protection rules pass. A job also cannot access secrets that are defined in an environment until all the deployment protection rules pass. To learn more, see Using custom deployment protection rules in this article.

Using concurrency

Concurrency ensures that only a single job or workflow using the same concurrency group will run at a time. You can use concurrency so that an environment has a maximum of one deployment in progress and one deployment pending at a time. For more information about concurrency, see 控制工作流和作业的并发性.

注意

concurrency and environment are not connected. The concurrency value can be any string; it does not need to be an environment name. Additionally, if another workflow uses the same environment but does not specify concurrency, that workflow will not be subject to any concurrency rules.

For example, when the following workflow runs, it will be paused with the status pending if any job or workflow that uses the production concurrency group is in progress. It will also cancel any job or workflow that uses the production concurrency group and has the status pending. This means that there will be a maximum of one running and one pending job or workflow in that uses the production concurrency group.

name: Deployment

concurrency: production

on:
  push:
    branches:
      - main

jobs:
  deployment:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - name: deploy
        # ...deployment-specific steps

You can also specify concurrency at the job level. This will allow other jobs in the workflow to proceed even if the concurrent job is pending.

name: Deployment

on:
  push:
    branches:
      - main

jobs:
  deployment:
    runs-on: ubuntu-latest
    environment: production
    concurrency: production
    steps:
      - name: deploy
        # ...deployment-specific steps

You can also use cancel-in-progress to cancel any currently running job or workflow in the same concurrency group.

name: Deployment

concurrency:
  group: production
  cancel-in-progress: true

on:
  push:
    branches:
      - main

jobs:
  deployment:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - name: deploy
        # ...deployment-specific steps

For guidance on writing deployment-specific steps, see Finding deployment examples.

Viewing deployment history

When a GitHub Actions workflow deploys to an environment, the environment is displayed on the main page of the repository. For more information about viewing deployments to environments, see 查看部署历史记录.

Monitoring workflow runs

Every workflow run generates a real-time graph that illustrates the run progress. You can use this graph to monitor and debug deployments. For more information see, 使用可视化图表.

You can also view the logs of each workflow run and the history of workflow runs. For more information, see 查看工作流程运行历史记录.

Using required reviews in workflows

Jobs that reference an environment configured with required reviewers will wait for an approval before starting. While a job is awaiting approval, it has a status of "Waiting". If a job is not approved within 30 days, it will automatically fail.

For more information about environments and required approvals, see 管理部署环境. For information about how to review deployments with the REST API, see 工作流运行的 REST API 终结点.

Using custom deployment protection rules

注意

自定义部署保护规则目前为公共预览版，可能随时更改。

可以启用自己的自定义保护规则来限制第三方服务的部署。例如，可以使用 Datadog、Honeycomb 和 ServiceNow 等服务为部署到 GitHub 提供自动审批。

Custom deployment protection rules are powered by GitHub Apps and run based on webhooks and callbacks. Approval or rejection of a workflow job is based on consumption of the deployment_protection_rule webhook. For more information, see Webhook 事件和有效负载 and Approving or rejecting deployments.

Once you have created a custom deployment protection rule and installed it on your repository, the custom deployment protection rule will automatically be available for all environments in the repository.

Deployments to an environment can be approved or rejected based on the conditions defined in any external service like an approved ticket in an IT Service Management (ITSM) system, vulnerable scan result on dependencies, or stable health metrics of a cloud resource. The decision to approve or reject deployments is at the discretion of the integrating third-party application and the gating conditions you define in them. The following are a few use cases for which you can create a deployment protection rule.

ITSM & Security Operations: you can check for service readiness by validating quality, security, and compliance processes that verify deployment readiness.
Observability systems: you can consult monitoring or observability systems (Asset Performance Management Systems and logging aggregators, cloud resource health verification systems, etc.) for verifying the safety and deployment readiness.
Code quality & testing tools: you can check for automated tests on CI builds which need to be deployed to an environment.

Alternatively, you can write your own protection rules for any of the above use cases or you can define any custom logic to safely approve or reject deployments from pre-production to production environments.

Tracking deployments through apps

You can also build an app that uses deployment and deployment status webhooks to track deployments. 当引用环境的工作流作业运行时，它将创建一个部署对象并将 environment 属性设置为环境名称。随着工作流的进行，它还将创建部署状态对象，并将 environment 属性设置为环境名称，将 environment_url 属性设置为环境的 URL（如果在工作流中指定），以及将 state 属性设置为作业的状态。 For more information, see GitHub 应用文档 and Webhook 事件和有效负载.

Choosing a runner

You can run your deployment workflow on GitHub-hosted runners or on self-hosted runners. Traffic from GitHub-hosted runners can come from a wide range of network addresses. If you are deploying to an internal environment and your company restricts external traffic into private networks, GitHub Actions workflows running on GitHub-hosted runners may not be able to communicate with your internal services or resources. To overcome this, you can host your own runners. For more information, see 关于自托管运行程序 and About GitHub-hosted runners.

Displaying a status badge

You can use a status badge to display the status of your deployment workflow. 状态徽章显示工作流程目前失败还是通过。添加状态徽章的常见位置是存储库的 README.md 文件，但也可将其添加到你喜欢的任何网页。默认情况下，徽章显示默认分支的状态。如果默认分支上没有工作流运行，它将显示所有分支中最近运行的状态。也可以在 URL 中使用 branch 和 event 查询参数显示特定分支或事件的工作流运行的状态。