我们经常发布文档更新,此页面的翻译可能仍在进行中。有关最新信息,请访问英文文档。如果此页面上的翻译有问题,请告诉我们

创建 Docker 容器操作

本指南向您展示构建 Docker 容器操作所需的最少步骤。

GitHub 操作 可用于 GitHub Free、GitHub Pro、GitHub Team、GitHub Enterprise Cloud 和 GitHub One。 GitHub 操作 is not available for private repositories owned by accounts using legacy per-repository plans. 更多信息请参阅“GitHub 的产品”。

本文内容

简介

In this guide, you'll learn about the basic components needed to create and use a packaged Docker container action. To focus this guide on the components needed to package the action, the functionality of the action's code is minimal. The action prints "Hello World" in the logs or "Hello [who-to-greet]" if you provide a custom name.

完成此项目后,您应了解如何构建自己的 Docker 容器操作和在工作流程测试该操作。

Self-hosted runners must use a Linux operating system and have Docker installed to run Docker container actions. For more information about the requirements of self-hosted runners, see "About self-hosted runners."

基本要求

You may find it helpful to have a basic understanding of GitHub 操作 environment variables and the Docker container filesystem:

开始之前,您需要创建 GitHub 仓库。

  1. 在 GitHub 上创建新仓库 您可以选择任何仓库名称或如本例一样使用“hello-world-docker-action”。 更多信息请参阅“创建新仓库”。

  2. 将仓库克隆到计算机。 更多信息请参阅“克隆仓库”。

  3. 从您的终端,将目录更改为新仓库。

    cd hello-world-docker-action

创建 Dockerfile

在新的 hello-world-docker-action 目录中,创建新的 Dockerfile 文件。

Dockerfile

# 运行代码的容器图像
FROM alpine:3.10

# 从操作仓科到容器的文件系统路径 `/`的副本
COPY entrypoint.sh /entrypoint.sh

# Docker 容器启动时执行的代码文件 (`entrypoint.sh`)
ENTRYPOINT ["/entrypoint.sh"]

创建操作元数据文件

在上面创建的 hello-world-docker-action 目录中创建一个新的 action.yml 文件。 For more information, see "Metadata syntax for GitHub 操作."

action.yml

# action.yml
name: 'Hello World'
description: 'Greet someone and record the time'
inputs:
  who-to-greet:  # id of input
    description: 'Who to greet'
    required: true
    default: 'World'
outputs:
  time: # id of output
    description: 'The time we greeted you'
runs:
  using: 'docker'
  image: 'Dockerfile'
  args:
    - ${{ inputs.who-to-greet }}

此元数据定义一个 who-to-greet 输入和一个 time 输出参数。 要将输入传递给 Docker 容器,您必须使用 inputs 声明输入并以 args 关键词传递输入。

GitHub 将从 Dockerfile 构建映像,然后使用此映像在新容器中运行命令。

编写操作代码

您可以选择任何基础 Docker 映像,并因此为您的操作选择任何语言。 以下 shell 脚本示例使用 who-to-greet 输入变量在日志文件中打印 "Hello [who-to-greet]"。

接下来,该脚本会获取当前时间并将其设置为作业中稍后运行的操作可以使用的输出变量。 In order for GitHub to recognize output variables, you must use a workflow command in a specific syntax: echo "::set-output name=<output name>::<value>". For more information, see "Workflow commands for GitHub 操作."

  1. hello-world-docker-action 目录中创建一个新的 entrypoint.sh 文件。

  2. Make sure to make your entrypoint.sh file executable:

    chmod +x entrypoint.sh
  3. 将以下代码添加到 entrypoint.sh 文件。

    entrypoint.sh

    #!/bin/sh -l
    
    echo "Hello $1"
    time=$(date)
    echo "::set-output name=time::$time"

    如果 entrypoint.sh 执行没有任何错误,则操作的状态设置为 success。 您还可以在操作的代码中显式设置退出代码以提供操作的状态。 For more information, see "Setting exit codes for actions."

创建自述文件

要让人们了解如何使用您的操作,您可以创建自述文件。 自述文件在您计划公开分享操作时最有用,但也是提醒您或您的团队如何使用该操作的绝佳方式。

hello-world-docker-action 目录中,创建指定以下信息的 README.md 文件:

  • 操作的详细描述。
  • 必要的输入和输出变量。
  • 可选的输入和输出变量。
  • 操作使用的密码。
  • 操作使用的环境变量。
  • 如何在工作流程中使用操作的示例。

README.md

# Hello world docker action

此操作将 "Hello World" 或 "Hello" + 要问候的人员的姓名打印到日志。

## Inputs

### `who-to-greet`

**必填** 要问候的人员的姓名。 默认值为 `"World"`## Outputs

### `time`

我们问候您的时间。

## Example usage

使用:actions/hello-world-docker-action@v1
及:
  who-to-greet: 'Mona the Octocat'

Commit, tag, and push your action to GitHub

从您的终端,提交 action.ymlentrypoint.shDockerfileREADME.md 文件。

It's best practice to also add a version tag for releases of your action. For more information on versioning your action, see "About actions."

git add action.yml entrypoint.sh Dockerfile README.md
git commit -m "My first action is ready"
git tag -a -m "My first action release" v1
git push --follow-tags

在工作流程中测试您的操作

现在,您已准备好在工作流程中测试您的操作。 如果操作位于私有仓库,则该操作只能在同一仓库的工作流程中使用。 公共操作可供任何仓库中的工作流程使用。

使用公共操作的示例

以下工作流程代码使用公共 actions/hello-world-docker-action 仓库中完整的 hello world 操作。 将以下工作流程示例代码复制到 .github/workflows/main.yml 文件中,但将 actions/hello-world-docker-action 替换为您的仓库和操作名称。 您还可以将 who-to-greet 输入替换为您的名称。

.github/workflows/main.yml

on: [push]

jobs:
  hello_world_job:
    runs-on: ubuntu-latest
    name: A job to say hello
    steps:
    - name: Hello world action step
      id: hello
      uses: actions/hello-world-docker-action@v1
      with:
        who-to-greet: 'Mona the Octocat'
    # 使用来自 `hello` 步骤的输出
    - name: Get the output time
      run: echo "The time was ${{ steps.hello.outputs.time }}"

使用私有操作的示例

将以下示例工作流程代码复制到操作仓库中的 .github/workflows/main.yml 文件。 您还可以将 who-to-greet 输入替换为您的名称。

.github/workflows/main.yml

on: [push]

jobs:
  hello_world_job:
    runs-on: ubuntu-latest
    name: A job to say hello
    steps:
      # To use this repository's private action, you must check out the repository
      - name: Checkout
        uses: actions/checkout@v2
      - name: Hello world action step
        uses: ./ # Uses an action in the root directory
        id: hello
        with:
          who-to-greet: 'Mona the Octocat'
      # Use the output from the `hello` step
      - name: Get the output time
        run: echo "The time was ${{ steps.hello.outputs.time }}"

从您的仓库中,单击 Actions(操作)选项卡,然后选择最新运行的工作流程。 您应看到 "Hello Mona the Octocat" 或您用于 who-to-greet 输入的姓名和时间戳在日志中打印。

在工作流中使用操作的屏幕截图

问问别人

找不到要找的内容?

联系我们