diff --git a/README.md b/README.md index 21e4c25..a5e6c36 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,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 | @@ -49,6 +49,8 @@ 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. | `acme-bot@example.org` | Unset | ### Assumptions @@ -56,6 +58,72 @@ Your Javascript must be in a `js` folder, similar to how Flarum core and Flarum' 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/REUSABLE_frontend.yml@1.x + with: + enable_prettier: true + ... + git_actor_name: acme-bot + git_actor_email: 12345678+acme-bot@users.noreply.github.com +``` + +### 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/REUSABLE_frontend.yml@1.x + with: + enable_prettier: true + .. + git_actor_name: ci-bot + git_actor_email: ci-bot@users.noreply.github.com + + 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: diff --git a/action.yml b/action.yml index 714d6c5..3f7a081 100644 --- a/action.yml +++ b/action.yml @@ -43,3 +43,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 diff --git a/src/jobs/commitChangesToGit.ts b/src/jobs/commitChangesToGit.ts index c77b489..14a3319 100644 --- a/src/jobs/commitChangesToGit.ts +++ b/src/jobs/commitChangesToGit.ts @@ -24,10 +24,13 @@ export default async function commitChangesToGit(jp: FSJetpack): Promise { 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 }) || 'bot@flarum.org'; + const config = { author: { - name: 'flarum-bot', - email: 'bot@flarum.org', + 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}`);