running-locally.md

Running locally for debug purposes

If the Scala Steward run is behaving incorrectly in some way, it may be worth running the Scala Steward code locally with Java Remote debugging enabled.

These instructions are adapted from Scala Steward's docs/running.md, doing our best to duplicate the parameters which are setup by the Scala Steward GitHub Action when we run it in our GitHub workflow.

1. Clone Scala Steward's codebase: scala-steward-org/scala-steward. We recommend these alterations to the code:
   • Uncomment the run / javaOptions build.sbt line to enable debugging.
   • Disable actual creation/update of PRs by removing the call to NurtureAlg.nurture()
   • Optionally, filter the repos list to focus on a single repo that you find interesting (eg amigo)
2. Clone this repo, guardian/scala-steward-public-repos, for our scala-steward.conf and REPOSITORIES.md files.
3. Create a workspace folder for Scala Steward to work in, eg. ~/code/scala-steward-workspace
4. Create a blank askpass.sh file (normally this would need to contain a valid user GitHub token, but it appears that's only necessary if the code is actually going to push commits to GitHub).

   touch ~/code/scala-steward-workspace/askpass.sh
   chmod 755 ~/code/scala-steward-workspace/askpass.sh

5. Download a temporary GitHub App private key (a .private-key.pem file) for the GitHub App (only GitHub App Managers for our gu-scala-steward-public-repos app can generate/download new keys for the app). Remember to DELETE THIS KEY when you've finished your debugging work.
6. Enter the sbt console in the Scala Steward project, and execute this sbt command, which uses all the different file resources you just set up (note your file paths won't start /Users/Roberto_Tyley!):

   core/run --do-not-fork --workspace "/Users/Roberto_Tyley/code/scala-steward-workspace" --repos-file "/Users/Roberto_Tyley/code/scala-steward-public-repos/REPOSITORIES.md" --repo-config "/Users/Roberto_Tyley/code/scala-steward-public-repos/scala-steward.conf" --forge-login "gu-scala-steward-public-repos" --git-author-email "108136057+gu-scala-steward-public-repos[bot]@users.noreply.github.com" --github-app-id 214238 --github-app-key-file "/Users/Roberto_Tyley/Downloads/gu-scala-steward-public-repos.2023-06-14.private-key.pem" --git-ask-pass "/Users/Roberto_Tyley/code/scala-steward-workspace/askpass.sh"

7. Attach your debugger - for IntelliJ, note that when running in the IntelliJ sbt shell, a discrete but useful Attach debugger affordance will be shown in the console:

DebuggingScalaSteward.mov