CHAPTER 4 : Working with Workflows
我相信您现在已经收集到了，工作流是使用GitHub操作的核心。
我已经介绍了一些理解工作流的基本知识。
但是，您还需要能够轻松地创建、运行和监控它们的成功/失败。
本章将重点介绍这些活动。
首先，我将调查GitHub为从启动程序创建工作流所提供的一些特性。
然后，我将向您展示如何在GitHub界面中编辑工作流，以及如何使用提交和拉请求等操作在同一界面中驱动更改。
在此过程中，您将学习如何浏览工作流运行的结果，以及如何监控工作流的执行。
最后，我将向您展示如何使用更新后的GitHub操作VS代码扩展来创建和编辑工作流，以及如何在Visual Studio代码（VS代码）中管理和监视您的运行。
首先是一个关于在存储库中创建初始工作流的指南。
Creating the First Workflow in a Repository：在存储库中创建第一个工作流
假设您有一个存储库，其中您没有使用GitHub操作，并且您想要启动。
你该如何开始呢❓
首先，让我们来看看GitHub中的一个简单项目示例。图4-1显示了一个包含几个文件的基本存储库。
如果在没有现有工作流的存储库中单击顶部菜单中的“Action”选项卡，则会显示操作的开始页面。
（如果需要，你也可以通过访问https:<访问你的github回购路径>/action/new 来访问这个页面。）
如果您有一个存储库中已经有特定类型的代码（Go、Java等），GitHub建议的工作流将会考虑到这一点。
图4-2显示了一个包含Go代码的存储库的入门页面。
GitHub建议使用这个存储库来代替通用的存储库。
当存储库中没有新的工作流时，有四种方法可以开始使用新的工作流：
• 单击搜索工作流操作上方的设置工作流自己的链接。
• 单击此存储库的建议标题下的建议工作流的配置按钮。
• 滚动并从其他建议的工作流中选择，并单击相应的图形按钮。
• 在GitHub之外创建一个工作流文件，并将其添加到存储库中的一个.github/工作流子目录中。
选择前两个选项中的任何一个，都可以将基本工作流的代码放在web界面的编辑器中。
对于工作流文件的名称，它以一个包含.github/workflows的路径和一个反映建议的工作流的名称字段开始。
该字段可以被编辑为具有您想要的任何名称。您可以回空格和编辑路径。
但是，正如在第1章中所讨论的，工作流需要生活在项目中的.github/workflows子目录中。
❗Moving a File Within a Repository：在存储库中移动文件作为一般的提示，在GitHub界面中编辑一个文件，然后修改名称区域中的目录路径（通过反向间隔和键入）是更改位置和在存储库中移动文件的一种简单方法。
窗口的右侧部分显示了 Featured 操作。
如果存储库包含特定类型的代码，则此窗口将显示一组相关的操作。
（但你总是可以通过该窗口中的搜索框来搜索其他操作。）
图4-3显示了在选择简单工作流模板并单击其配置按钮后在编辑器中填充的示例工作流。
这里显示了这个启动器工作流的完整代码。我将向您介绍一下这个代码接下来要做些什么：
查看该列表，您可以确定在第2章和第3章中讨论的工作流的组件。
从第7行开始，on部分定义了何时将调用此工作流。
在这种情况下，对主分支的push或pull请求将导致触发工作流。
这个工作流还包括在第15行中的一个workflow_dispatch子句。
一旦该代码提交到默认分支上，GitHub将在“Action”屏幕上添加一个按钮，为您提供手动运行此工作流的选项。
（workflow_dispatch触发器的使用，稍后将在第12章详细介绍。）
❗workflow_dispatch and Branches如果工作流包含workflow_dispatch子句，那么带有子句的工作流文件的实例必须存在于默认分支（通常是主分支）上，这样按钮才能显示在界面中。
作业部分从第18行开始。此工作流中只有一个作业—即构建一个作业。在作业开始时，您有运行子句（第22行），
它描述了此工作流将will/can执行的系统类型。在本例中，它是在一个运行Linux Ubuntu发行版的系统上。
然后是生成作业中的步骤部分（从第25行开始）。
如前所述，步骤可以调用预定义的操作，或者通过shell执行操作系统命令。
在这个启动工作流中，您同时有这两种步骤。
在第27行，第一步使用GitHub Action checkout@v3 来在工作流运行时检查这个存储库的内容。
在第29-37行中，执行简单的shell命令，通过run子句响应文本的shell命令。在创建或编辑工作流后，需要将其提交回存储库。
下一节将展示如何在不离开GitHub web界面的情况下做到这一点。
在创建或编辑工作流后，需要将其提交回存储库。
下一节将展示如何在不离开GitHub web界面的情况下做到这一点。
Committing the Initial Workflow
当您最初在 GitHub web 编辑器中编写工作流时，它还不是代码库的一部分。
就像您在本地编辑一个新文件一样，您需要将其提交到存储库中。
在此之前，如果需要，可以通过编辑以名称：开头的文件中的行（本示例中的第3行）来更改工作流的名称。
完成编辑后，只需单击编辑器屏幕右上角的“changes更改”按钮。图4-4显示了该按钮。
在本例中，我离开了名为CI的启动工作流，但将工作流文件本身重命名为basic.yml。
❗Editing the Workflow File’s Path如前所述，您可以在路径区域中退空，并更改存储工作流的目录。但不要。
工作流必须在恢复的.github/workflows目录中，才能使用操作框架。
单击“Commit changes”按钮后，将显示一个pop-up对话框，以收集有关提交的更多信息（图4-5)。
这包括描述和选择是通过对当前分支进行简单的提交来进行更改，还是创建一个新的分支并通过拉拉请求来进行更改。
我在这里直接提交到当前分支，但将在章节的后面显示拉请求示例。
对于这种情况，您可以随意添加一些注释，将默认值保留为直接提交到
在提交完成后，该文件将被添加到存储库中的代码库中。
现在，如果您切换到顶部菜单中的“ Actions ”选项卡，则工作流将正在运行（或已运行）。
为什么当向main提交时，满足on部分中工作流指定的标准：
这是一个很好的机会来分解这个屏幕向你展示的内容以及如何浏览它。
从左侧开始的是与此存储库关联的工作流的列表。
此列表中选择的项目将过滤哪些工作流运行。
默认情况下，将选择“所有工作流”项，并且所有工作流的运行情况都将显示在列表中。
如果您在左侧的列表中选择了一个特定的工作流，那么它将过滤右侧的列表，以只显示有关所选工作流的信息。（该界面如图4-7所示。）
因为只有一个工作流只有一个运行，所以这里没有什么有趣的地方。
现在与所选择的特定工作流一起显示的另一个部分是带有“此工作流有一个 workflow_dispatch 事件 触发”一行的框
和运行工作流按钮。我现在看到这个问题的原因是，我选择了左边的这个工作流（而不是所有的工作流选择）。
这个工作流在默认分支的工作流文件的on部分包含以下代码：
这是一个 workflow_dispatch 触发器类型的实例。
它显示一个按钮，可以手动启动另一个工作流的运行。
当您按下它时，您会看到一个小对话框，允许您选择一个分支来运行它，如果定义了其他选项（参见第8章）。
如果调用，将执行工作流，并将另一个运行添加到列表中，如图4-8所示。
这种直接调用工作流的直接调用对于原型化、调试和其他您可能不总是希望在GitHub中导致一个事件来触发运行的情况非常有用。
如果您仔细查看这些运行的描述（在左边的圆圈中带有复选标记的行下），您可以阅读关于每次运行中启动的事件的信息。
这些是按照执行的时间排序的，从顶部的最新运行开始。
运行后，您可能希望返回并对工作流进行一些编辑，以纠正或添加某些内容。您可以向下克隆存储库并在本地编辑该文件。
或者，您可以回到GitHub中的存储库的代码部分，选择一个文件，并从那里编辑它。
此页面上的“操作”界面提供了另一种可以直接进入工作流代码的快捷方式：单击顶部工作流标题下的小YAML文件名。
图4-9显示了我正在讨论的元素。在本例中，link/name 是basic.yml。
单击该链接将进入web编辑器中的文件视图。在文件上方灰色条的右上角部分是一小组图标。找那个看起来像铅笔的。
您可以单击此图标以直接在浏览器中编辑该文件（图4-10)。
单击铅笔图标将显示该文件的基本编辑界面。
除了能够更改文件的名称和路径（通过代码上方的文件路径的输入框），还有更改缩进和包装样式（编辑区域右上方)、查看更改预览的选项卡以及上面提交或取消更改的按钮。所有这些都如图4-11所示。
❗Editing with VS Code
GitHub最近增加了使用VS代码的一个版本通过浏览器编辑文件的功能。
要调用VS代码编辑器，只需在存储库中选择一个文件来显示其内容，然后按“”。
在你的键盘上。这将打开集成的教育。图4-12显示了一个示例。
这是一个更强大、功能更齐全的代码编辑器，尽管如果您还不习惯VS代码，它可能需要一些努力来弄清楚如何提交等等。
您还可以将URL的开头从github.com更改为github.dev来调用编辑器。
关于使用该集成的更多细节可以在相关的文档中找到。
为了显示编辑是如何工作的，我可以做一些简单的更改来改变这个工作流，使之有两个作业而不是一个作业。
首先，我将更改现有作业的描述和名称。这并不是严格必要的，但考虑到其他方面的改变，这是一个更好的选择：
# This workflow contains a single job called "build"build:
to:# This job checks out code from the repocheckout:
进一步向下，在第一步运行之前，我将添加几行，使剩余的步骤进入他们自己的工作。这就需要添加以下内容：
• A name for the job
• 一个run-on子句，用来说明在执行时使用什么类型的系统
• steps子句指示新作业的步骤启动位置
这些行从原始的第28行开始插入（带有注释）。当你这样做时，非常重要的是要非常小心地匹配预期的插入样式，因为这是YAML：
工作流的工作部分现在看起来如下所示：
您可以使用“预览”选项卡方便地查看此文件中更改的内容。图4-13显示了选择该选项卡后的代码显示。
现在，这些改变已经准备好要开始实施了。我只需点击提交更改按钮。所出现的对话框与以前相同。
这次，我将选择通过拉请求进行提交的选项。我将给新分支起一个patch-1。图4-14显示了已完成的对话框。
单击“建议更改”按钮后，将获得标准“打开拉请求”对话框，如图4-15所示。
在顶部的灰色条中，它已经被设置为比较patch-1分支和main分支。
它可以合并更改而不发生冲突。当准备好后，下一步只需单击创建拉出请求按钮。
创建拉请求后，GitHub将运行与存储库和分支相关联的任何预定义检查。
在这种情况下，运行的检查是由此分支中的拉请求触发的任何工作流中的作业。
这相当于刚刚在basic.yaml工作流文件中定义的checkout和 process jobs 。
您可以看到它们在初始处理拉请求时正在执行。
您还可以在单击所有检查已通过的右侧的显示所有检查链接行完成初始处理后看到它们。
图4-16显示了它们运行后的检查集。
单击每一行末尾的详细信息链接，您将被带到该运行的屏幕。
在图4-17中，您可以看到左侧列出的工作流中的作业和右侧的一个区域，该区域列出了对每个步骤执行时输出的作业需要执行的所有步骤。
这还包括由GitHub管理的隐式步骤，这是执行作业所需的步骤，比如 set up job。
每个步骤都可以进行扩展，以显示更多的细节。
在步骤中列出的一些行也可以展开以显示折叠的输出或执行细节。
（在第5章深入跑步者和第10章的debugging/troubleshooting排除中，会有更多的说明。）
❗Another Way to Get to the Details如果您选择存储库屏幕顶部的“`pull requests` ”选项卡，选择打开的拉请求，然后选择“`Checks`”选项卡，则可以看到相同的详细信息屏幕。（见图4-18。）
此workflow的最新运行在列表顶部的一行中。
单击提交消息更新basic.yaml切换视图以显示工作流中的作业列表，以及它们完成所需的时间以及它们是否成功。
在图4-20中，用带有 checkmarks 标记的圆圈表示成功。
单击此屏幕中作业的任何名称，您将进入步骤详细信息的视图。
这与您单击拉请求屏幕的检查部分中的详细信息链接时获得的视图相同。
在图4-20所示的屏幕右上方，您还可以看到重新运行所有作业的按钮。
旁边是一个按钮，它可以通过扩展来指导您创建一个status badge ，以及一个 delete logs 的选项。
（第56页上的“Creating a Status Badge”解释了更多关于创建状态徽章的内容。）
❗Creating a Status Badge要指示工作流的状态（pass/fail），您可以在存储库的任何网页中显示一个徽章。
徽章通常显示在README.md文件中。
您可以自己为 `Create Status Badge` 选项，或者GitHub可以通过创建状态徽章选项帮助您使用此标记。
如图4-21所示，您可以选择状态徽章的分支和触发事件。
对话框提供一个按钮，用于在选择后复制生成的标记代码。
然后，就可以简单地将其粘贴到自述文件中，以便在存储库中显示。
图4-22显示了我在本章中使用的简单工作流程的一个徽章示例。
这个徽章也可以作为一个捷径。单击显示的徽章将直接进入工作流的运行列表。
关于状态徽章代码的其他语法示例可以在GitHub文档中找到。
现在所有合并前检查已经完成，您就准备好合并代码并完成拉请求了。
❗Getting Back to the Pull Request通过选择顶级菜单（以<>Code开头的行），然后从显示的列表中选择拉请求，您可以轻松地返回到拉请求。
或者您可以简单地使用GitHub项目的URL，以pull/1结尾（假设这是存储库中的第一个pull请求）。
要完成合并，请单击合并拉请求按钮，然后单击下一个按钮，确认合并。
然后您将看到通常的对话框，拉请求已经合并并关闭（如果需要，可以删除分支）。
此时，如果您单击顶部的操作菜单，您将能够查看由拉请求的工作流（图4-23）生成的最新运行的工作流以及自动生成的提交消息。
在离开这个屏幕之前，这里还有其他一些值得注意的次要功能。
在任何运行的行中，您可以选择……在最后删除运行或直接转到工作流文件（图4-24)。
此外，在运行列表的顶部还有过滤选项。
您可以选择其中一个的下拉列表，并过滤器只查看与您的选择匹配的运行。
图4-25显示了过滤刚刚完成的pull请求中使用的patch-1分支的运行列表。
Using the VS Code GitHub Actions Extension
如果您更愿意在IDE中工作，则有一个GitHub操作扩展，允许您创建和编辑工作流，以及管理和监视运行。
它包括诸如衬里和代码完成等功能，并由GitHub正式支持。（扩建部分最初是一个社区项目，主要用于监控。）
如果您熟悉VS代码，您可以通过在VS代码IDE中搜索操作（图4-26）或通过VS代码GitHub操作扩展链接轻松地安装扩展。
然后，您可以选择一个存储库，并在VS代码中克隆它。
在某个时候，您将被要求登录到GitHub，并被提示允许扩展访问您的Git- Hub存储库（图4-27）。
在安装和授权后，您将在GitHub操作的VS代码中获得一个新的视图。
如果您的存储库中已经有了工作流和工作流的运行，则该视图将显示它们（图4-28)。
在工作流列表中，选择按其编号运行的工作流会导致右侧显示一个全局图标。单击全局图标允许您在标准操作界面中打开在浏览器中运行的工作流。同样地，在列表中选择一个作业会导致在右侧出现一个列表图标。选择该选项，您可以查看与该作业关联的日志（图4-29)。
如果您查看日志，资源管理器视图提供一个轮廓部分，可以单击以更轻松地移动到日志中的特定点（图4-30)。
该扩展还可以理解工作流模式，并可以在创建/编辑工作流文件时提供上下文底盘功能。
例如，如果您将鼠标悬停在一个关键字上，则可以获得包含有关上下文的有用信息的弹出窗口（图4-31)。
在创建/编辑工作流文件时，扩展名将通知您语法问题（图4-32)。
其他不错的特性包括，当它可以确定 available（可用）选项集时，代码完成（图4-33），以及通过悬停在工作流中的uses语句上获得操作代码的快速链接（图4-34）。
Conclusion
在本章中，我已经介绍了用于处理操作和工作流的GitHub web界面。
所提供的功能允许您轻松地创建和编辑工作流，而不必离开浏览器。
您还可以执行工作流，并查看每次运行的情况。
我们存储了以前的运行，以便您可以查看它们。
GitHub操作提供了一组启动程序和参考工作流，使创建初始工作流更容易。
GitHub将查看存储库中的任何现有代码，并在可能的情况下对有用的初始工作流提出建议。
当您需要一个新的存储库的工作流时，启动器和参考工作流是一个很好的开始。
执行工作流可以响应标准GitHub事件触发，但如果为工作流调度设置，也可以手动触发。
执行后，GitHub记录有关运行的信息，您可以深入到运行记录，查看实际发生了什么，并获得细节，例如最终在运行系统上完成的命令。
编辑工作流可以完全使用浏览器来完成，也可以通过VS代码集成来完成。
更改可以直接提交到当前分支，也可以通过拉请求合并。
当通过拉请求完成时，匹配事件的任何工作流都将被触发，并作为预检查运行，以在合并之前验证更改。
下一章将更多地介绍执行工作流的系统，也称为运行器。
