Allow to Use Custom Git Actor for Bundled JS Output (#14)

* feat: allow to use custom actor

* chore: new inputs

* docs: add tutorial section

* chore: minor doc fix

* chore: remove unused `github_token` input

Author: DavideIadeluca

README.md

@@ -21,7 +21,6 @@ jobs:
       - uses: actions/checkout@master
       - uses: flarum/action-build@2
         with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
           build_script: build # npm run build
           build_typings_script: build-typings # npm run build-typings
           test_script: test # npm run test
@@ -36,8 +35,7 @@ jobs:
 Here is a full list of options available using the `with` syntax:
 
 | Name                   | Required | Description                                                                                                             | Example                       | Default |
-|------------------------| -------- |-------------------------------------------------------------------------------------------------------------------------|-------------------------------| ------- |
-| `github_token`         | Yes      | Your Actions GitHub token. The example value should work for this by default.                                           | `${{ secrets.GITHUB_TOKEN }}` | None    |
+| ---------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ------- |
 | `build_script`         | Yes      | The `package.json` script to run to build your extension JS.                                                            | `build`                       | `build` |
 | `build_typings_script` | No       | If defined, runs the script of this name in `package.json` to build typings for your extension.                         | `build-typings`               | Unset   |
 | `format_script`        | No       | If defined, runs the script of this name in `package.json` to check code formatting of your extension's JS.             | `format-check`                | Unset   |
@@ -49,13 +47,81 @@ Here is a full list of options available using the `with` syntax:
 | `do_not_commit`        | No       | Set to `true` to NOT commit the built JS/Typings. Useful for validating JS source.                                      | `false`                       | `false` |
 | `checks`               | No       | An array of strings, where each is a script that should be run before committing built js.                              | `false`                       | `false` |
 | `commit_all_dirty`     | No       | Set to `true` to commit all file changes, not just files in the dist JS directory.                                      | `false`                       | `false` |
+| `git_actor_name`       | No       | Allows to set a different username (normally `flarum-bot`) for the actor which commits the bundles JS.                  | `acme-bot`                    | Unset   |
+| `git_actor_email`      | No       | Allows to set a different email for the actor which commits the bundled JS.                                             | `[email protected]`        | Unset   |
 
 ### Assumptions
 
 Your Javascript must be in a `js` folder, similar to how Flarum core and Flarum's first-party extensions are laid out.
 
 If building typings, we assume that they are built to `js/dist-typings`, as set in the example `tsconfig.json` found on the [flarum-tsconfig](https://github.com/flarum/flarum-tsconfig).
 
+## Setting Up Custom Git Actor for Frontend Workflow
+
+This guide helps you configure a custom Git actor in your extension's frontend workflow, specifically useful if your organization enforces branch protection rules requiring pull requests for changes to the default branch.
+
+### Basic Configuration (Light Version)
+
+To change the actor committing bundled JS in your workflow:
+
+1. Add `git_actor_name` and `git_actor_email` inputs to your workflow file.
+2. These values can represent either a real GitHub user or a fictional one.
+3. If using a real user, it's recommended to use the GitHub-provided email for privacy-enabled accounts.
+
+Example:
+
+```yaml
+name: ACME Foobar JS
+
+on: [workflow_dispatch, push, pull_request]
+
+jobs:
+  run:
+    uses: flarum/framework/.github/workflows/[email protected]
+    with:
+      enable_prettier: true
+      ...
+      git_actor_name: acme-bot
+      git_actor_email: [email protected]
+```
+
+### Advanced Configuration (With Branch Protection Rules)
+
+If you also want to enforce branch protection and allow a custom actor to bypass pull requests:
+
+1. Create a dedicated CI GitHub account with admin permissions in your organization.
+2. Generate a Personal Access Token for the CI account:
+
+   - Go to [GitHub Tokens](https://github.com/settings/tokens/new) and create a new token with repo and workflow scopes.
+
+3. Add the token as a secret in your repository.
+4. Use the real CI account's username and email in your workflow.
+
+When setting branch protection rules, make sure not to enable "Do not allow bypassing the above settings" as this would block automated commits from the CI actor.
+
+```yml
+name: ACME Foobar JS
+
+on: [workflow_dispatch, push, pull_request]
+
+jobs:
+  run:
+    uses: flarum/framework/.github/workflows/[email protected]
+    with:
+      enable_prettier: true
+      ..
+      git_actor_name: ci-bot
+      git_actor_email: [email protected]
+
+    secrets:
+      git_actor_token: ${{ secrets.GIT_ACTOR_TOKEN }}
+```
+
+### Important Notes
+
+- Avoid the "Do not allow bypassing the above settings" option when setting up branch protection, or your CI actor won’t be able to commit the bundled JS.
+- Make sure other rules or permissions don't block the CI account from making automated commits.
+
 ## Only Build on Master
 
 If you only want to run the workflow when commits are pushed to the `master` branch, change `on: push` to the following:

action.yml

@@ -5,9 +5,6 @@ runs:
   using: 'node20'
   main: 'dist/index.js'
 inputs:
-  github_token:
-    description: 'Token used to push built JS code to your GitHub repository (if in doubt, use "(dollar-sign){{ secrets.GITHUB_TOKEN }}")'
-    required: true
   build_script:
     description: The name of the package.json script to run to build your JS code
     default: 'build'
@@ -43,3 +40,9 @@ inputs:
     description: Set to `true` to commit all file changes, not just files in the dist JS directory.
     default: 'false'
     required: false
+  git_actor_name:
+    description: The name of the git actor to use for the bundled JS output.
+    required: false
+  git_actor_email:
+    description: The email of the git actor to use for the bundled JS output.
+    required: false

src/jobs/commitChangesToGit.ts

@@ -24,10 +24,13 @@ export default async function commitChangesToGit(jp: FSJetpack): Promise<void> {
     maxConcurrentProcesses: 1,
   };
 
+  const gitActorName = core.getInput('git_actor_name', { required: false, trimWhitespace: true }) || 'flarum-bot';
+  const gitActorEmail = core.getInput('git_actor_email', { required: false, trimWhitespace: true }) || '[email protected]';
+
   const config = {
     author: {
-      name: 'flarum-bot',
-      email: '[email protected]',
+      name: gitActorName,
+      email: gitActorEmail,
     },
   };
 
@@ -61,11 +64,9 @@ Includes transpiled JS/TS${core.getInput('build_typings_script') !== '' ? ', and
 
 [skip ci]`);
 
-  const token = core.getInput('github_token', { required: true, trimWhitespace: true });
-
   debugLog(`** Pushing commit`);
 
-  await git.addRemote('upstream', `https://${process.env.GITHUB_ACTOR}:${token}@github.com/${process.env.GITHUB_REPOSITORY}.git`);
+  await git.addRemote('upstream', `https://github-actions:${process.env.GITHUB_TOKEN}@github.com/${process.env.GITHUB_REPOSITORY}.git`);
 
   log(`${status}`);