README.md

Languages GitHub Actions

A set of custom GitHub Actions and reusable workflow used by the Languages Team.

• Workflows
  • Required Configuration
  • Buildpacks - Prepare Release
  • Buildpacks - Release
• Actions
  • Install Languages CLI
• Development

Workflows

Required Configuration

Before using the shared workflows below, please be sure to configure the following settings in your repository:

• Edit the branch protection rules on the default branch (e.g.; main). If Restrict who can push to matching branches and Restrict pushes that create matching branches is checked, then add the bot user of the GitHub Application that will be used to create pull requests and commits (e.g.; heroku-linguist).
• Configure PR merges to Allow auto-merge.

If either of these settings are misconfigured you will encounter errors during steps that create or configure pull requests. For example, an error message of "Pull request User is not authorized for this protected branch" indicates the branch protection rules are missing the GitHub Application bot user.

Buildpacks - Prepare Release

Prepares a buildpack release by:

• bumping the fixed version
• updating changelogs
• generating an aggregate changelog from all the changelogs
• opening a PR against the repository with the modified files

You can pin to:

• the latest release version with @latest
• a specific release version with @v{major}.{minor}.{patch}
• the development version with @main

Example Usage

name: Prepare Buildpack Releases

on:
  workflow_dispatch:
    inputs:
      bump:
        description: "Bump"
        required: true
        default: 'patch'
        type: choice
        options:
          - major
          - minor
          - patch

jobs:
  prepare-release:
    uses: heroku/languages-github-actions/.github/workflows/_buildpacks-prepare-release.yml@latest
    with:
      app_id: ${{ vars.GH_APP_ID }}
      bump: ${{ inputs.bump }}
    secrets:
      app_private_key: ${{ secrets.GH_APP_PRIVATE_KEY }}

Inputs

Name	Description	Required	Default
app_id	Application ID of GitHub application (e.g. the Linguist App)	true
bump	Which component of the version to increment (major, minor, or patch)	true
declarations_starting_version	Only needed if existing releases have been published but there is no matching release tag in Git. If this is the case, the first git tag that matches a version from your CHANGELOG should be supplied.	false
ip_allowlisted_runner	The GitHub Actions runner to use to run jobs that require IP allow-list privileges	false	pub-hk-ubuntu-24.04-ip
languages_cli_branch	The branch to install the Languages CLI from (FOR TESTING)	false	main

Secrets

Name	Description	Required
app_private_key	Private key of GitHub application (Linguist)	true

Buildpacks - Release

Performs the release steps for one or more buildpacks by:

• Detecting all the buildpacks in a repository and compiling them into Cloud Native Buildpacks
• For each compiled buildpack:
  • Creating a CNB archive file from the compiled buildpack and publishing it as a GitHub Release
  • Creating an OCI image from the compiled buildpack and publishing it to the Docker Hub repository specified in the buildpack's buildpack.toml

    The following metadata is used for declaring the registry:

    [metadata.release]
    image = { repository = "docker.io/heroku/buildpack-example" }

  • Retrieving the OCI image url published to Docker Hub and registering this with the CNB Registry
• Once all buildpacks have been published, all the buildpack references found in heroku/cnb-builder-images are updated for the given list of builders and a pull request is opened containing all the changes to be committed.

You can pin to:

• the latest release version with @latest
• a specific release version with @v{major}.{minor}.{patch}
• the development version with @main

Example Usage

name: Release Buildpacks

on:
  workflow_dispatch:

jobs:
  release:
    name: Release
    uses: heroku/languages-github-actions/.github/workflows/_buildpacks-release.yml@latest
    with:
      app_id: ${{ vars.GH_APP_ID }}
    secrets:
      app_private_key: ${{ secrets.GH_APP_PRIVATE_KEY }}
      cnb_registry_token: ${{ secrets.CNB_REGISTRY_TOKEN }}
      docker_hub_user: ${{ secrets.DOCKER_HUB_USER }}
      docker_hub_token: ${{ secrets.DOCKER_HUB_TOKEN }}

Inputs

Name	Description	Required	Default
app_id	Application ID of GitHub application (e.g. the Linguist App)	true
dry_run	Flag used for testing purposes to prevent actions that perform publishing operations from executing	false	false
ip_allowlisted_runner	The GitHub Actions runner to use to run jobs that require IP allow-list privileges	false	pub-hk-ubuntu-24.04-ip
languages_cli_branch	The branch to install the Languages CLI from (FOR TESTING)	false	main

Secrets

Name	Description	Required
app_private_key	Private key of GitHub application (e.g. the Linguist App)	true
cnb_registry_token	The token of the GitHub user used to interact with the CNB registry	true
docker_hub_user	The username to login to Docker Hub with	true
docker_hub_token	The token to login to Docker Hub with	true

Classic Buildpack - Prepare Release

Prepares a "classic" buildpack release by:

• updating the changelog
• opening a PR against the repository with the modified files

You can pin to:

• the latest release version with @latest
• a specific release version with @v{major}.{minor}.{patch}
• the development version with @main

Example Usage

name: Prepare Buildpack Release

on:
  workflow_dispatch:

jobs:
  prepare-release:
    uses: heroku/languages-github-actions/.github/workflows/_classic-buildpack-prepare-release.yml@latest
    secrets: inherit

Inputs

Name	Description	Required	Default
custom_update_command	An additional command to run before changes are committed, which can make use of the env vars EXISTING_VERSION and NEW_VERSION	false

In addition, the workflow requires that the LINGUIST_* env vars are available (which are set as organization variables).

Secrets

The workflow requires that inherit mode be enabled, so that it can access the LINGUIST_GH_PRIVATE_KEY organization secret.

Actions

Install Languages CLI

Downloads the Languages CLI from a known release or installs using Cargo.

Usage

- name: Install Languages CLI
  uses: heroku/languages-github-actions/.github/actions/install-languages-cli@latest

You can pin to:

• the latest release version with @latest
• a specific release version with @v{major}.{minor}.{patch}
• the development version with @main

Inputs

Name	Description	Required	Default
download_url	The url to download the CLI binary from	false
update_rust_toolchain	Run rustup update before installing the CLI from Cargo	false	true

Development

Custom actions are written in Rust and compiled into a command-line application that exposes the following sub-commands:

Usage: actions <COMMAND>

Commands:
  generate-buildpack-matrix  Generates a JSON list of buildpack information for each buildpack detected
  generate-changelog         Generates a changelog from one or more buildpacks in a project
  prepare-release            Bumps the version of each detected buildpack and adds an entry for any unreleased changes from the changelog
  update-builder             Updates all references to a buildpack in heroku/cnb-builder-images for the given list of builders
  help                       Print this message or the help of the given subcommand(s)