From 0405b8f7874d18047249c24a1956956f6ecc2fb0 Mon Sep 17 00:00:00 2001 From: Danielle Adams Date: Tue, 5 Sep 2023 14:04:16 -0600 Subject: [PATCH 1/7] ARCH-1916 - Update README.md with latest contributing guidelines --- README.md | 96 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 53 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index 93824f8..a33908d 100644 --- a/README.md +++ b/README.md @@ -5,20 +5,24 @@ This action is based on [danielpalme/ReportGenerator-GitHub-Action]. [ReportGenerator] converts coverage reports generated by OpenCover, dotCover, Visual Studio, NCover, Cobertura, JaCoCo, Clover, gcov or lcov into human readable reports in various formats. This action does not generate the code coverage reports itself, those must be created by a previous action. - -## Index -- [Inputs](#inputs) -- [Usage](#usage) -- [Contributing](#contributing) - - [Recompiling](#recompiling) - - [Incrementing the Version](#incrementing-the-version) -- [Code of Conduct](#code-of-conduct) -- [License](#license) +## Index + +- [ReportGenerator](#reportgenerator) + - [Inputs](#inputs) + - [Usage Examples](#usage-examples) + - [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) ## Inputs + | Parameter | Is Required | Default Value | Description | -| ----------------- | ----------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +|-------------------|-------------|-----------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `reports` | false | */**/coverage.opencover.xml | The coverage reports that should be parsed (separated by semicolon). Globbing is supported. | | `targetdir` | false | coverage-results | The directory where the generated report should be saved. | | `reporttypes` | false | Html;MarkdownSummary; | The output formats and scope (separated by semicolon)
Values: Badges, Clover, Cobertura, CsvSummary, Html, HtmlChart, HtmlInline, HtmlInline_AzurePipelines, HtmlInline_AzurePipelines_Dark, HtmlSummary, JsonSummary, Latex, LatexSummary, lcov, MarkdownSummary, MHtml, PngChart, SonarQube, TeamCitySummary, TextSummary, Xml, XmlSummary | @@ -34,7 +38,7 @@ This action does not generate the code coverage reports itself, those must be cr | `customSettings` | false | '' | Optional custom settings (separated by semicolon). See [Settings]. | | `toolpath` | false | reportgeneratortool | Default directory for installing the dotnet tool. | -## Usage +## Usage Examples ```yml - name: Setup .NET Core # Required to execute ReportGenerator @@ -82,58 +86,64 @@ This action does not generate the code coverage reports itself, those must be cr ## Contributing -When creating new PRs please ensure: +When creating PRs, please review the following guidelines: + +- [ ] 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. + +### 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* | -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. +### Source Code Changes -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: +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. -- action.yml -- package.json -- package-lock.json -- src/\*\* -- dist/\*\* +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. -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. +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. - -### 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. +### Updating the README.md -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 [danielpalme/ReportGenerator-GitHub-Action]: https://github.com/danielpalme/ReportGenerator-GitHub-Action [ReportGenerator]: https://github.com/danielpalme/ReportGenerator -[Settings]: https://github.com/danielpalme/ReportGenerator/wiki/Settings \ No newline at end of file +[Settings]: https://github.com/danielpalme/ReportGenerator/wiki/Settings From 6d02cb1b723b44cbf652cde006debe0e25aee5e4 Mon Sep 17 00:00:00 2001 From: Danielle Adams Date: Tue, 5 Sep 2023 15:07:35 -0600 Subject: [PATCH 2/7] ARCH-1916 - Rename build.yml --- .github/workflows/{build.yml => build-and-review-pr.yml} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename .github/workflows/{build.yml => build-and-review-pr.yml} (100%) diff --git a/.github/workflows/build.yml b/.github/workflows/build-and-review-pr.yml similarity index 100% rename from .github/workflows/build.yml rename to .github/workflows/build-and-review-pr.yml From c043db894160a49e875db0d1382195d8cb592152 Mon Sep 17 00:00:00 2001 From: Danielle Adams Date: Tue, 5 Sep 2023 15:54:32 -0600 Subject: [PATCH 3/7] ARCH-1916 - Update build-and-review-pr.yml implementation --- .github/workflows/build-and-review-pr.yml | 114 ++++++++++------------ 1 file changed, 54 insertions(+), 60 deletions(-) diff --git a/.github/workflows/build-and-review-pr.yml b/.github/workflows/build-and-review-pr.yml index c7626ef..b8f596a 100644 --- a/.github/workflows/build-and-review-pr.yml +++ b/.github/workflows/build-and-review-pr.yml @@ -1,68 +1,62 @@ -name: Build and Check for Changes +name: Build and Review PR +run-name: Build and Review PR #${{ github.event.pull_request.number }} + 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. + # 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: - # 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. + 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: - runs-on: ubuntu-latest - - steps: - - name: Checkout - uses: actions/checkout@v3 - with: - ref: ${{ github.head_ref }} - fetch-depth: 0 + 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' - - name: Setup Node.js 16 - uses: actions/setup-node@v3 - with: - node-version: 16.x + # The id of the usage examples section of the README.md + readme-examples-id: '#usage-examples' - # 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 + # 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' - - 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 }} + # 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' - - 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 + # 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' From 3a43d14a7e681e06dd20f8630552dc9d7b10e852 Mon Sep 17 00:00:00 2001 From: Danielle Adams Date: Tue, 5 Sep 2023 16:08:24 -0600 Subject: [PATCH 4/7] ARCH-1916 - Update increment-version-on-merge.yml implementation --- .../workflows/increment-version-on-merge.yml | 85 ++++++++----------- 1 file changed, 36 insertions(+), 49 deletions(-) diff --git a/.github/workflows/increment-version-on-merge.yml b/.github/workflows/increment-version-on-merge.yml index 44f52f3..b287790 100644 --- a/.github/workflows/increment-version-on-merge.yml +++ b/.github/workflows/increment-version-on-merge.yml @@ -1,59 +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: - # - 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 }} - - - 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' From 6ac457175f9ff5a7c284c7a8729cdd6c92a9fedb Mon Sep 17 00:00:00 2001 From: Danielle Adams Date: Tue, 5 Sep 2023 16:44:19 -0600 Subject: [PATCH 5/7] ARCH-1916 - Update .gitignore --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 75ab0b6..1e60333 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ .vs lib/ node_modules +/.vscode/launch.json reportgeneratortool src/*.js \ No newline at end of file From 65a5d25d4c239610becd83ae357b37521a714004 Mon Sep 17 00:00:00 2001 From: Danielle Adams Date: Wed, 6 Sep 2023 09:24:57 -0600 Subject: [PATCH 6/7] ARCH-1916 - Update run-name for workflows --- .github/workflows/build-and-review-pr.yml | 2 +- .github/workflows/increment-version-on-merge.yml | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/build-and-review-pr.yml b/.github/workflows/build-and-review-pr.yml index b8f596a..67e987c 100644 --- a/.github/workflows/build-and-review-pr.yml +++ b/.github/workflows/build-and-review-pr.yml @@ -1,5 +1,5 @@ name: Build and Review PR -run-name: Build and Review PR #${{ github.event.pull_request.number }} +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 diff --git a/.github/workflows/increment-version-on-merge.yml b/.github/workflows/increment-version-on-merge.yml index b287790..4d35b56 100644 --- a/.github/workflows/increment-version-on-merge.yml +++ b/.github/workflows/increment-version-on-merge.yml @@ -1,4 +1,5 @@ name: Increment Version on Merge +run-name: 'Increment Version for PR #${{ github.event.pull_request.number }}' on: # https://securitylab.github.com/research/github-actions-preventing-pwn-requests/ # https://docs.github.com/en/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token From fe48a7a58e2a2c6b9e283c04abf40fb3fab70c2f Mon Sep 17 00:00:00 2001 From: Danielle Adams Date: Wed, 6 Sep 2023 15:14:54 -0600 Subject: [PATCH 7/7] ARCH-1916 - Update run-name for increment workflow --- .github/workflows/increment-version-on-merge.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/increment-version-on-merge.yml b/.github/workflows/increment-version-on-merge.yml index 4d35b56..f6e80f7 100644 --- a/.github/workflows/increment-version-on-merge.yml +++ b/.github/workflows/increment-version-on-merge.yml @@ -1,5 +1,5 @@ name: Increment Version on Merge -run-name: 'Increment Version for PR #${{ github.event.pull_request.number }}' +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/ # https://docs.github.com/en/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token