⚡️ 6分钟内创建你的第一个GitHub操作

Sapper 的 GitHub Action

介绍

开发者社区的朋友们，大家好！😉 新的一天，又带来了一些关于 GitHub Actions 的实用信息。之前，我们探讨了如何在推送代码后将静态 11ty 网站部署到远程虚拟服务器，希望大家已经掌握了文章中提到的要点。

使用Marketplace 中现成的GitHub Actions 固然不错，但是……如果它们不可用，或者/以及您的配置过于特殊怎么办？

没错！👌 让我们来写下你的第一个行动吧。

📝 目录

• 示例的基础
• GitHub Action 基础知识
  • action.yml
  • Dockerfile
  • entrypoint.sh
  • 其他文件和文件夹
• 文档
• 将操作发布到 GitHub Marketplace
  • 最终结果
• 为了更好地理解，请提出以下问题
• 独立执行练习

示例的基础

让我们来看看我为构建基于 Sapper 的网站而创建的 GitHub Action ：

- name: Build
  uses: truewebartisans/actions-sapper@master
  with:
    build_mode: "export"
    args: "--legacy --entry about"

name: Build Sapper and Deploy to GitHub Pages
on: [push]

jobs:
  build_deploy:
    runs-on: ubuntu-latest
    steps:

GitHub Action 基础知识

通常，GitHub Action 项目的结构如下所示：

.
├── .gitignore
├── .github
│   ├── gh-cover.png
│   └── workflows
│       └── test_deploy.yml
├── action.yml
├── Dockerfile
├── entrypoint.sh
├── LICENSE
└── README.md

现在，让我们来分析最基本的文件。在下面的代码示例中，我特意划分了不同的部分并做了标记，以便于阅读。

但是，你的行动可能并非如此……😏

↑ 目录

├── action.yml

这是该操作的设置文件。

# Action's main info
name: "Sapper Action"
description: "Build your Sapper-based static website"

# Action's author name
author: "Vic Shóstak"

# Action's branding data for GitHub Marketplace
# See docs: [1]
branding:
  icon: "package" # icon name from Feather open source icons pack
  color: "blue"

# Action's inputs (options)
# See docs: [2]
inputs:

  # First input (option) name
  # See docs: [3]
  build_mode:

    # Input's description
    description: "Build mode to the Sapper (could be `build` or `export`, by default `export`)"

    # Specify, if this input is required to define
    required: false

    # Input's default value
    default: "export"

  # Second input (option) name
  args:
    description: "Arguments to pass to the Sapper invocation (by default `--legacy`)"
    required: false
    default: "--legacy"

# Configures the image (used for the Docker action)
# See docs: [4]
runs:

  # Use Docker to run the action 
  using: "docker"

  # The Docker image to use as the container to run the action
  # or path to 'Dockerfile' with settings
  image: "Dockerfile"

🔗 文档链接：[1]、[2]、[3]、[4]。

↑ 目录

├── Dockerfile

是的，正如你已经理解的那样，这是一个常规的Dockerfile容器设置（与你在项目中通常使用的设置相同）：

# Select the Docker image
FROM node:10-alpine

# Copy `entrypoint.sh` file to container's root
COPY entrypoint.sh /

# Set permissions for `entrypoint.sh` file execution 
RUN chmod +x /entrypoint.sh

# Define an entrypoint to be called after the container is created
ENTRYPOINT ["/entrypoint.sh"]

☝️提示：请阅读此处的Dockerfile 编写最佳实践 。

↑ 目录

├── entrypoint.sh

入口点将在容器创建后被调用。在我们的例子中，它只是一个简单的bash脚本。

#!/bin/sh

echo "Running \`npm install\`"
npm install

echo "Build Sapper"
npx sapper $INPUT_BUILD_MODE $INPUT_ARGS

请注意，在文件中$INPUT_BUILD_MODE等同于，同样的逻辑也适用于括号( )。换句话说，所有允许用户定义的变量都应该定义为。inputs.build_modeactions.yml$INPUT_ARGSinputs.args$INPUT_<OPTION_NAME>

条件运算符示例

如果某个变量是特定的，你可以用boolean变量定义它action.yml，然后在变量中检查它entrypoint.sh。

• inputs为“部分”指定一个新的输入action.yml：

# ...

inputs: 
  npm_install:
    description: 'If set to `true`, `npm install` will be run'
    required: false
    default: false

# ...

☝️提示：文件中变量名的大小写并不重要action.yml，但必须全部是大写字母或全部是小写字母！

• 现在，只需添加if...then以下部分entrypoint.sh：

#!/bin/sh

if [ "$INPUT_NPM_INSTALL" = "true" ]; then
  echo "Running \`npm install\`"
  npm install
fi

# ...

↑ 目录

其他文件和文件夹

• .github/workflows/test_build.yml— 测试您的操作（可选）。
• .github/gh-cover.png— 预览封面图片，如下所示：

↑ 目录

文档

GitHub Action 的文档和使用示例README.md至关重要。因为你的 Action很可能会被其他开发者使用！创建新 Action 时，务必牢记这一点。

以下是一些简单的规则，可以帮助你编写出真正优秀的文档：

• 一开始就写一份详细的入门指南。
• 将所有可选值（）格式化为表格inputs格式，遵循字符串结构：Input name，，，。Is required?Default valueDescription
• 添加更多示例，特别是如果您的操作可以构建成一系列操作，或者只能与另一个 GitHub 操作结合使用。

• 为您的 GitHub 仓库添加美观易懂的预览图。这一点非常重要，因为当人们分享您的 GitHub 操作链接时，他们会看到一个吸引人的预览图，这有助于提高转化率！

☝️提示：您可以下载一个特殊的模板（带有安全缩进）来创建封面图片，以便预览您的存储库。

• （高级）添加一个演示仓库，其中包含如何应用您的 GitHub 操作的示例，就像我为这个示例的操作所做的那样：

↑ 目录

将操作发布到 GitHub Marketplace

好的！👍 我们现在已完全准备好将您的第一个操作发布到 GitHub Actions Marketplace。

1. 前往仓库中的Releases页面，并起草新的版本发布。
2. 查看Publish this Action to the GitHub Marketplace。
3. GitHub 将检查与该操作相关的所有文件，如果发现任何不符合最佳实践或/和社区协议的内容，将会发出警告。
4. 添加Security contact email。
5. 添加Primary和Secondary操作类别。
6. 指定标签版本（使用语义化版本控制）、标题和描述。
7. 点击Publish release。

如果一切操作正确，那么您的仓库主页上将会添加一个徽章，邀请您在 GitHub Marketplace 上查看此操作：

↑ 目录

最终结果

事实上，就是这样！😎 您刚刚创建了您的第一个 GitHub 操作，为其编写了优秀的文档，并将其发布到了 Marketplace 上。

🎉 恭喜！我们成功了！

↑ 目录

💬 问题以加深理解

1. 在什么情况下应该写出每个名称input？
2. brandingGitHub Actions在文件部分使用哪套图标集action.yml？
3. 在为发布版本选择标签时，最佳实践是什么？
4. 如何在GitHub Actions中定义环境变量input？请阅读GitHub Actions文档中的这一部分。

↑ 目录

✏️ 独立完成的练习

• 请尝试用自己的方式重现文章中提到的所有内容。请在本文评论区分享您的结果！
• 在 GitHub Marketplace 上更改操作的颜色和图标。

↑ 目录

照片/图像由

• GitHub Actions推广网站（链接）
• GitHub 仓库设置（链接）
• 真正的网络艺术家actions-sapper资源库（链接）

PS

如果你想在这个博客上看到更多类似的文章，请在下方留言并订阅我。谢谢！😻

❗️您可以通过Boosty平台支持我，既可以长期支持，也可以一次性支持。所有收益都将用于支持我的开源软件项目，并激励我为社区创作新的产品和文章。

当然，您也可以帮助我让开发者的工作变得更好！只需以贡献者的身份加入我的项目即可。很简单！

我最需要你帮助（和点赞）的项目👇

• 🔥 gowebly：一款新一代 CLI 工具，可轻松使用 Go 在后端创建出色的 Web 应用程序，使用 htmx、hyperscript 或 Alpine.js 以及最流行的 CSS 框架在前端进行开发。
• ✨ create-go-app：通过运行一条 CLI 命令，创建一个包含 Go 后端、前端和部署自动化功能的新生产就绪项目。

我的其他一些小项目：yatr、gosl、json2csv、csv2api。