Ruleset Bypassing

You can use HausKeeper in order to bypass rulesets when using GitHub Actions and workflows. The bypass is achieved by integrating specific steps into the workflow YAML file, allowing the workflow to proceed when a ruleset violation would otherwise block it.

Implementation

To set up the ruleset bypass make sure that HausKeeper is installed on the repository. After that you will need to include following steps in your workflow YAML file.

1. Add the Token Generation Step

Insert the snippet below before any step that might trigger a ruleset violation:

- uses: actions/create-github-app-token@v1
  id: app-token
  with:
    app-id: ${{ vars.FH_HAUSKEEPER_ID }}
    private-key: ${{ secrets.FH_HAUSKEEPER_PRIVATE_KEY }}

This step generates a token, storing it as an output named token. You don't need to configure the vars.FH_HAUSKEEPER_ID variable nor secrets.FH_HAUSKEEPER_PRIVATE_KEY secret, as both are already set up organization-wide.

tip

The value for id can be adjusted to a different value as needed. For example, if you set id: hauskeeper-token, the token will be accessible using ${{ steps.hauskeeper-token.outputs.token }} in subsequent steps.

2. Update the checkout step

In the actions/checkout step, use the generated token by referencing the token output from the app-token step:

- uses: actions/checkout@v4
  with:
    ref: ${{ github.head_ref }}
    token: ${{ steps.app-token.outputs.token }}

This ensures that the token of HausKeeper is used during the checkout process, allowing the workflow to proceed despite the ruleset restrictions.

danger

When committing compiled files back to the repository, you must ensure that the directory or files being committed are ignored from the workflow trigger. Otherwise, each commit will trigger the workflow again, leading to an infinite loop.

Example

Here's an example of a workflow that runs a build/compile pipeline and commits the resulting files to the main branch:

name: compile-webpack

on:
  push:
    branches:
      - 'main'
    paths:
      - '**.js'
      - '**.ts'
      - '**.scss'
      - '!packages/**/Public/**' # ignore directory where compiled files will end up

jobs:
  compile:
    runs-on: ubuntu-latest

    permissions:
      contents: write

    steps:
      - uses: actions/create-github-app-token@v1
        id: app-token
        with:
          app-id: ${{ vars.FH_HAUSKEEPER_ID }}
          private-key: ${{ secrets.FH_HAUSKEEPER_PRIVATE_KEY }}

      - uses: actions/checkout@v4
        with:
          ref: ${{ github.head_ref }}
          token: ${{ steps.app-token.outputs.token }}

      # your custom build/compile pipeline
      # (e.g. installing composer/pnpm dependencies, compiling webpack assets)

      - uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_user_name: 'hauskeeper[bot]'
          commit_user_email: '190356206+hauskeeper[bot]@users.noreply.github.com'
          commit_message: 'build(webpack): compile CSS and JS'