Skip to content

GitHub Actions Design Guidelines

Jump to bottom
Mike Harder edited this page Nov 7, 2024 · 26 revisions

Folder Structure

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

# Composite Actions (preferred option for complex tasks)
.github/actions/do-something/action.yaml
.github/actions/do-something/action.js (if using `github-script`)
.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 composite action for complex tasks)
.github/workflows/util.js (code shared between workflows)

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

VS Code

Extensions

Formatting

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)
  • Before merging, run "Format Document With...Prettier" (will be enforced in the future)

Naming jobs in a matrix

Matrix UI improvements

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.

Composite Actions behavior is different from DevOps templates

Error logging in pwsh

To $ErrorActionPreference and Write-Error or not to $ErrorActionPreference and Write-Host?

Clone this wiki locally