You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@beam.apache.org by da...@apache.org on 2022/09/12 13:32:47 UTC
[beam] branch master updated: Added documentation in ACTIONS.md file (#23159)
This is an automated email from the ASF dual-hosted git repository.
damccorm pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/beam.git
The following commit(s) were added to refs/heads/master by this push:
new 2113ffcac3f Added documentation in ACTIONS.md file (#23159)
2113ffcac3f is described below
commit 2113ffcac3fa3d7522ceb22d03919e6edafe5e90
Author: Daniela MartÃn <da...@gmail.com>
AuthorDate: Mon Sep 12 08:32:39 2022 -0500
Added documentation in ACTIONS.md file (#23159)
---
.github/ACTIONS.md | 73 +++++++++++++++++++++++++++++++++++++++++++++++++++---
1 file changed, 69 insertions(+), 4 deletions(-)
diff --git a/.github/ACTIONS.md b/.github/ACTIONS.md
index 57e84b5725d..43dbe0479d4 100644
--- a/.github/ACTIONS.md
+++ b/.github/ACTIONS.md
@@ -6,9 +6,7 @@
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
-
http://www.apache.org/licenses/LICENSE-2.0
-
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
@@ -17,10 +15,77 @@
under the License.
-->
-> **PLEASE update this file if you add new github action or change name/trigger phrase of a github action.**
+> **PLEASE update this file if you add new GitHub Action or change name/trigger phrase of a GitHub Action.**
+## About GitHub Actions Runners and Self-hosted Runners
+According to GitHub Docs, we can define a GitHub-hosted runner and a self-hosted runner as the following:
+* A [GitHub-hosted runner](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners) is a new virtual machine (VM) hosted by GitHub with the runner application and other tools preinstalled, and is available with Ubuntu Linux, Windows, or macOS operating systems.
+* A [self-hosted runner](https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners) is a system that you deploy and manage to execute jobs from GitHub Actions on GitHub.com.
+
+## Apache Beam GitHub Actions
+
+Currently, we have both GitHub-hosted and self-hosted runners for running the GitHub Actions workflows, hosted on Google Cloud Platform(GCP) Virtual Machines and Google Kubernetes Engine(GKE). The majority of our workflows that run in Ubuntu and Windows run in self-hosted runners, except for those that runs on MacOS and the `Monitor Self-Hosted Runners Status` workflow that monitors our GCP self-hosted runners.
+
+### Getting Started with self-hosted runners
+* Refer to [this README](./gh-actions-self-hosted-runners/README.md) for the steps for creating your own self-hosted runners for testing your workflows.
+* Depending on your workflow's needs, it must specify the following `runs-on` tags to run in the specified operating system:
+ * Ubuntu 20.04 self-hosted runner: `[self-hosted, ubuntu-20.04]`
+ * Windows Server 2019 self-hosted runner: `[self-hosted, windows-server-2019]`
+ * MacOS GitHub-hosted runner: `macos-latest`
+* Every workflow that tests the source code, needs to have the workflow trigger `pull_request_target` instead of `pull_request`.
+* The workflow must have set read permissions for all the available scopes and jobs: `permissions: read-all`. It must be set at the top of the `jobs` directive.
+* For those workflows that have the `pull_request_target` trigger, in the checkout step must be added a ref to `${{ github.event.pull_request.head.sha }}`
+``` yaml
+ - name: Checkout code
+ uses: actions/checkout@v#
+ with:
+ ref: ${{ github.event.pull_request.head.sha }}
+```
+* If your workflow runs successfully in a GitHub-hosted runner but not in the self-hosted runner, it might need a new installation step.
+```yaml
+ - name: Setup Node
+ uses: actions/setup-node@v3
+ with:
+ node-version: 16
+```
+* You can find the GitHub-hosted runner installations in the following links:
+ * [Ubuntu-20.04](https://github.com/actions/runner-images/blob/main/images/linux/Ubuntu2004-Readme.md#installed-apt-packages)
+ * [Windows-2019](https://github.com/actions/runner-images/blob/main/images/win/Windows2019-Readme.md)
-## Beam Github Actions
+#### GitHub Actions Example
+```yaml
+name: GitHub Actions Example
+on:
+ pull_request_target:
+ branches: ['master']
+permissions: read-all
+jobs:
+ github-actions-example:
+ runs-on: [self-hosted, ubuntu-20.04]
+ steps:
+ - name: Check out repository code
+ uses: actions/checkout@v2
+ with:
+ ref: ${{ github.event.pull_request.head.sha }}
+ - run: echo "This job is now running on a ubuntu server hosted by Apache Beam!"
+ - name: Setup Node
+ uses: actions/setup-node@v3
+ with:
+ node-version: 16
+ - name: Install npm dependencies
+ run: npm ci
+ working-directory: 'scripts/ci/your-path'
+ - name: Run Node.js code
+ run: npm run functionName
+ env:
+ VAR_1: my-var
+ working-directory: 'scripts/ci/your-path'
+```
+#### IMPORTANT for Committers
+* A **detailed review** for changes in the workflows is needed due to important **security concerns**.
+* **DO NOT** Approve and Run changes in the workflows in the PR Conversation tab, under "Workflow(s) awaiting approval".
+* For approving the updates in the workflows, you should go to the Repository Actions and filter All Workflows by `action_required`. The search will display the workflows that need to be reviewed before running. **Please make sure reviewing the file that is referenced by the workflow.**
+* Seed job will be emulated using the `Approve and Run` built-in feature of GitHub Actions, since the workflows will use the `pull_request_target` directive; no modifications would be allowed either for new or existent jobs unless a committer explicitly approves the job from GitHub Actions UI.
### Issue Management
Phrases self-assign, close, or manage labels on an issue: