github-helpers

A collection of Github Actions that simplify and standardize common CI/CD workflow tasks.

Usage

General

uses: ExpediaGroup/github-helpers@v1
with:
  helper: < HELPER NAME >
  ...
  github_token: ${{ secrets.GITHUB_TOKEN }}

The helper and github_token inputs are required for all helpers. Additional inputs vary by helper. Each helper file in src/helpers contains an interface that defines which additional inputs are required or optional. If a required input is ommitted, the helper will throw a descriptive error.

Example

Input interface in src/helpers/set-commit-status.ts:

export class SetCommitStatus {
    sha = ''; // required
    context = ''; // required
    state = ''; // required
    description?: string; // optional
    target_url?: string; // optional
}

Github Actions workflow invocation:

uses: ExpediaGroup/github-helpers@v1
with:
  helper: set-commit-status
  sha: ${{ github.event.pull_request.head.sha }}
  context: My Context
  state: success
  description: My Description
  github_token: ${{ secrets.GITHUB_TOKEN }}

Available Helpers

Each of the following helpers are defined in a file of the same name in src/helpers:

add-labels

Adds one or more labels to a PR

add-pr-approval-label

Upon PR review, adds a CORE APPROVED label if the reviewer is a part of the provided Github team, otherwise adds the PEER APPROVED label

approve-pr

Approves a PR

assign-pr-reviewers

Randomly assigns members of a github team to review a PR. If login is provided, it does nothing if that user is already part of the team
You can also pass a slack_webhook_url to notify the assignees that they are assigned to the PR!

create-pr

Opens a pull request

create-project-card

Creates a Project card into your GitHub Project repository by providing a project_name and project_destination_column_name in which the card should be created.
If note is provided, it will add that information into the card. If it is not provided, it will use the PR information details to populate it.
Useful when opening a pull request and want to track its information details into a GitHub Project.

check-pr-title

Checks whether PR title matches a certain regular expression

create-pr-comment

Comments on a pull request or other issue

delete-deployment

Deletes a Github deployment and environment

filter-paths

Returns true if specified file paths have changed for a PR, and false otherwise

generate-path-matrix

Returns a job matrix JSON for dynamically running workflows only for changed file paths
Can be used to parallelize similar jobs, which can be useful in a monorepo environment. More information on matrix strategies can be found here
In this example, a multi-package repo splits its builds dynamically based on which packages are modified in the pull request. These builds run in parallel, and the final build-status job is used to determine the overall success/failure result, contingent on all of the individual build jobs passing. The helper returns a JSON object of this format:

{
  "include": [
    { "path": "package-name" }
  ]
}

Additionally, the following parameters can be used for additional control over the resulting matrix:

override_filter_paths defines paths that, if modified, will override the filter and return a matrix including all packages
- example: override_filter_paths: package.json,package-lock.json
paths_no_filter defines paths that should be included in the matrix regardless of if they've been modified
batches defines a fixed number of matrix jobs to run for the workflow

get-changed-files

Returns a comma-separated list of changed files for a PR

initiate-deployment

Creates a new in-progress Github "deployment" for a commit. More information on Github deployment events can be found here

manage-merge-queue

Manages a queue for PRs as follows:
- Adding the READY TO MERGE label to a PR will add the PR to the "merge queue", represented by a QUEUED FOR MERGE #X label. Removing READY TO MERGE will remove this label and thus remove the PR from the queue.
- If a PR is first in the queue, the QUEUE CHECKER commit status will be set to success, and it will be pending otherwise. Github's branch protection rules can be used to ensure this requirement is met prior to merging.
- Merging a PR will update the positions of all PRs in the queue.
- Adding the JUMP THE QUEUE label to a PR will make that PR first in the queue immediately.
- When a PR is merged, it automatically updates the first-queued PR with the default branch.
You can also pass login and slack_webhook_url to notify the PR author when they are in the 1st position of the merge queue.

move-project-card

Moves a GitHub Project card to a new column, using the project_origin_column_name andproject_destination_column_name you provide.
In order to move a card from one place to another, it must already exist.

notify-pipeline-complete

Sets a "pipeline" commit status to green for all open PRs

prepare-queued-pr-for-merge

Merges the default branch into the pull request that has the QUEUED FOR MERGE #1 label

remove-label

Removes a label from a PR

remove-pr-from-merge-queue

Removes a PR from the merge queue if it has a stale failing status check. A PR check is considered stale if it is older than the provided number of seconds.

rerun-pr-checks

Reruns all of the latest workflow checks on a pull request (helpful if they were cancelled for some reason, either manually or due to rate limiting, for example).

set-commit-status

Sets a commit status

set-deployment-status

Updates a Github deployment status

set-latest-pipeline-status

Determines whether the pipeline is clear for a PR. This means it will set the "pipeline" commit status to pending if there is an in-progress production deployment for the repo, and success otherwise.

Legal

This project is available under the Apache 2.0 License.

cryptozenci / github-helpers