GitHub Actions Cheat Sheet

README.md

⚠️ OUTDATED ⚠️

GitHub's documentation has caught up with the provided features and became a lot better: https://docs.github.com/en/actions

GitHub Actions Cheat Sheet

Table of Contents

• Table of Contents
• Helpful GitHub pages
• action.yml
• General
• Filesystem
• Getting information
  • Inputs
  • Environment variables
  • Secrets
  • Event payload
• Logging commands

Helpful GitHub pages

• Triggers
• Contexts and Expressions

action.yml

Reference: https://help.github.com/en/articles/metadata-syntax-for-github-actions

# Required, string. Name of the action.
name: 'My Action'
# Optional, string. Name of the action's author.
author: 'John Doe'
# Required, string. Short description of the action.
description: 'Does something special'

# Optional. Allows you to specify data that the action expects during runtime.
# See Getting information > Inputs for how to retrieve them.
inputs: # see below

# Optional. Allows you to specify data that subsequent actions can use later in the workflow.
outputs: # see below

# Required. Command to run when the action executes.
runs: # see below

# Optional? Color and Feather icon to create a badge visible in GitHub Marketplace.
branding: # see below

inputs

# Required. (Unique) ID of the input; lowercase recommended.
# RegEx: [A-Za-z_][A-Za-z0-9_-]*
repo-token:
  # Required, string. Description of the input.
  description: 'The GITHUB_TOKEN secret'
  # Required, bool. Whether this input is required.
  required: true
  # Optional, string. Default value when input isn't specified in a workflow.
  default: 'xxx'

outputs

# Required. (Unique) ID of the output; lowercase recommended.
# RegEx: [A-Za-z_][A-Za-z0-9_-]*
answer-to-everything:
  # Required, string. Description of the output.
  description: 'The answer to life, the universe and everything'

runs

• Creating a Docker Action

# Required. Application to use to execute code specified in main.
using: 'node12'  # e.g. node12, docker
# Optional, map. Key/value map of environment variables for the virtual environment.
env:
  test: false

# Only for JS actions:
# Required. Code file with your action code. The application specified in 'using' will execute this file.
main: 'lib/main.js'

# Only for container actions:
# Required, string. Docker image to use as the container to run the action.
# The application specified with the using syntax will execute this file.
# Examples:
# - 'Dockerfile' (Dockerfile in repo, relative to repo root)
# - 'docker://debian:stretch-slim' (Docker registry container)
# - 'actions/container-template@master' (Docker container on GitHub)
image: 'Dockerfile'
# Optional. Sets/overrides ENTRYPOINT in the Dockerfile. If an action does not use the runs keyword, the commands in entrypoint will execute. 
# exec form recommended.
entrypoint:
# Optional, string[]. Strings that define the inputs for a Docker container.
# See https://help.github.com/en/articles/metadata-syntax-for-github-actions#args
args: ['${{ inputs.greeting }}', 'foo', 'bar']

branding

See https://developer.github.com/marketplace/actions

# Optional? Background color of the badge.
# Values: white, yellow, blue, green, orange, red, purple, gray-dark
color: purple
# Optional? Name of the Feather icon to use.
# See https://feathericons.com
icon: check

General

VMs and hardware resources: https://help.github.com/en/articles/virtual-environments-for-github-actions#supported-virtual-environments-and-hardware-resources

Filesystem

Source: https://help.github.com/en/actions/automating-your-workflow-with-github-actions/virtual-environments-for-github-hosted-runners#filesystems-on-github-hosted-runners

Getting information

Inputs

Environment variables

Reference: https://help.github.com/en/actions/automating-your-workflow-with-github-actions/using-environment-variables
JS implementation: https://github.com/actions/toolkit/blob/master/packages/github/src/context.ts

Name	Description	Example
HOME	Path to the GitHub home directory used to store user data.	/github/home
GITHUB_WORKFLOW	Name of the workflow.
GITHUB_ACTION	Unique ID of the action.
GITHUB_ACTOR	Name of the person or app that initiated the workflow.	octocat
GITHUB_REPOSITORY	Owner and repository name.	octocat/Hello-World
GITHUB_EVENT_NAME	Name of the webhook event that triggered the workflow.
GITHUB_EVENT_PATH	Path of the file with the complete webhook event payload.	/github/workflow/event.json
GITHUB_WORKSPACE	GitHub workspace directory path. Contains a subdirectory with a copy of your repository if your workflow uses the actions/checkout action. Empty otherwise.	/home/runner/work/my-repo-name/my-repo-name
GITHUB_SHA	Commit SHA that triggered the workflow.	ffac537e6cbbf934b08745a378932722df287a53
GITHUB_REF	Branch or tag ref that triggered the workflow. If neither is available for the event type, this variable will not exist.	refs/heads/feature-branch-1
GITHUB_HEAD_REF	The branch of the head repository. Only set for forked repositories.
GITHUB_BASE_REF	The branch of the base repository. Only set for forked repositories.

Note: GitHub reserves the GITHUB_ environment variable prefix for internal use by GitHub. Setting an environment variable or secret with the GITHUB_ prefix will result in an error.

Secrets

Reference: https://help.github.com/en/articles/virtual-environments-for-github-actions#creating-and-using-secrets-encrypted-variables

Event payload

Source: https://github.com/actions/toolkit/blob/master/packages/github/src/interfaces.ts

Logging commands

Reference: https://help.github.com/en/articles/development-tools-for-github-actions#logging-commands