Scala Steward GitHub Action
A GitHub Action to launch Scala Steward in your repository.
Installation
You can use this action for individual repositories or you can configure a repository to manage many repositories.
Simple workflow using default GitHub Actions App
on:
schedule:
- cron: '0 0 * * 0'
name: Scala Steward
permissions:
contents: write
pull-requests: write
jobs:
scala-steward:
runs-on: ubuntu-latest
name: Scala Steward
steps:
- name: Install sbt
uses: sbt/setup-sbt@v1
- name: Scala Steward
uses: scala-steward-org/scala-steward-action@v2See Usage
Note that you won't be able to use any of github-app-*, repos-file, or github-repository inputs as the GitHub Actions App can only possibly write to the current repository.
You will also need to ensure that GitHub Actions has permissions to create and approve pull requests for the organization or repository.
Workflow with a custom GitHub App to manage multiple repositories
To use the Action in your repo, you need to create a GitHub App. Then you need to create a new GitHub Actions workflow file to run this Action. Here is a step-by-step tutorial on how to do it:
1. Create a new GitHub App
If you are creating a GitHub App for your personal account, just click [here][github-app-personal] and it will create one with the base settings already pre-configured. On the other hand, if you are creating the App for an organization account, copy [this url][github-app-organization] and replace `my_org` with the name of your organization. > You will need to rename the App's name to a handler that is not already taken. You can use `scala-steward-{my-github-login}` if you are creating the app for your personal account; otherwise, you can use `scala-steward-{my-org}`. Alternatively, you can follow the official guide for creating a GitHub App :point_down:
Official guide
Follow the GitHub's [Creating a GitHub App](https://docs.github.com/en/developers/apps/building-github-apps/creating-a-github-app) Guide. 1. If you're setting up this Action for an organisation-owned repo, note that the step (1) of the "Creating a GitHub App" Guide tells you how to create an organization-level App. 2. Step (7) of the Guide tells you to specify the homepage – you can write a random URL there. 3. Step (13) of the Guide tells you to specify the Webhook URL - you don't need it. Uncheck the box. 4. Step (15) of the Guide asks you which permissions you want your app to have. Specify the following: - Metadata: Read-only - Pull requests: Read and write - Contents: Read and write
Optional: Upload a profile picture for the newly created App. 1. Locate the newly created App's Settings. To do so, go to the settings of either your personal profile or of that of your organisation (depending on where you created the App), select "Developer Settings" from the side bar, then click "GitHub Apps". Find your app, and click "Edit" next to it. - To access your personal settings, click on your profile icon at the top-right corner of the GitHub interface, click "Settings". - To access the settings of an organisation, click on your profile icon at the top-right, select "Your organizations", find the organisation for which you created an App and click "Settings" for that organisation. 2. In the settings, locate the "Display information" section and press the "Upload a logo" button. 3. If you want to use [Scala Steward's official logo](https://github.com/scala-steward-org/scala-steward/raw/main/data/images/scala-steward-logo-circle-0.png) just download it to a folder in your computer and upload it back using the input. Then set "Badge background color" to `#3d5a80`
2. Install the App
1. At the App Settings, at the sidebar, click the "Public page" button, there, click the green "Install" button. 2. Select whether you'd like to install it account-wide or only for selected repos. If you install it for your entire account (personal or organisation), Scala Steward will try to update every repository in your organization, even if they're not Scala repositories. 3. Click "Install". 4. When the new page opens, find its URL and copy the number behind `https://github.com/settings/installations/`. It is the installation ID, you will need it in the following step.
3. Copy the App ID, the App private key and the installation ID
Locate the App ID, the installation ID and the App private key for usage in the next step of this tutorial. All of them can be accessed from your App's Settings. 1. App ID is available in the "About" section of the Settings. 2. You should have the installation ID from step (2.4). If you didn't copy it, go to the App's settings and click on "Install App" on the left. On the new page you should see the account where you install the app. Click the "gear" icon on the right. When the next page loads, find its URL and copy the number behind `https://github.com/settings/installations/`. That's the installation ID. 3. The private key needs to be generated from the "Private keys" section. Clicking the "Generate private key" button will download a `*.pem` file on your computer. Save that file for the following step.
4. Create repo secrets
Create repo secrets for the private key, the app id and the installation ID in the repository from where you want to run this action. 1. To do so, from the repo's page, click the "Settings" tab. There, select "Secrets" at the sidebar, and click "Actions" at the dropdown menu. Click "New repository secret". 2. At the "Name" field, enter `APP_PRIVATE_KEY`. Then, open the ".pem" file you downloaded at step (3.3) with a text editor, and copy the contents. Make sure to copy everything, including the first line `-----BEGIN RSA PRIVATE KEY-----` and the last line `-----END RSA PRIVATE KEY-----`. Paste it at the "Value" text area. Click "Add Secret". 3. Repeat the previous steps (4.1) to add a secret for the app id you recover on step (3.1). Specify `APP_ID` as the name. 4. Repeat the previous steps (4.1) to add a secret for the installation id you recover on step (3.2). Specify `APP_INSTALLATION_ID` as the name.
5. Create a new GitHub Actions Workflow
Create a new GitHub Actions Workflow file, e.g. `.github/workflows/scala-steward.yml`, in the repo where you're installing this Action. Paste the following content into that file: ```yaml on: schedule: - cron: '0 0 * * 0' name: Launch Scala Steward jobs: scala-steward: runs-on: ubuntu-latest name: Launch Scala Steward steps: - name: Install sbt uses: sbt/setup-sbt@v1 - name: Launch Scala Steward uses: scala-steward-org/scala-steward-action@v2 with: github-app-id: ${{ secrets.APP_ID }} github-app-installation-id: ${{ secrets.APP_INSTALLATION_ID }} github-app-key: ${{ secrets.APP_PRIVATE_KEY }} ```
6. Scala Steward does its magic :tada:
If you have used the default cron expression the workflow will launch at 00:00 every Sunday. If you want to change it to a different schedule, you can check [this page](https://crontab.guru). When it launches it will send PR to update all the repos selected in step (2.2).
Manually triggering a run
You can manually trigger workflow runs using the [workflow_dispatch](https://docs.github.com/en/free-pro-team@latest/actions/reference/events-that-trigger-workflows#workflow_dispatch) event: ```diff on: + workflow_dispatch: schedule: - cron: '0 0 * * 0' name: Launch Scala Steward jobs: scala-steward: runs-on: ubuntu-latest name: Launch Scala Steward steps: - name: Install sbt uses: sbt/setup-sbt@v1 - name: Launch Scala Steward uses: scala-steward-org/scala-steward-action@v2 with: github-app-id: ${{ secrets.APP_ID }} github-app-installation-id: ${{ secrets.APP_INSTALLATION_ID }} github-app-key: ${{ secrets.APP_PRIVATE_KEY }} ``` Once you've added this trigger GitHub will show a "Run workflow" button at the workflow page.
Specify JVM version
If you would like to specify a specific Java version (e.g Java 11) please add the following step before `Launch Scala Steward` step: ```yaml - name: Set up JDK 11 uses: actions/setup-java@v3 with: java-version: 11 distribution: temurin ```
Add JVM options to the running JVM
If you would like to add JVM options (such as `-Xmx`) to the Scala Steward JVM process please add the following to the main `Launch Scala Steward` step: ```yaml - name: Launch Scala Steward uses: scala-steward-org/scala-steward-action@v2 env: JAVA_OPTS: "-XX:+UseG1GC -Xms4G -Xmx4G -Xss2M -XX:MetaspaceSize=512M" ```
Updating a specific repository
When using the `github-app-*` inputs, Scala Steward will always retrieve the list of repositories to update from the App's installation. You can override this by setting `github-app-auth-only` to `'true'`. This way the action will only use the app credentials to authenticate and will update the repository set on the `github-repository` input (defaults to the current repository). ```yaml on: schedule: - cron: '0 0 * * 0' name: Launch Scala Steward jobs: scala-steward: runs-on: ubuntu-latest name: Launch Scala Steward steps: - name: Install sbt uses: sbt/setup-sbt@v1 - name: Launch Scala Steward uses: scala-steward-org/scala-steward-action@v2 with: github-app-id: ${{ secrets.APP_ID }} github-app-installation-id: ${{ secrets.APP_INSTALLATION_ID }} github-app-key: ${{ secrets.APP_PRIVATE_KEY }} github-app-auth-only: 'true' ``` To update a repository other than the one where the Action runs, we can override the `github-repository` input. Just set it to the name (owner/repo) of the repository you would like to update. ```yaml - name: Launch Scala Steward uses: scala-steward-org/scala-steward-action@v2 with: github-app-id: ${{ secrets.APP_ID }} github-app-installation-id: ${{ secrets.APP_INSTALLATION_ID }} github-app-key: ${{ secrets.APP_PRIVATE_KEY }} github-app-auth-only: 'true' github-repository: owner/repo ```
Update specific repositories (listed on a file)
When using the `github-app-*` inputs, Scala Steward will always retrieve the list of repositories to update from the App's installation. You can override this by setting `github-app-auth-only` to `'true'`. This way the action will only use the app credentials to authenticate and will allow other mechanisms for selecting which repository should be updated. For example, you can specify a list of repositories in a markdown file. 1. Create a file containing the list of repositories in markdown format: ```markdown # repos.md - owner/repo_1 - owner/repo_2 ``` 2. Put that file inside the repository directory (so it is accessible to Scala Steward's action). 3. Provide it to the action using `repos-file`: ```yaml - name: Checkout repository so `repos.md` is available uses: actions/checkout@v2 - name: Launch Scala Steward uses: scala-steward-org/scala-steward-action@v2 with: github-app-id: ${{ secrets.APP_ID }} github-app-installation-id: ${{ secrets.APP_INSTALLATION_ID }} github-app-key: ${{ secrets.APP_PRIVATE_KEY }} github-app-auth-only: 'true' repos-file: 'repos.md' ``` > > This input (if present) will always take precedence over `github-repository`.
Update one or more specific branches
> **Important!** This input is only used when using the `github-repository` input (see the "Updating a specific repository" guide). For cases where the `repos-file` input is used (see the "Update specific repositories (listed on a file)" guide), you should follow the instructions [here](https://github.com/scala-steward-org/scala-steward/blob/main/docs/faq.md#can-scala-steward-update-multiple-branches-in-a-repository). > **This input won't have any effect when using a GitHub App for listing the repositories to update.** By default, Scala Steward uses the repository's default branch to make the updates. If you want to customize that behavior, you can use the `branches` input: ```yml - name: Launch Scala Steward uses: scala-steward-org/scala-steward-action@v2 with: github-app-id: ${{ secrets.APP_ID }} github-app-installation-id: ${{ secrets.APP_INSTALLATION_ID }} github-app-key: ${{ secrets.APP_PRIVATE_KEY }} github-app-auth-only: 'true' github-repository: owner/repo branches: main,0.1.x,0.2.x ```
Disable ignoring OPTS files
By default, Scala Steward will ignore "opts" files (such as `.jvmopts` or `.sbtopts`) when found on repositories, if you want to disable this feature, use the `ignore-opts-files` input: ```yaml - name: Launch Scala Steward uses: scala-steward-org/scala-steward-action@v2 with: github-app-id: ${{ secrets.APP_ID }} github-app-installation-id: ${{ secrets.APP_INSTALLATION_ID }} github-app-key: ${{ secrets.APP_PRIVATE_KEY }} ignore-opts-files: false ```
Run Scala Steward with step debug logging
You just need to enable [GitHub Actions' "step debug logging"](https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/enabling-debug-logging#enabling-step-debug-logging) and Scala Steward will start automatically in debug mode too. For this you must set the following secret in the repository that contains the workflow: `ACTIONS_STEP_DEBUG` to `true` (as stated in GitHub's documentation). > Alternatively, if you are re-running a failed job and want to re-run it in debug > mode, follow this tutorial and check `Enable debug logging` before clicking on > `Re-run jobs`. > > 
Running locally to attach a JVM debugger
When debugging the behaviour of Scala Steward, it can be helpful to run Scala Steward locally, while mimicking the settings used by the Scala Steward GitHub Action, so that a debugger can be attached - [the Guardian have notes on how they do that](https://github.com/guardian/scala-steward-public-repos/blob/main/running-locally.md), which may provide a helpful example if you need to do that in your own organisation.
Using a Personal Access Token (instead of the GitHub App)
If for any reason you want to use the default GitHub Token available in GitHub Actions, you won't be able to use the `github-app-*` inputs. If you still want to use it you just need to remove all the `github-app-*` inputs and follow these steps: 1. Generate a [GitHub Personal Access Token](https://github.com/settings/tokens) with `repo` permissions for reading/writing in the repository/repositories you wish to update. 2. Add it as a repository secret. 3. Follow either the `Updating a specific repository` or the `Update specific repositories (listed on a file)` guides to provide a repository to update. 3. Provide the token to the action using the `github-token` input. **Example updating the current repository with the default GitHub Token** ```yaml - name: Launch Scala Steward uses: scala-steward-org/scala-steward-action@v2 with: github-token: ${{ secrets.REPO_GITHUB_TOKEN }} ``` **Example updating a specific repository with the default GitHub Token** ```yaml - name: Launch Scala Steward uses: scala-steward-org/scala-steward-action@v2 with: github-repository: owner/repo github-token: ${{ secrets.REPO_GITHUB_TOKEN }} ``` **Example updating a list of repositories (from a file) with the default GitHub Token** ```yaml - name: Launch Scala Steward uses: scala-steward-org/scala-steward-action@v2 with: github-repository: owner/repo github-token: ${{ secrets.REPO_GITHUB_TOKEN }} repos-file: 'repos.md' ``` Beware that using the Personal Access Token will make it look like it's you who submitted all the PRs. The workaround for this is to create a separate GitHub account for the Action and give it the [Collaborator](https://help.github.com/en/github/setting-up-and-managing-your-github-user-account/inviting-collaborators-to-a-personal-repository) permission in the repository or repositories you wish to update. Make sure the account you choose has *Name* and *Public email* fields defined in its [Public Profile](https://github.com/settings/profile), as they will be used by Scala Steward to make commits. If the account has [personal email address protection](https://help.github.com/en/github/setting-up-and-managing-your-github-user-account/blocking-command-line-pushes-that-expose-your-personal-email-address) enabled, then you will need to explicitly specify an email to use in commits: ```yaml - name: Launch Scala Steward uses: scala-steward-org/scala-steward-action@v2 with: github-token: ${{ secrets.REPO_GITHUB_TOKEN }} author-email: 12345+octocat@users.noreply.github.com ```
Sign commits created by Scala Steward
> Signing commits only take place when using a GitHub Personal Access Token (see the "Using a Personal Access Token (instead of the GitHub App)" guide). If you want commits created by Scala Steward to be automatically signed with a GPG key, follow these steps: 1. Generate a new GPG key following [GitHub's own tutorial](https://help.github.com/en/github/authenticating-to-github/generating-a-new-gpg-key). 2. Add your new GPG key to your [user's GitHub account](https://github.com/settings/keys) following [GitHub's own tutorial](https://help.github.com/en/github/authenticating-to-github/adding-a-new-gpg-key-to-your-github-account). 3. Export the GPG private key as an ASCII armored version to your clipboard (change `joe@foo.bar` with your key email address): ```bash # macOS gpg --armor --export-secret-key joe@foo.bar | pbcopy # Ubuntu (assuming GNU base64) gpg --armor --export-secret-key joe@foo.bar -w0 | xclip # Arch gpg --armor --export-secret-key joe@foo.bar | sed -z 's;\n;;g' | xclip -selection clipboard -i # FreeBSD (assuming BSD base64) gpg --armor --export-secret-key joe@foo.bar | xclip ``` 4. Paste your clipboard as a new `GPG_PRIVATE_KEY` repository secret. 5. If the key is passphrase protected, add the passphrase as another repository secret called `GPG_PASSPHRASE`. 6. Import it to the workflow using an action such us [crazy-max/ghaction-import-gpg](https://github.com/crazy-max/ghaction-import-gpg): ```yaml - name: Import GPG key uses: crazy-max/ghaction-import-gpg@v2 with: git_user_signingkey: true env: GPG_PRIVATE_KEY: ${{ secrets.GPG_PRIVATE_KEY }} PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }} ``` 7. Obtain the key ID for the key that should be used. For instance, in the following example, the GPG key ID is `3AA5C34371567BD2`: ``` $ gpg --list-secret-keys --keyid-format=long ~/.gnupg/secring.gpg ------------------------------------ sec 4096R/3AA5C34371567BD2 2022-01-01 uid My Name ssb 4096R/42B317FD4BA89E7A 2022-01-01 ``` 8. Copy the key ID and paste it as the content of a new repository secret, named `GPG_SIGNING_KEY_ID`. 9. Tell Scala Steward to sign commits using the `sign-commits` input. Use as well the `signing-key` parameter to allow Scala Steward to use the correct key: ```yaml - name: Launch Scala Steward uses: scala-steward-org/scala-steward-action@v2 with: github-token: ${{ secrets.REPO_GITHUB_TOKEN }} signing-key: ${{ secrets.GPG_SIGNING_KEY_ID }} sign-commits: true ``` 10. **Optional**. By default, Scala Steward will use the email/name of the user that created the token added in `github-token`, if you want to override that behavior, you can use `author-email`/`author-name` inputs, for example with the values extracted from the imported private key: ```yaml - name: Import GPG key id: import_gpg uses: crazy-max/ghaction-import-gpg@v2 with: git_user_signingkey: true env: GPG_PRIVATE_KEY: ${{ secrets.GPG_PRIVATE_KEY }} PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }} - name: Launch Scala Steward uses: scala-steward-org/scala-steward-action@v2 with: github-token: ${{ secrets.REPO_GITHUB_TOKEN }} signing-key: ${{ secrets.GPG_SIGNING_KEY_ID }} sign-commits: true author-email: ${{ steps.import_gpg.outputs.email }} author-name: ${{ steps.import_gpg.outputs.name }} ```
