Build refactor

.github/workflows/build-and-review-pr.yml

@@ -0,0 +1,62 @@
+name: Build and Review PR
+run-name: Build and Review PR #${{ github.event.pull_request.number }}
+
+on:
+  # https://docs.github.com/en/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token
+  #
+  # This workflow uses the pull_request trigger which prevents write permissions on the
+  # GH_TOKEN and secrets access from public forks.  This should remain as a pull_request
+  # trigger to minimize the access public forks have in the repository.  The reduced
+  # permissions are adequate but do mean that re-compiles and readme changes will have to be
+  # made manually by the PR author.  These auto-updates could be done by this workflow
+  # for branches but in order to re-trigger a PR build (which is needed for status checks),
+  # we would make the commits with a different user and their PAT.  To minimize exposure
+  # and complication we will request those changes be manually made by the PR author.
+  pull_request:
+    types: [opened, synchronize, reopened]
+  # paths:
+  #   Do not include specific paths here.  We always want this build to run and produce a
+  #   status check which are branch protection rules can use.  If this is skipped because of
+  #   path filtering, a status check will not be created and we won't be able to merge the PR
+  #   without disabling that requirement.  If we have a status check that is always produced,
+  #   we can also use that to require all branches be up to date before they are merged.
+
+jobs:
+  build-and-review-pr:
+    # This reusable workflow will check to see if an action's source code has changed based on
+    # whether the PR includes files that match the files-with-code arg or are in one of the
+    # dirs-with-code directories.  If there are source code changes, this reusable workflow
+    # will then run the action's build (if one was provided) and update the README.md with the
+    # the latest version of the action.  If those two steps result in any changes that need to
+    # be committed, the workflow will fail because the PR needs some updates.  Instructions for
+    # updating the PR will be available in the build log, the workflow summary and as a PR
+    # comment if the PR came from a branch (not a fork).
+    # This workflow assumes:
+    #  - The main README.md is at the root of the repo
+    #  - The README contains a contribution guidelines and usage examples section
+    uses: im-open/.github/.github/workflows/reusable-build-and-review-pr.yml@v1
+    with:
+      action-name: ${{ github.repository }}
+      default-branch: main
+      readme-name: 'README.md'
+
+      # The id of the contribution guidelines section of the README.md
+      readme-contribution-id: '#contributing'
+
+      # The id of the usage examples section of the README.md
+      readme-examples-id: '#usage-examples'
+
+      # The files that contain source code for the action.  Only files that affect the action's execution
+      # should be included like action.yml or package.json.  Do not include files like README.md or .gitignore.
+      # Files do not need to be explicitly provided here if they fall under one of the dirs in dirs-with-code.
+      # ** This value must match the same files-with-code argument specified in increment-version-on-merge.yml.
+      files-with-code: 'action.yml' # TODO:  Update if there are additional files or scripts.
+
+      # The directories that contain source code for the action.  Only dirs with files that affect the action's
+      # execution should be included like src or dist.  Do not include dirs like .github or node_modules.
+      # ** This value must match the same dirs-with-code argument specified in increment-version-on-merge.yml.
+      dirs-with-code: '' # TODO:  Update if there are additional directories with code for the action.
+
+      # The npm script to run to build the action.  This is typically 'npm run build' if the
+      # action needs to be compiled.  For composite-run-steps actions this is typically empty.
+      build-command: '' # TODO:  Update if this action has a build step.

.github/workflows/increment-version-on-merge.yml

@@ -1,27 +1,46 @@
 name: Increment Version on Merge
 on:
   # https://securitylab.github.com/research/github-actions-preventing-pwn-requests/
-  # - GitHub’s standard pull_request workflow trigger prevents write permissions and secrets
-  #   access to the target repository from public forks.  PRs from a branch in the same repo
-  #   and forks of internal/private repos are not limited the same way for this trigger.
-  # - The pull_request_target trigger allows the workflow to relax some restrictions to a
-  #   target repository so PRs from forks have write permission to the target repo and have
-  #   secrets access (which we need in order to push a new tag in this workflow).
-  # - For this workflow, the elevated permissions should not be a problem because:
-  #    - Require approval for all outside collaborators' is set at the org level so someone
-  #      with Write access has a chance to review code before allowing any workflow runs
-  #    - This workflow with elevated Write permissions will only run once the code has been
-  #      reviewed, approved by a CODEOWNER and merged
+  # https://docs.github.com/en/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token
+  #
+  # GitHub's standard pull_request workflow trigger prevents write permissions and
+  # secrets access when the PR is from a public fork.  PRs from branches and forks of
+  # internal/private repos are not limited the same way for the pull_request trigger.
+  #
+  # The pull_request_target trigger (which this workflow is using) relaxes some of those
+  # restrictions and allows PRs from public forks to have write permissions through the
+  # GH_TOKEN which we need in order to push new tags to the repo through this workflow.
+  #
+  # For this workflow, the elevated permissions should not be a problem because:
+  # • This workflow is only triggered when a PR is closed and the reusable workflow it
+  #   calls only executes if it has been merged to the default branch.  This means the PR
+  #   has been reviewed and approved by a CODEOWNER and merged by someone with Write
+  #   access before this workflow with its elevated permissions gets executed.  Any code
+  #   that doesn't meet our standards should be caught before it gets to this point.
+  # • The "Require approval for all outside collaborators" setting is set at the org-level.
+  #   Before a workflow can execute for a PR generated by an outside collaborator, a user
+  #   with Write access must manually approve the request to execute the workflow run.
+  #   Prior to doing so they should have had a chance to review any changes in the PR
   pull_request_target:
     types: [closed]
-    paths-ignore:
-      - 'README.md'
-      - 'LICENSE'
-      - '.github/CODEOWNERS'
-      - '.github/workflows/**'
+  # paths:
+  #   Do not include specific paths here.  reusable-increment-version-on-merge.yml will decide
+  #   if this action should be incremented and if new tags should be pushed to the repo based
+  #   on the same criteria used in the build-and-review-pr.yml workflow.
 
 jobs:
   increment-version:
-    uses: im-open/.github/.github/workflows/reusable-version-on-merge.yml@v1
+    uses: im-open/.github/.github/workflows/reusable-increment-version-on-merge.yml@v1
     with:
       default-branch: main
+
+      # The files that contain source code for the action.  Only files that affect the action's execution
+      # should be included like action.yml or package.json.  Do not include files like README.md or .gitignore.
+      # Files do not need to be explicitly provided here if they fall under one of the dirs in dirs-with-code.
+      # ** This value must match the same files-with-code argument specified in increment-version-on-merge.yml.
+      files-with-code: 'action.yml,package.json,package-lock.json' # TODO:  Update if there are additional files or scripts.
+
+      # The directories that contain source code for the action.  Only dirs with files that affect the action's
+      # execution should be included like src or dist.  Do not include dirs like .github or node_modules.
+      # ** This value must match the same dirs-with-code argument specified in increment-version-on-merge.yml.
+      dirs-with-code: 'src,dist' # TODO:  Update if there are additional directories with code for the action.

README.md

@@ -9,6 +9,7 @@ This template can be used to quickly start a new custom composite-run-steps acti
 - [Example](#example)
 - [Contributing](#contributing)
   - [Incrementing the Version](#incrementing-the-version)
+  - [Source Code Changes](#source-code-changes)
   - [Updating the README.md](#updating-the-readmemd)
 - [Code of Conduct](#code-of-conduct)
 - [License](#license)
@@ -86,18 +87,15 @@ jobs:
 
 ## Contributing
 
-When creating new PRs from a fork please review the following items:
-| PR Contribution Requirements/Tasks                                                                                                                    | Required<br/>for Branches | Required<br/>for Forks |
-|-------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------------:|:----------------------:|
-| The action code does not contain sensitive information.                                                                                               |            Yes            |          Yes           |
-| For major or minor changes, at least one of the commit messages contains the appropriate `+semver:` keywords listed under [Incrementing the Version]. |            Yes            |          Yes           |
-| The README.md action versions have been updated.  See [Updating the README.md] for details.                                                           |            No*            |          Yes           |
+When creating PRs, please review the following guidelines:
 
-\* When a pull request is created from a branch, the build workflow will automatically update the README.md with the next version and push a commit to the branch if those changes have not already been made.
+- [ ] The action code does not contain sensitive information.
+- [ ] At least one of the commit messages contains the appropriate `+semver:` keywords listed under [Incrementing the Version] for major and minor increments.
+- [ ] The README.md has been updated with the latest version of the action.  See [Updating the README.md] for details.
 
 ### Incrementing the Version
 
-This repo uses [git-version-lite] in its build and PR merge workflows to examine commit messages to determine whether to perform a major, minor or patch increment on merge.  The following table provides the fragment that should be included in a commit message to active different increment strategies.
+This repo uses [git-version-lite] in its workflows to examine commit messages to determine whether to perform a major, minor or patch increment on merge if [source code] changes have been made.  The following table provides the fragment that should be included in a commit message to active different increment strategies.
 
 | Increment Type | Commit Message Fragment                     |
 |----------------|---------------------------------------------|
@@ -107,15 +105,17 @@ This repo uses [git-version-lite] in its build and PR merge workflows to examine
 | minor          | +semver:minor                               |
 | patch          | *default increment type, no comment needed* |
 
-If a contributor is unsure what the next version will be, create a PR and the first build workflow that runs will calculate the value.
+### Source Code Changes
 
-### Updating the README.md
+The files and directories that are considered source code are listed in the `files-with-code` and `dirs-with-code` arguments in both the [build-and-review-pr] and [increment-version-on-merge] workflows.  
+
+If a PR contains source code changes, the README.md should be updated with the latest action version.  The [build-and-review-pr] workflow will ensure these steps are performed when they are required.  The workflow will provide instructions for completing these steps if the PR Author does not initially complete them.
 
-If changes are made to the action's source code, the README.md file should be updated to reflect the next version of the action.  Each instance of the action in the examples should be updated.  This helps users know what the latest tag is without having to navigate to the Tags page of the repository.
+If a PR consists solely of non-source code changes like changes to the `README.md` or workflows under `./.github/workflows`, version updates do not need to be performed.
 
-This step does not need to be completed if only ancillary files like the README.md have been changed.
+### Updating the README.md
 
-If a pull request is made from a branch, this step will be automatically performed by the build workflow unless the PR author has already done so.  Pull requests made from forked repositories will need to perform this step manually.  See [Incrementing the Version] for details on how to determine what the next version will be.
+If changes are made to the action's [source code], the [usage examples] section of this file should be updated with the next version of the action.  Each instance of this action should be updated.  This helps users know what the latest tag is without having to navigate to the Tags page of the repository.  See [Incrementing the Version] for details on how to determine what the next version will be or consult the first workflow run for the PR which will also calculate the next version.
 
 ## Code of Conduct
 
@@ -128,3 +128,7 @@ Copyright &copy; 2023, Extend Health, LLC. Code released under the [MIT license]
 [git-version-lite]: https://github.com/im-open/git-version-lite
 [Incrementing the Version]: #incrementing-the-version
 [Updating the README.md]: #updating-the-readmemd
+[build-and-review-pr]: ./.github/workflows/build-and-review-pr.yml
+[increment-version-on-merge]: ./.github/workflows/increment-version-on-merge.yml
+[source code]: #source-code-changes
+[usage examples]: #usage-examples