[1.x] Allow to Pass Custom Git Actor to flarum/action-build

[DavideIadeluca]

Counterpart to flarum/action-build#14

Fixes #0000

Some organizations might be looking into restricting pushing directly to the default branch and instead want to require that every change must be done on a non-protected branch and only merged via a pull request.

The issue is that flarum-bot doesn't qualify as an actor which can be selected to bypass required pull requests (at least for third-party organizations, not sure if it works in the flarum org itself).

This PR and flarum/action-build#14 aims to optionally add the ability for repository maintainers to customize the actor which commits the bundled JS (by default flarum-bot) and set up branch protection rules, while still allowing the bundled JS to be automatically committed to the default branch. 

Changes proposed in this pull request:
This PR introduces two new inputs and a new secret:

• git_actor_name
• git_actor_email
• git_actor_token

Those new values can optionally be used in the frontend workflow of extensions (which use the reusable frontend workflow) like this:

name: ACME Foobar JS

on: [workflow_dispatch, push, pull_request]

jobs:
  run:
    uses: flarum/framework/.github/workflows/[email protected]
    with:
      enable_prettier: true
      enable_typescript: true

      frontend_directory: ./js
      js_package_manager: yarn
      main_git_branch: master

      git_actor_name: acme-bot
      git_actor_email: [email protected]

    secrets:
      git_actor_token: ${{ secrets.GIT_ACTOR_TOKEN }}

Outline of how it works

Note

This guide is written for usage in private extensions. The required setup for Advanced version below might differ for your use case.

The changes introduced in this PR can be used in two "levels" depending on what the repository maintainer wants to achieve:

• Light Version: If a maintainer is just looking into changing the actor, without setting up branch protection rules as explained in the beginning, only the git_actor_name and (ideally) the git_actor_email have to be provided in the frontend workflow of your extension. Both values can either be based on a real GitHub user or a fictional, non-existing one. If a real user is used, it's recommended to use the email which GitHub provides for web-based operations when email privacy is enabled (see https://github.com/settings/emails).

• Advanced version: If a maintainer is looking into setting up branch protection rules and exempting the new custom actor for it, the following steps are a prerequisite for it:

  1. Create a new GitHub Account, which is ideally just used for CI purposes
  2. Add this new user to your organization and grant it the owner role (i.e. admin permissions)
  3. Using the new account, go to https://github.com/settings/tokens/new and create a new personal access token (classic). Select an expiration date and name which makes sense for you and select the repo (full) and workflow scopes.
  4. At either the enterprise, organization or repository level, create a new secret and use the previously generated token as the value. You can name this secret whatever you want.
  5. In the frontend workflow of your extension, provide the real username and email of the CI Account to the git_actor_name and git_actor_email input. Also add the just created secret, like in the example workflow above.

Important

When setting up branch protection rules and requiring a pull request before merging, don't select the Do not allow bypassing the above settings option. This will prevent the bundled JS from being committed. Also verify that you don't have other rules, rulesets, roles etc. in place which might interfere with the logic.

Reviewers should focus on:

If this PR and flarum/action-build#14 get merged, please update the flarum/action-build version in the REUSABLE_FRONTEND workflow.

Screenshot

If maintainers don't provide the values introduced here, flarum-bot will be used like before as the actor which commits the bundled JS:

If maintainers provide the `git_actor_name` and `git_actor_email` values with a real GitHub user:

If maintainers provide a non-existing user or non-matching values (i.e. an email address which doesn't match with the username:

QA

Necessity

• Has the problem that is being solved here been clearly explained?
• If applicable, have various options for solving this problem been considered?
• For core PRs, does this need to be in core, or could it be in an extension?
• Are we willing to maintain this for years / potentially forever?

Confirmed

• Frontend changes: tested on a local Flarum installation.
• Backend changes: tests are green (run composer test).
• Core developer confirmed locally this works as intended.
• Tests have been added, or are not appropriate here.

Required changes:

• Related documentation PR: (Remove if irrelevant)
• Related core extension PRs: (Remove if irrelevant)