GitHub Actions Design Guidelines

Folder Structure

# Dev Dependencies for VS Code intellisense in github-script JS files
.github/package[-lock].json

# Composite Actions (preferred option for code reuse)
.github/actions/do-something/action.yaml
.github/actions/do-something/action.js (if using `github-script`, but prefer declarative YAML when possible)
.github/actions/util.js (code shared between actions)

# Workflows
.github/workflows/test-something.yaml
.github/workflows/test-something.js (if using `github-script`, but prefer declarative YAML or composite actions)
.github/workflows/util.js (code shared between workflows)

# Shared JS Libraries
.github/scripts/util.js (code shared between actions and workflows)

VS Code

Extensions

• GitHub Actions
• ESLint
• Prettier
• YAML

Install dev dependencies

For VS Code intellisense and tools:

1. cd .github
2. npm ci

YAML

Docs

• YAML syntax for Workflows - Files under .github/workflows
• YAML syntax for Actions - Files under .github/actions

Guidelines

• Workflows and Actions should use the .yaml file extension (not .yml)
• Less is more, but make things nice
  • Don't set a property (like id or shell) unless it's useful
  • Do set a property (like name) if (and only if) it improves the log UI
• Sort properties approximately in the order listed in the documents above (and/or align with examples in GitHub docs)
• Log as much as you can, but within reason
  • Do log anything you think might be useful to debug a problem in the future
  • Don't log anything verbose, unless it's useful
  • Consider grouping log chunks to improve UI
  • Use debug when appropriate for verbose logs, but remember it's only useful for repros (not the original failure)
• Before merging, run "Format Document" (will be enforced in the future)

Security

• Security hardening for GitHub Actions
  • Using CODEOWNERS to monitor changes
  • Understanding the risk of script injections
  • Good practices for mitigating script injection attacks
• Keeping your GitHub Actions and workflows secure: Preventing pwn requests
• Trigger pull_request has a read-only GITHUB_TOKEN
  • Should be used whenever possible, like to run a test and return pass/fail
• Triggers like pull_request_target and workflow_completed have read-write GITHUB_TOKEN
  • You must never do anything that could execute untrusted code from a fork PR
  • Safest option is to never clone the PR source branch at all
  • Perform most of the work in a safe pull_request trigger, then use a workflow_completed trigger to execute the privileged tasks (e.g. adding a label) based on artifacts published by the first workflow
  • If you must clone the PR source branch, it can only be treated as text, never executed
• Don't log anything that might leak secrets
  • GitHub has some built-in protections (e.g. masking secrets), but treat them as defense-in-depth

Suggestions

• Use workflow_dispatch wherever you can
  • Manually triggering a pipeline can make testing/debugging easier
  • Beware the different context objects available to the pipeline and don't couple to a specific one
• Naming jobs in a matrix
  • Matrix UI improvements
• Composite Actions behavior is different from DevOps templates

JS

Guidelines

• Code is written in JavaScript instead of TypeScript
  • Significantly improves startup time
  • Recommended by github-script action
  • Encourages us to keep our code simple
  • With type checking and intellisense, the editing experience is similar

Type Checking

• All JS files should start with header // @ts-check to enable type checking
• Functions called from github-script should start with the following, to set the argument types:

/**
 * @param {import('github-script').AsyncFunctionArguments} AsyncFunctionArguments
 */
module.exports = async ({ github, context, core }) => {

• Additional type declarations can be added via JSDoc comments

const payload =
  /** @type {import("@octokit/webhooks-types").WorkflowRunCompletedEvent} */ (
    context.payload
  );

PowerShell

• Error logging in pwsh
  • To $ErrorActionPreference and Write-Error or not to $ErrorActionPreference and Write-Host?