diff --git a/.github/workflows/build-and-review-pr.yml b/.github/workflows/build-and-review-pr.yml new file mode 100644 index 0000000..67e987c --- /dev/null +++ b/.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,package.json,package-lock.json' + + # 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' + + # 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: 'npm run build' diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml deleted file mode 100644 index c7626ef..0000000 --- a/.github/workflows/build.yml +++ /dev/null @@ -1,68 +0,0 @@ -name: Build and Check for Changes -on: - # This workflow uses the pull_request trigger which prevents write permissions and secrets - # access to the target repository from public forks. This should remain as a pull_request - # trigger because checkout, build, format and checking for changes do not need elevated - # permissions to the repository. The reduced permissions for public forks is adequate. - # Since this will commit readme/recompile changes back to the branch, special attention - # should be paid to changes made to this workflow when reviewing the PR and granting - # permission to first time contributors to run the workflow. - pull_request: - # Don't include any specific paths here so we always get a build that produces a status - # check that our Branch Protection Rules can use. Having a status check also allows us - # to require that branches be up to date before they are merged. - -jobs: - build: - runs-on: ubuntu-latest - - steps: - - name: Checkout - uses: actions/checkout@v3 - with: - ref: ${{ github.head_ref }} - fetch-depth: 0 - - - name: Setup Node.js 16 - uses: actions/setup-node@v3 - with: - node-version: 16.x - - # If this step results in changes, they will be committed in the last step - - name: Recompile and Format action - run: npm run build - - - name: Check for code changes to the action - id: action-code - uses: im-open/did-custom-action-code-change@v1.0.1 - with: - files-with-code: 'action.yml,package.json,package-lock.json' - folders-with-code: 'src,dist' - token: ${{ secrets.GITHUB_TOKEN }} - - - name: Get the next version for the readme if there are code changes to the action - if: steps.action-code.outputs.HAS_CHANGES == 'true' - id: version - uses: im-open/git-version-lite@v2.1.2 - - - name: Update readme with next version if there are code changes to the action - if: steps.action-code.outputs.HAS_CHANGES == 'true' - uses: im-open/update-action-version-in-file@v1.0.0 - with: - file-to-update: './README.md' - action-name: ${{ github.repository }} - updated-version: ${{ steps.version.outputs.NEXT_VERSION }} - - - name: Commit unstaged readme/recompile changes if there are code changes to the action - if: steps.action-code.outputs.HAS_CHANGES == 'true' - run: | - if [[ "$(git status --porcelain)" != "" ]]; then - echo "There are changes to commit" - git config user.name github-actions - git config user.email github-actions@github.com - git add . - git commit -m "Update readme with latest version and/or recompile the action." - git push origin HEAD:${{ github.head_ref }} - else - echo "There were no changes to commit" - fi diff --git a/.github/workflows/increment-version-on-merge.yml b/.github/workflows/increment-version-on-merge.yml index 11043a4..f6e80f7 100644 --- a/.github/workflows/increment-version-on-merge.yml +++ b/.github/workflows/increment-version-on-merge.yml @@ -1,60 +1,47 @@ name: Increment Version on Merge +run-name: "${{ github.event.pull_request.merged && 'Increment version for' || 'Closing' }} PR #${{ github.event.pull_request.number }}" 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: - # - Our im-open repositories do not contain secrets, they are dumb actions - # - 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: - - 'dist/**' - - 'src/**' - - 'action.yml' - - 'package.json' - - 'package-lock.json' + # 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: - if: github.event.pull_request.merged == true && github.event.pull_request.base.ref == 'main' + uses: im-open/.github/.github/workflows/reusable-increment-version-on-merge.yml@v1 + with: + default-branch: main - runs-on: ubuntu-latest + # 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' - steps: - # Generally speaking, when the PR contents are treated as passive data, i.e. not in a - # position of influence over the build/testing process, it is safe to checkout the code - # on a pull_request_target. But we need to be extra careful not to trigger any script - # that may operate on PR controlled contents like in the case of npm install. - - name: Checkout Repository - uses: actions/checkout@v3 - with: - ref: main - fetch-depth: 0 - - # See https://github.com/im-open/git-version-lite for more details around how to increment - # major/minor/patch through commit messages - - name: Increment the version - uses: im-open/git-version-lite@v2 - id: version - with: - github-token: ${{ secrets.GITHUB_TOKEN }} - default-release-type: major - - - name: Create version tag, create or update major, and minor tags - run: | - git config user.name github-actions - git config user.email github-actions@github.com - git tag ${{ steps.version.outputs.NEXT_VERSION }} ${{ github.sha }} - git tag -f ${{ steps.version.outputs.NEXT_MAJOR_VERSION }} ${{ github.sha }} - git tag -f ${{ steps.version.outputs.NEXT_MINOR_VERSION }} ${{ github.sha }} - git push origin ${{ steps.version.outputs.NEXT_VERSION }} - git push origin ${{ steps.version.outputs.NEXT_MAJOR_VERSION }} -f - git push origin ${{ steps.version.outputs.NEXT_MINOR_VERSION }} -f + # 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' diff --git a/README.md b/README.md index 074bf2c..5c62eb2 100644 --- a/README.md +++ b/README.md @@ -6,25 +6,29 @@ This action works in conjunction with another step that runs `dotnet test` and i There should be one status check created per `trx` file. For comments, one will be created for all `trx` files. The check and comment headings are named after the test project the `trx` was generated for. -## Index - -- [Failures](#failures) -- [Limitations](#limitations) -- [Action Outputs](#action-outputs) - - [Pull Request Comment](#pull-request-comment) - - [Pull Request Status Check](#pull-request-status-check) - - [Workflow Run](#workflow-run) - - [Failed Test Details](#failed-test-details) -- [Inputs](#inputs) -- [Outputs](#outputs) -- [Usage Examples](#usage-examples) - - [Using the defaults](#using-the-defaults) - - [Specifying additional behavior](#specifying-additional-behavior) -- [Contributing](#contributing) - - [Recompiling](#recompiling) - - [Incrementing the Version](#incrementing-the-version) -- [Code of Conduct](#code-of-conduct) -- [License](#license) +## Index + +- [process-dotnet-test-results](#process-dotnet-test-results) + - [Failures](#failures) + - [Limitations](#limitations) + - [Action Outputs](#action-outputs) + - [Pull Request Comment](#pull-request-comment) + - [Pull Request Status Check](#pull-request-status-check) + - [Workflow Run](#workflow-run) + - [Failed Test Details](#failed-test-details) + - [Inputs](#inputs) + - [Outputs](#outputs) + - [Usage Examples](#usage-examples) + - [Using the defaults](#using-the-defaults) + - [Specifying additional behavior](#specifying-additional-behavior) + - [Using create-results-file](#using-create-results-file) + - [Contributing](#contributing) + - [Incrementing the Version](#incrementing-the-version) + - [Source Code Changes](#source-code-changes) + - [Recompiling Manually](#recompiling-manually) + - [Updating the README.md](#updating-the-readmemd) + - [Code of Conduct](#code-of-conduct) + - [License](#license) ## Failures @@ -60,23 +64,23 @@ For failed test runs you can expand each failed test and view more details about ## Inputs -| Parameter | Is Required | Default | Description | -| ------------------------------ | ----------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `github-token` | true | N/A | Used for the GitHub Checks API. Value is generally: secrets.GITHUB_TOKEN. | -| `base-directory` | false | `.` Root Directory of repository | The base directory of where to look for `trx` files. | -| `create-status-check` | false | true | Flag indicating whether a status check with code coverage results should be generated. | -| `create-pr-comment` | false | true | Flag indicating whether a PR comment with dotnet test results should be generated. When `true` the default behavior is to update an existing comment if one exists. | -| `create-results-file` | false | false | Flag indicating whether a results file in markdown format should be generated. | -| `update-comment-if-one-exists` | false | true | When `create-pr-comment` is true, this flag determines whether a new comment is created or if the action updates an existing comment if one is found which is the default behavior. | -| `ignore-test-failures` | false | `false` | When set to true the check status is set to `Neutral` when there are test failures and it will not block pull requests. | -| `timezone` | false | `UTC` | IANA time zone name (e.g. America/Denver) to display dates in. | -| `comment-identifier` | false | `` | Used when there are multiple test projects that run separately but are part of the same CI run. | -| `report-title-filter` | false | | Sets the report title in markdown to the `Unit Test Name`. This splits the Unit Test Name by `.` and gets the next word in the name that you inputed in this field. To find test name(s) run `dotnet test --list-tests`. See examples below for more details. | +| Parameter | Is Required | Default | Description | +|--------------------------------|-------------|----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `github-token` | true | N/A | Used for the GitHub Checks API. Value is generally: secrets.GITHUB_TOKEN. | +| `base-directory` | false | `.` Root Directory of repository | The base directory of where to look for `trx` files. | +| `create-status-check` | false | true | Flag indicating whether a status check with code coverage results should be generated. | +| `create-pr-comment` | false | true | Flag indicating whether a PR comment with dotnet test results should be generated. When `true` the default behavior is to update an existing comment if one exists. | +| `create-results-file` | false | false | Flag indicating whether a results file in markdown format should be generated. | +| `update-comment-if-one-exists` | false | true | When `create-pr-comment` is true, this flag determines whether a new comment is created or if the action updates an existing comment if one is found which is the default behavior. | +| `ignore-test-failures` | false | `false` | When set to true the check status is set to `Neutral` when there are test failures and it will not block pull requests. | +| `timezone` | false | `UTC` | IANA time zone name (e.g. America/Denver) to display dates in. | +| `comment-identifier` | false | `` | Used when there are multiple test projects that run separately but are part of the same CI run. | +| `report-title-filter` | false | | Sets the report title in markdown to the `Unit Test Name`. This splits the Unit Test Name by `.` and gets the next word in the name that you inputted in this field. To find test name(s) run `dotnet test --list-tests`. See examples below for more details. | ## Outputs | Output | Description | -| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `test-outcome` | Test outcome based on presence of failing tests: _Failed,Passed_
If exceptions are thrown or if it exits early because of argument errors, this is set to Failed. | | `trx-files` | List of `trx` files that were processed | | `test-results-file-path` | File path for test results file. This will be `null` when the input `create-results-file` is set to `false`. | @@ -188,57 +192,63 @@ To get a list of Unit Test names run `dotnet test --list-tests` in the cli. ## Contributing -When creating new PRs please ensure: +When creating PRs, please review the following guidelines: -1. For major or minor changes, at least one of the commit messages contains the appropriate `+semver:` keywords listed under [Incrementing the Version](#incrementing-the-version). -1. The action code does not contain sensitive information. +- [ ] 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 action has been recompiled. See [Recompiling Manually] for details. +- [ ] The README.md has been updated with the latest version of the action. See [Updating the README.md] for details. -When a pull request is created and there are changes to code-specific files and folders, the build workflow will run and it will recompile the action and push a commit to the branch if the PR author has not done so. The usage examples in the README.md will also be updated with the next version if they have not been updated manually. The following files and folders contain action code and will trigger the automatic updates: +### Incrementing the Version + +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 | +|----------------|---------------------------------------------| +| major | +semver:breaking | +| major | +semver:major | +| minor | +semver:feature | +| minor | +semver:minor | +| patch | _default increment type, no comment needed_ | -- action.yml -- package.json -- package-lock.json -- src/\*\* -- dist/\*\* +### Source Code Changes -There may be some instances where the bot does not have permission to push changes back to the branch though so these steps should be done manually for those branches. See [Recompiling Manually](#recompiling-manually) and [Incrementing the Version](#incrementing-the-version) for more details. +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 and the action should be recompiled. 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 a PR consists solely of non-source code changes like changes to the `README.md` or workflows under `./.github/workflows`, version updates and recompiles do not need to be performed. ### Recompiling Manually -If changes are made to the action's code in this repository, or its dependencies, the action can be re-compiled by running the following command: +This command utilizes [esbuild] to bundle the action and its dependencies into a single file located in the `dist` folder. If changes are made to the action's [source code], the action must be recompiled by running the following command: ```sh # Installs dependencies and bundles the code npm run build - -# Bundle the code (if dependencies are already installed) -npm run bundle ``` -These commands utilize [esbuild](https://esbuild.github.io/getting-started/#bundling-for-node) to bundle the action and -its dependencies into a single file located in the `dist` folder. +### Updating the README.md -### Incrementing the Version - -Both the build and PR merge workflows will use the strategies below to determine what the next version will be. If the build workflow was not able to automatically update the README.md action examples with the next version, the README.md should be updated manually as part of the PR using that calculated version. - -This action uses [git-version-lite] 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. -| Increment Type | Commit Message Fragment | -| -------------- | ------------------------------------------- | -| major | +semver:breaking | -| major | +semver:major | -| minor | +semver:feature | -| minor | +semver:minor | -| patch | _default increment type, no comment needed_ | +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 -This project has adopted the [im-open's Code of Conduct](https://github.com/im-open/.github/blob/master/CODE_OF_CONDUCT.md). +This project has adopted the [im-open's Code of Conduct](https://github.com/im-open/.github/blob/main/CODE_OF_CONDUCT.md). ## License -Copyright © 2021, Extend Health, LLC. Code released under the [MIT license](LICENSE). - +Copyright © 2023, Extend Health, LLC. Code released under the [MIT license](LICENSE). + + +[Incrementing the Version]: #incrementing-the-version +[Recompiling Manually]: #recompiling-manually +[Updating the README.md]: #updating-the-readmemd +[source code]: #source-code-changes +[usage examples]: #usage-examples +[build-and-review-pr]: ./.github/workflows/build-and-review-pr.yml +[increment-version-on-merge]: ./.github/workflows/increment-version-on-merge.yml +[esbuild]: https://esbuild.github.io/getting-started/#bundling-for-node +[git-version-lite]: https://github.com/im-open/git-version-lite [nasamin/trx-parser]: https://github.com/NasAmin/trx-parser#%EF%B8%8F-github-actions-limitations-%EF%B8%8F [limit]: https://github.com/github/docs/issues/3765 -[git-version-lite]: https://github.com/im-open/git-version-lite