damccorm commented on code in PR #27689:
URL: https://github.com/apache/beam/pull/27689#discussion_r1275384722
##########
.github/workflows/README.md:
##########
@@ -14,6 +14,87 @@
specific language governing permissions and limitations
under the License.
-->
+
+# Guidelines for Adding or Modifying Workflows
+
+On top of normal Actions workflow steps, all new CI workflows (excluding
release workflows or other workflow automation) should have the following:
+
+1) A set of specific triggers
+2) An explicit checkout step
+3) A set of GitHub token permissions
+4) Concurrency Groups
+5) Comment Triggering Support
+
+Each of these is described in more detail below.
+
+## Workflow triggers
+
+GitHub allows workflows to define a set of triggers that dictate when a job
should be run. For more info, see [documentation
here](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows).
+
+For the purposes of Beam, each CI workflow should define the following
triggers:
+
+1) A `push` trigger
+2) A `pull_request_target` trigger
+3) An issue_comment trigger (for issue created). This is needed for comment
triggering support (see section below).
+4) A scheduled trigger
+5) A workflow_dispatch trigger
+
+The `push`/`pull_request_target` triggers should only run when appropriate
paths are modified. See
https://github.com/apache/beam/blob/master/.github/workflows/beam_PreCommit_Go.yml#L4
for an example (you can copy and paste this into your workflow, you just need
to change the paths).
+
+## Checkout step
+
+Because we use the `pull_request_target` trigger instead of `pull_request`, we
need an explicit checkout of the correct commit. This can be done as the first
step of any jobs in your workflow. See
https://github.com/apache/beam/blob/907c5110163b0efe52e9e12127fd013c7fc455d7/.github/workflows/beam_PreCommit_Go.yml#L46
for an example (you can copy and paste this into your workflow).
+
+## Token Permissions
+
+You should explicitly define the GitHub Actions token scopes needed by your
job. For most jobs, this will be `actions: write` (needed for comment
triggering support) and `read` permissions for all other options. See
https://github.com/apache/beam/blob/907c5110163b0efe52e9e12127fd013c7fc455d7/.github/workflows/beam_PreCommit_Go.yml#L16
for an example (you can copy and paste this into your workflow).
+
+## Concurrency Groups
+
+Concurrency groups are a way of making sure that no more than one Actions run
is running per job/group at any given time (previous ones can be cancelled). To
reduce resource usage, you should define the following concurrency group:
+
+```
+concurrency:
+ group: '${{ github.workflow }} @ ${{ github.event.pull_request.head.label ||
github.sha || github.head_ref || github.ref }}-${{ github.event.sender.login
}}-${{ github.event.schedule }}'
+ cancel-in-progress: true
+```
+
+this defines the following groups:
Review Comment:
>> Is @ just a symbol in a string or it has a specific interpretation?
> It is just a symbol included by convention
Here's an example of how these are rendered (this one doesn't include the
schedule or username changes)
<img width="732" alt="image"
src="https://github.com/apache/beam/assets/42773683/001df584-971f-4f9e-a138-7ae73ccb7b38";>
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
