Create a GitHub workflow to lint a repo

This is an attempt to automate a frequent source of toil (and a classic
example of spending 20 times as long automating a task as it would take
to do it) where we test [rubocop-govuk against a few repos on local
machines][1] before releasing a new version.

The approach to reduce this toil is create a GitHub Action Workflow that
can be [executed manually][2] that will clone an alphagov repo, switch the
rubocop-govuk version to the git reference provided by the workflow, and
run rubocop against it.

As this will only be executed manually there are some risks it may
degrade with time. There is also a risk that it won't work for some
alphagov projects, should they have extra system dependency needs to
install gems.

These are some examples of the job running against projects:

- [Whitehall](https://github.com/alphagov/rubocop-govuk/actions/runs/3543847135)
- [Content
  Publisher](https://github.com/alphagov/rubocop-govuk/actions/runs/3543848200)
- [GDS API Adapters](https://github.com/alphagov/rubocop-govuk/actions/runs/3543849527)
- [Search API](https://github.com/alphagov/rubocop-govuk/actions/runs/3543850013)

---

There were a few quirks/decisions when putting this together:

The first was whether to utilise bundler cache or not and whether it was
problematic to share a cache with different apps. I decided it'd be
useful as there's probably a lot of cross-over between the gems of apps.
However setting bundler-cache on ruby/setup-ruby does put bundler into
deployment mode and I couldn't work out how to disable that with env
vars (BUNDLE_DEPLOYMENT=false failed) so I had to add an extra step to
resolve this.

The second issue was using `bundle add rubocop-govuk
--github=alphagov/rubocop-govuk --ref=main` to add the git reference of
the gem. This added a line like: `gem "rubocop-govuk", "~> 4.8", :github
=> "alphagov/rubocop-govuk", :ref => "main"` which fails linting 🤦. I
consider adding a step of `bundle exec rubocop -A Gemfile` which would
fix the issue but this seemed a bit contrived. I instead went for the
rather janky looking printf step.

Another issue was thinking how best to communicate the results. I thought it
would be nice to use the [GitHub Action summary][3] as a way to output it to
the action summary screen and avoid a few clicks. However I didn't want
to lose the information in the run output. Hence I used `tee` as a way to do
both. Using the markdown formatter for Rubocop allowed this summary to be
nicely formatted for GitHub.

Finally, I was pondering whether we want a job to fail when linting
fails. In theory if the linting fails the job isn't an error because
we're running it to just see the linting output and just managing to lint is
a success. However I felt that doing this was potentially misleading and
could lead to missing problematic rules. Ideally it'd be nice to have a neutral
exit state (such as unstable for Jenkins) to indicate the item ran without error
but wasn't a success.

[1]: https://github.com/alphagov/rubocop-govuk/blob/e6d5c03ad5cbbac1fc5a711731e79af0d8a2fbc7/CONTRIBUTING.md#1-check-what-the-impact-is-going-to-be
[2]: https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#workflow_dispatch
[3]: https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#adding-a-job-summary

.github/workflows/run-against-project.yml

@@ -0,0 +1,51 @@
+# GitHub Workflow to allow running rubocop-govuk against an alphagov repo
+# to test the effects of linting rules prior to releasing the gem.
+#
+# This is expected to be called manually via the GitHub UI (https://github.com/alphagov/rubocop-govuk/actions/workflows/run-against-project.yml)
+# or via the GitHub CLI.
+name: Run against project
+run-name: Running rubocop-govuk (${{ inputs.git_ref }}) against ${{ inputs.alphagov_repo }}
+
+on:
+  workflow_dispatch:
+    inputs:
+      alphagov_repo:
+        description: 'The alphagov repository to run rubocop-govuk against'
+        required: true
+        type: string
+      git_ref:
+        description: 'Commit, tag or branch name of rubocop-govuk to use'
+        required: true
+        type: string
+        default: 'main'
+
+jobs:
+  lint_project:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Cloning alphagov/${{ inputs.alphagov_repo }}
+        uses: actions/checkout@v3
+        with:
+          repository: alphagov/${{ inputs.alphagov_repo }}
+      - uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+      # We need to turn off deployment mode so that we can modify the gems
+      - run: bundle config unset deployment
+      - run: bundle remove rubocop-govuk
+      # There is a `bundle add --github --ref` command we could have used,
+      # however the output of that falls foul of our linter (how ironic).
+      # Instead of fighting/correcting/accepting that we have this work
+      # around of amending the gemfile ourselves and running bundle install
+      # again.
+      - name: Amending gemfile for rubocop-govuk (${{ inputs.git_ref }})
+        run: |
+          printf '\ngem "rubocop-govuk", github: "alphagov/rubocop-govuk", ref: "${{ inputs.git_ref }}"\n' >> Gemfile
+      - name: Install rubcop-govuk gem
+        run: bundle install
+      - name: Run rubocop
+        run: |
+          # preserve exit code if rubocop fails
+          set -o pipefail
+          # use tee to output to stdout and populate GitHub summary
+          bundle exec rubocop --format markdown | tee $GITHUB_STEP_SUMMARY

CONTRIBUTING.md

@@ -29,11 +29,7 @@ RuboCop GOV.UK is a styleguide, so each rule in each YAML file should have a com
 
 Find out how much effort it will be to adopt your changes in typical GOV.UK repos. This could just be running `rubocop -A` to autocorrect new issues, or it could involve significant manual effort.
 
-You can test changes locally by tweaking the Gemfile or `.gemspec` for the repo e.g.
-
-```
-gem "rubocop-govuk", path: "/govuk/rubocop-govuk"
-```
+You can test changes against an alphagov repo by [running the GitHub worflow](https://github.com/alphagov/rubocop-govuk/actions/workflows/run-against-project.yml) we have configured.
 
 This is a rough list of typical GOV.UK repos we recommend testing against: