GitHub Actions Toolkit

Problem matchers allow the runner to scan build output and automatically surface errors or warnings. Use ::add-matcher with a path to a .json file to register one, or ::remove-matcher to remove one by its owner.

echo "::add-matcher::eslint-compact-problem-matcher.json"
echo "::remove-matcher owner=eslint-compact::"

Create collapsible regions in the GitHub Actions log UI by wrapping log output with ::group:: and ::endgroup:: commands.

This is wrapped by the @actions/core methods startGroup(name: string): void and endGroup(): void.

echo "::group::my title"
# ... log lines ...
echo "::endgroup::"

If a tool is not available in the system's PATH, you can execute it by providing its absolute or relative file path as the first argument to exec.exec().

const exec = require('@actions/exec');

await exec.exec('"/path/to/my-tool"', ['arg1']);

The execution logic for a Docker action is contained within the entrypoint script, typically named entrypoint.sh. This script is executed when the container starts. Arguments passed from the runs.args section in the metadata are available to this script as positional parameters (e.g., $1, $2).

#!/bin/sh -l

echo "hello $1"

When using GitHub Actions workflows, ensure that the versions of actions/upload-artifact and actions/download-artifact are compatible. They both rely on the GitHub Actions toolkit.

Compatibility Matrix:

Example workflow usage:

  uses: actions/upload-artifact@v4
  # ...
  uses: actions/download-artifact@v4
  # ...

Configure your action's identity and inputs in the action metadata file (typically action.yml). You must define the name, description, and specify that it runs using docker.

Inputs defined in the metadata are made available to workflow authors via the with: keyword. In a Docker action, these inputs are typically passed to the container via the args field in the runs section.

name: 'My Container Action'
description: 'Get started with Container actions'
author: 'GitHub'
inputs: 
  myInput:
    description: 'Input to use'
    default: 'world'
runs:
  using: 'docker'
  image: 'Dockerfile'
  args:
    - ${{ inputs.myInput }}

To ensure GitHub Actions work correctly behind a proxy server on self-hosted runners, follow these requirements:

1. Requirement: Use @actions/tool-cache version 1.3.1 or higher.
2. Recommendation: Use @actions/http-client for HTTP requests, as it is designed to work with proxy configurations.

If you are using other HTTP clients, you must configure them using the environment variables provided by the GitHub Actions runner.

To get full TypeScript type safety for webhook payloads, install @octokit/webhooks-definitions and cast the github.context.payload based on the github.context.eventName.

// 1. Install the definitions: npm install @octokit/webhooks-definitions

import * as core from '@actions/core'
import * as github from '@actions/github'
import {PushEvent} from '@octokit/webhooks-definitions/schema'

if (github.context.eventName === 'push') {
  // Cast the payload to the specific event type
  const pushPayload = github.context.payload as PushEvent
  core.info(`The head commit is: ${pushPayload.head_commit}`)
}

Use @actions/glob to find files matching specific glob patterns. You can provide relative paths (rooted against the current working directory) or absolute paths. Use glob.create(patterns) to initialize a globber and globber.glob() to retrieve the list of files.

const glob = require('@actions/glob');

const patterns = ['**/tar.gz', '**/tar.bz']
const globber = await glob.create(patterns.join('\n'))
const files = await globber.glob()