github pages_如何使用GitHub Actions和Pages发布GitHub事件数据

github pages

Teams who work on GitHub rely on event data to collaborate.  The data recorded as issues, pull requests, and comments become vital to understanding the project.

在GitHub上工作的团队依靠事件数据进行协作。 记录为问题，请求和注释的数据对于理解项目至关重要。

With the general availability of GitHub Actions, we have a chance to programmatically access and preserve GitHub event data in our repository. Making the data part of the repository itself is a way of preserving it outside of GitHub. It also gives us the ability to feature the data on a front-facing website, such as with GitHub Pages.

有了GitHub Actions的普遍可用性，我们就有机会以编程方式访问并在我们的存储库中保存GitHub事件数据。 使数据成为存储库本身的一部分是将其保存在GitHub之外的一种方法。 它还使我们能够在前端网站(例如GitHub Pages)上显示数据。

And, if you’re like me, you can turn GitHub issue comments into an awesome 90s guestbook page.

而且，如果您像我一样，可以将GitHub问题评论变成一个很棒的90年代留言簿页面 。

No matter the usage, the principle concepts are the same. We can use Actions to access, preserve, and display GitHub event data - with just one workflow file. To illustrate the process, I’ll take you through the workflow code that makes my guestbook shine on.

无论用法如何，其原理都是相同的。 我们可以使用Actions来访问，保留和显示GitHub事件数据-只需一个工作流文件。 为了说明该过程，我将带您浏览使我的留言簿更加生动的工作流代码 。

For an introductory look at GitHub Actions including how workflows are triggered, see A lightweight, tool-agnostic CI/CD flow with GitHub Actions.

有关GitHub Actions(包括如何触发工作流)的入门介绍，请参阅GitHub Actions中的工具无关的轻量级CI / CD流 。

访问GitHub事件数据 (Accessing GitHub event data)

An Action workflow runs in an environment with some default environment variables. A lot of convenient information is available here, including event data. The most complete way to access the event data is using the $GITHUB_EVENT_PATH variable, the path of the file with the complete JSON event payload.

Action工作流在具有某些默认环境变量的环境中运行。 此处提供了许多方便的信息，包括事件数据。 访问事件数据的最完整方法是使用$GITHUB_EVENT_PATH变量，即带有完整JSON事件有效负载的文件路径。

The expanded path looks like /home/runner/work/_temp/_github_workflow/event.json and its data corresponds to its webhook event. You can find the documentation for webhook event data in GitHub REST API Event Types and Payloads. To make the JSON data available in the workflow environment, you can use a tool like jq to parse the event data and put it in an environment variable.

扩展路径类似于/home/runner/work/_temp/_github_workflow/event.json ，其数据对应于其webhook事件。 您可以在GitHub REST API 事件类型和有效负载中找到webhook事件数据的文档。 要使JSON数据在工作流环境中可用，您可以使用jq类的工具来解析事件数据并将其放入环境变量中。

Below, I grab the comment ID from an issue comment event:

下面，我从问题评论事件中获取评论ID：

ID="$(jq '.comment.id' $GITHUB_EVENT_PATH)"

Most event data is also available via the github.event context variable without needing to parse JSON. The fields are accessed using dot notation, as in the example below where I grab the same comment ID:

大多数事件数据也可以通过github.event上下文变量获得，而无需解析JSON。 可以使用点表示法来访问这些字段，如下面的示例所示，其中我获取了相同的注释ID：

ID=${{ github.event.comment.id }}

For my guestbook, I want to display entries with the user’s handle, and the date and time. I can capture this event data like so:

对于我的留言簿，我想显示带有用户句柄以及日期和时间的条目。 我可以像这样捕获此事件数据：

AUTHOR=${{ github.event.comment.user.login }}
DATE=${{ github.event.comment.created_at }}

Shell variables are handy for accessing data, however, they’re ephemeral. The workflow environment is created anew each run, and even shell variables set in one step do not persist to other steps. To persist the captured data, you have two options: use artifacts, or commit it to the repository.

Shell变量很容易访问数据，但是它们是短暂的。 每次运行都会重新创建工作流环境，甚至在一个步骤中设置的Shell变量也不会保留到其他步骤。 要持久保存捕获的数据，您有两个选择：使用构件，或将其提交到存储库。

保留事件数据：使用工件 (Preserving event data: using artifacts)

Using artifacts, you can persist data between workflow jobs without committing it to your repository. This is handy when, for example, you wish to transform or incorporate the data before putting it somewhere more permanent. It’s necessary to persist data between workflow jobs because:

使用工件，您可以在工作流作业之间保留数据，而无需将其提交到存储库。 例如，当您希望在将数据放置到更永久的位置之前进行转换或合并时，这非常方便。 有必要在工作流作业之间保留数据，因为：

Each job in a workflow runs in a fresh instance of the virtual environment. When the job completes, the runner terminates and deletes the instance of the virtual environment. (Persisting workflow data using artifacts)

工作流中的每个作业都在虚拟环境的新实例中运行。 作业完成后，运行程序终止并删除虚拟环境的实例。 ( 使用工件保留工作流数据 )

Two actions assist with using artifacts: upload-artifact and download-artifact. You can use these actions to make files available to other jobs in the same workflow. For a full example, see passing data between jobs in a workflow.

有两种操作可帮助使用工件： upload-artifact和download-artifact 。 您可以使用这些操作使文件可用于同一工作流程中的其他作业。 有关完整示例，请参见工作流中作业之间的数据传递 。

The upload-artifact action’s action.yml contains an explanation of the keywords. The uploaded files are saved in .zip format. Another job in the same workflow run can use the download-artifact action to utilize the data in another step.

upload-artifact操作的action.yml包含关键字的说明 。 上载的文件以.zip格式保存。 同一工作流运行中的另一个作业可以在另一个步骤中使用download-artifact操作来利用数据。

You can also manually download the archive on the workflow run page, under the repository’s Actions tab.

您也可以在工作流运行页面上，在存储库的“操作”选项卡下手动下载存档。

Persisting workflow data between jobs does not make any changes to the repository files, as the artifacts generated live only in the workflow environment.

在作业之间保留工作流数据不会对存储库文件进行任何更改，因为生成的工件仅在工作流环境中有效。

Personally, being comfortable working in a shell  environment, I see a narrow use case for artifacts, though I’d have been remiss not to mention them. Besides passing data between jobs, they could be useful for creating .zip format archives of, say, test output data. In the case of my guestbook example, I simply ran all  the necessary steps in one job, negating any need for passing data  between jobs.

就个人而言，在外壳环境中工作自如，我看到了工件的狭窄用例，尽管我一直不愿提及它们。 除了在作业之间传递数据外，它们对于创建.zip格式的存档(例如测试输出数据)很有用。 就我的留言簿示例而言，我只需在一个作业中运行所有必要的步骤，而无需在作业之间传递数据。

保留事件数据：将工作流文件推送到存储库 (Preserving event data: pushing workflow files to the repository)

To preserve data captured in the workflow in the repository itself, it is necessary to add and push this data to the Git repository. You can do this in the workflow by creating new files with the data, or by appending data to existing files, using shell commands.

为了将工作流程中捕获的数据保留在存储库本身中，有必要将这些数据添加并推送到Git存储库中。 您可以在工作流中通过使用数据创建新文件或使用Shell命令将数据附加到现有文件中来完成此操作。

在工作流程中创建文件 (Creating files in the workflow)

To work with the repository files in the workflow, use the checkout action to first get a copy to work with:

要在工作流中使用存储库文件，请使用checkout操作首先获取要使用的副本：

- uses: actions/checkout@master
  with:
    fetch-depth: 1

To add comments to my guestbook, I turn the event data captured in shell variables into proper files, using substitutions in shell parameter expansion to sanitize user input and translate newlines to paragraphs. I wrote previously about why user input should be treated carefully.

要将注释添加到我的留言簿中，我将在shell变量中捕获的事件数据转换为适当的文件，使用shell参数扩展中的替换项来清理用户输入并将换行符转换为段落。 之前，我写过关于为什么应谨慎对待用户输入的文章 。

- name: Turn comment into file
  run: |
    ID=${{ github.event.comment.id }}
    AUTHOR=${{ github.event.comment.user.login }}
    DATE=${{ github.event.comment.created_at }}
    COMMENT=$(echo "${{ github.event.comment.body }}")
    NO_TAGS=${COMMENT//[<>]/\`}
    FOLDER=comments

    printf '%b\n' "<div class=\"comment\"><p>${AUTHOR} says:</p><p>${NO_TAGS//$'\n'/\<\/p\>\<p\>}</p><p>${DATE}</p></div>\r\n" > ${FOLDER}/${ID}.html

By using printf and directing its output with > to a new file, the event data is transformed into an HTML file, named with the comment ID number, that contains the captured event data. Formatted, it looks like:

通过使用printf并将其输出带有>定向到新文件，事件数据将转换为HTML文件，该文件以注释ID号命名，其中包含捕获的事件数据。 格式化后，它看起来像：

<div class="comment">
  <p>victoriadrake says:</p>
  <p>This is a comment!</p>
  <p>2019-11-04T00:28:36Z</p>
</div>

When working with comments, one effect of naming files using the comment ID is that a new file with the same ID will overwrite the previous. This is handy for a guestbook, as it allows any edits to a comment to replace the original comment file.

使用注释时，使用注释ID命名文件的一个效果是，具有相同ID的新文件将覆盖前一个文件。 这对于留言簿非常方便，因为它允许对注释的任何编辑来替换原始注释文件。

If you’re using a static site generator like Hugo, you could build a Markdown format file, stick it in your content/ folder, and the regular site build will take care of the rest.

如果您使用的是Hugo之类的静态网站生成器，则可以构建Markdown格式的文件，并将其粘贴在content/文件夹中，其余的工作将由常规网站进行。

In the case of my simplistic guestbook, I have an extra step to consolidate the  individual comment files into a page. Each time it runs, it overwrites the existing index.html with the header.html portion (>), then finds and appends (>>) all the comment files’ contents in descending order, and lastly appends the footer.html portion to end the page.

对于我的简单留言簿，我还有一个额外的步骤将单个注释文件整合到页面中。 每次运行时，它都会用header.html部分( > )覆盖现有的index.html ，然后以降序查找并附加( >> )所有注释文件的内容，最后将footer.html部分附加到末尾。这一页。

- name: Assemble page
  run: |
    cat header.html > index.html
    find comments/ -name "*.html" | sort -r | xargs -I % cat % >> index.html
    cat footer.html >> index.html

提交对存储库的更改 (Committing changes to the repository)

Since the checkout action is not quite the same as cloning the repository, at time of writing, there are some issues still to work around. A couple extra steps are necessary to pull, checkout, and successfully push changes back to the master branch, but this is pretty trivially done in the shell.

由于checkout操作与克隆存储库不太一样，因此在撰写本文时，仍有一些问题需要解决。 需要几个额外的步骤才能pull ， checkout和成功地push更改push回master分支，但这在shell中非常简单。

Below is the step that adds, commits, and pushes changes made by the workflow back to the repository’s master branch.

以下是添加，提交并将工作流所做的更改推回存储库的master分支的步骤。

- name: Push changes to repo
  run: |
    REMOTE=https://${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}
    git config user.email "${{ github.actor }}@users.noreply.github.com"
    git config user.name "${{ github.actor }}"

    git pull ${REMOTE}
    git checkout master
    git add .
    git status
    git commit -am "Add new comment"
    git push ${REMOTE} master

The remote, in fact, our repository, is specified using the github.repository context variable. For our workflow to be allowed to push to master, we use the secrets.GITHUB_TOKEN variable.

远程，实际上是我们的存储库，是使用github.repository上下文变量指定的。 为了使我们的工作流程能够掌握，我们使用secrets.GITHUB_TOKEN变量。

Since the workflow environment is shiny and newborn, we need to configure Git. In the above example, I’ve used the github.actor context variable to input the username of the account initiating the workflow. The email is similarly configured using the default noreply GitHub email address.

由于工作流环境充满生机和新生，我们需要配置Git。 在上面的示例中，我使用了github.actor上下文变量来输入启动工作流程的帐户的用户名。 使用默认的noreply GitHub电子邮件地址类似地配置电子邮件 。

显示事件数据 (Displaying event data)

Nov 6, 2019 correction: GitHub Actions requires a Personal Access Token to trigger a Pages site build.

2019年11月6日更正：GitHub Actions需要一个Personal Access Token来触发Pages网站构建。

If you're using GitHub Pages with the default secrets.GITHUB_TOKEN variable and without a site generator, pushing changes to the  repository in the workflow will only update the repository files. The  GitHub Pages build will fail with an error, "Your site is having  problems building: Page build failed."

如果您使用具有默认secrets.GITHUB_TOKEN变量且没有网站生成器的GitHub Pages，则将更改推送到工作流中的存储库只会更新存储库文件。 GitHub Pages构建将失败，并显示错误：“您的网站构建存在问题：页面构建失败。”

To enable Actions to trigger a Pages site build, you'll need to create a Personal Access Token. This token can be stored as a secret in the repository settings and passed into the workflow in place of the default secrets.GITHUB_TOKEN variable. I wrote more about Actions environment and variables in this post.

要使操作能够触发Pages网站构建，您需要创建一个个人访问令牌。 该令牌可以作为机密存储在存储库设置中，并代替默认的secrets.GITHUB_TOKEN变量传递到工作流中。 我在这篇文章中写了更多有关Actions环境和变量的文章 。

With the use of a Personal Access Token, a push initiated by the  Actions workflow will also update the Pages site. You can see it for  yourself by leaving a comment in my guestbook!  The comment creation event triggers the workflow, which then takes  around 30 seconds to a minute to run and update the guestbook page.

通过使用个人访问令牌，由“动作”工作流启动的推送也将更新“页面”站点。 您可以在留言簿中 留下评论 ，亲自查看！ 注释创建事件触发工作流程，然后运行大约30秒到一分钟来运行和更新留言簿页面。

Where a site build is necessary for changes to be published, such as  when using Hugo, an Action can do this too. However, in order to avoid  creating unintended loops, one Action workflow will not trigger another. Instead, it's extremely convenient to handle the process of building the site with a Makefile,  which any workflow can then run. Simply add running the Makefile as the  final step in your workflow job, with the repository token where  necessary:

在需要发布网站更改才能发布的地方(例如使用Hugo时)，Action也可以这样做。 但是，为了避免创建意外的循环， 一个Action工作流程将不会触发另一个 。 取而代之的是， 使用Makefile处理构建网站的过程非常方便，然后任何工作流都可以运行该文件 。 只需添加运行Makefile作为工作流程工作的最后一步，并在必要时添加存储库令牌：

- name: Run Makefile
  env:
    TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: make all

This ensures that the final step of your workflow builds and deploys the updated site.

这样可以确保工作流程的最后一步可以构建和部署更新的站点。

不再有事件数据范围 (No more event data horizon)

GitHub Actions provides a neat way to capture and utilize event data so that it’s not only available within GitHub. The possibilities are only as limited as your imagination! Here are a few ideas for things this lets us create:

GitHub Actions提供了一种捕获和利用事件数据的巧妙方法，因此不仅在GitHub中可用。 可能性只限于您的想象！ 以下是一些让我们创建的东西的想法：

1. A public-facing issues board, where customers without GitHub accounts can view and give feedback on project issues.
   一个面向公众的问题委员会，没有GitHub帐户的客户可以在其中查看项目问题并提供反馈。
2. An automatically-updating RSS feed of new issues, comments, or PRs for any repository.
   自动更新任何存储库的新问题，评论或PR的RSS feed。
3. A comments system for static sites, utilizing GitHub issue comments as an input method.
   用于静态站点的评论系统，利用GitHub发布评论作为输入方法。
4. An awesome 90s guestbook page.
   很棒的90年代留言簿页面。

Did I mention I made a 90s guestbook page? My inner-Geocities-nerd is a little excited.

我是否提到我做了90年代的留言簿页面 ？ 我内心的地质书呆子有点兴奋。

翻译自: https://www.freecodecamp.org/news/publishing-github-event-data-with-github-actions-and-pages/

github pages