注:GitHub Enterprise Server 2.22 上的 GitHub Actions 支持是有限的公测版。 测试已结束。 GitHub Actions 现在一般可用于 GitHub Enterprise Server 3.0 或更新版本。 更多信息请参阅 GitHub Enterprise Server 3.0 发行说明。
- 有关升级到 GitHub Enterprise Server 3.0 或更新版本的更多信息,请参阅“升级 GitHub Enterprise Server”。
- 有关在升级后配置 GitHub Actions 的更多信息,请参阅 GitHub Enterprise Server 3.0 的文档。
注: GitHub 托管的运行器目前在 GitHub Enterprise Server 上不受支持。 您可以在 GitHub 公共路线图 上查看有关未来支持计划的更多信息。
简介
在本指南中,您将了解创建和使用打包的 Docker 容器操作所需的基本组件。 本指南的重点是打包操作所需的组件,因此很少讲操作代码的功能。 操作将在日志文件中打印“Hello World”或“Hello [who-to-greet]”(如果您提供自定义名称)。
完成此项目后,您应了解如何构建自己的 Docker 容器操作和在工作流程测试该操作。
自托管运行器必须使用 Linux 操作系统并安装 Docker 才能运行 Docker 容器操作。 有关自托管运行器要求的更多信息,请参阅“关于自托管运行器”。
警告:创建工作流程和操作时,您应始终考虑您的代码是否会执行来自可能的攻击者的不信任输入。 某些上下文应被视为不受信任的输入,因为攻击者可能会插入自己的恶意内容。 更多信息请参阅“了解脚本注入的风险”。
基本要求
您可能会发现它有助于基本了解 GitHub Actions 环境变量和 Docker 容器文件系统:
-
"使用环境变量"
在开始之前,您需要创建 GitHub 仓库。
-
在 您的 GitHub Enterprise Server 实例 上创建新仓库 您可以选择任何仓库名称或如本例一样使用“hello-world-docker-action”。 更多信息请参阅“创建新仓库”。
-
将仓库克隆到计算机。 更多信息请参阅“克隆仓库”。
-
从您的终端,将目录更改为新仓库。
Shell cd hello-world-docker-action
创建 Dockerfile
在新的 hello-world-docker-action
目录中,创建新的 Dockerfile
文件。 更多信息请参阅“GitHub Actions 的 Dockerfile 支持”。
Dockerfile
# Container image that runs your code
FROM alpine:3.10
# Copies your code file from your action repository to the filesystem path `/` of the container
COPY entrypoint.sh /entrypoint.sh
# Code file to execute when the docker container starts up (`entrypoint.sh`)
ENTRYPOINT ["/entrypoint.sh"]
创建操作元数据文件
在上面创建的 hello-world-docker-action
目录中创建一个新的 action.yml
文件。 更多信息请参阅“GitHub Actions 的元数据语法”。
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]"。
接下来,该脚本会获取当前时间并将其设置为作业中稍后运行的操作可以使用的输出变量。 为便于 GitHub 识别输出变量, 您必须以特定语法使用工作流程命令: echo "::set-output name=<output name>::<value>"
。 更多信息请参阅“GitHub Actions 的工作流程命令”。
-
在
hello-world-docker-action
目录中创建一个新的entrypoint.sh
文件。 -
将以下代码添加到
entrypoint.sh
文件。entrypoint.sh
Shell #!/bin/sh -l echo "Hello $1" time=$(date) echo "::set-output name=time::$time"
如果
entrypoint.sh
执行没有任何错误,则操作的状态设置为success
。 您还可以在操作的代码中显式设置退出代码以提供操作的状态。 更多信息请参阅“设置操作的退出代码”。 -
通过在您的系统上运行以下命令使您的
entrypoint.sh
文件可执行。Shell $ chmod +x entrypoint.sh
创建自述文件
要让人们了解如何使用您的操作,您可以创建自述文件。 自述文件在您计划公开分享操作时最有用,但也是提醒您或您的团队如何使用该操作的绝佳方式。
在 hello-world-docker-action
目录中,创建指定以下信息的 README.md
文件:
- 操作的详细描述。
- 必要的输入和输出变量。
- 可选的输入和输出变量。
- 操作使用的密码。
- 操作使用的环境变量。
- 如何在工作流程中使用操作的示例。
README.md
# Hello world docker action
This action prints "Hello World" or "Hello" + the name of a person to greet to the log.
## Inputs
## `who-to-greet`
**Required** The name of the person to greet. Default `"World"`.
## Outputs
## `time`
The time we greeted you.
## Example usage
uses: actions/hello-world-docker-action@v1
with:
who-to-greet: 'Mona the Octocat'
提交、标记和推送操作到 GitHub Enterprise Server
从您的终端,提交 action.yml
、entrypoint.sh
、Dockerfile
和 README.md
文件。
最佳做法是同时为操作版本添加版本标记。 有关对操作进行版本管理的详细信息,请参阅“关于操作”。
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
在工作流程中测试您的操作
现在,您已准备好在工作流程中测试您的操作。 如果操作位于私有仓库,则该操作只能在同一仓库的工作流程中使用。 公共操作可供任何仓库中的工作流程使用。
注:您的 GitHub Enterprise Server 实例 上的 GitHub Actions 对 GitHub.com 或 GitHub Marketplace 上的操作具有有限的访问权限。 更多信息请参阅“自托管运行器与 GitHub 之间的通信”。
使用公共操作的示例
以下工作流程代码使用公共 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'
# Use the output from the `hello` step
- 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
输入的姓名和时间戳在日志中打印。