Scala Steward Github Action

A Github Action to launch Scala Steward in your repository.

What does this action do?
Usage
- How can I trigger a run?
Configuration
Contributors
License

What does this action do?

When added, this action will launch Scala Steward on your own repository and create PRs to update your Scala dependencies using your own user:

Usage

Create a new .github/workflows/scala-steward.yml file:

# This workflow will launch at 00:00 every Sunday
on:
  schedule:
    - cron: '0 0 * * 0'

name: Launch Scala Steward

jobs:
  scala-steward:
    runs-on: ubuntu-latest
    name: Launch Scala Steward
    steps:
      - name: Launch Scala Steward
        uses: scala-steward-org/scala-steward-action@v2
        with:
          github-token: ${{ secrets.REPO_GITHUB_TOKEN }}

How can I trigger a run?

You can manually trigger workflow runs using the workflow_dispatch event:

on:
  schedule:
    - cron: '0 0 * * 0'
  workflow_dispatch:

Once you added this trigger Github will show a "Run workflow" button at the workflow page.

Configuration

The following inputs are available (all of them are optional):

Input (click on name for description)	Allowed values	Default
`repos-file` Path to a file containing the list of repositories to update in markdown format (- owner/repo)	File paths	`''`
`github-repository` Repository to update. The current repository will be used by default	{{owner}}/{{repo}}	`$GITHUB_REPOSITORY`
`github-token` Github Personal Access Token with permission to create branches on repo (or `${{ secrets.GITHUB_TOKEN }}`)	Valid Github Token	`''`
`author-email` Author email address to use in commits	Email address	Github user's Public email
`author-name` Author name to use in commits	String	Github user's Name
`scala-steward-version` Scala Steward version to use	Valid Scala Steward's version	`0.14.0`
`ignore-opts-files` Whether to ignore "opts" files (such as `.jvmopts` or `.sbtopts`) when found on repositories or not	true/false	`true`
`sign-commits` Whether to sign commits or not	true/false	`false`
`signing-key` Key ID of signing key to use for signing commits. Analogous to git's `user.signingkey` configuration setting.	Signing key ID	' '
`cache-ttl` TTL of cache for fetching dependency versions and metadata. Set it to `0s` to disable cache completely.	like 24hours, 5min, 10s, or 0s	`2hours`
`timeout` Timeout for external process invocations.	like 2hours, 5min, 10s, or 0s	`20min`
`github-api-url` The URL of the Github API, only use this input if you are using Github Enterprise	https://git.yourcompany.com/api/v3	`https://api.github.com`
`coursier-cli-url` The Url to download the coursier CLI from.	Valid Url to install coursier CLI from	`https://git.io/coursier-cli-linux`
`scalafix-migrations` Scalafix migrations to run when updating dependencies. Check here for more information.	Path to HOCON file or remote URL with migration	`''`
`artifact-migrations` Artifact migrations to find newer dependency updates. Check here for more information.	Path to HOCON file with migration	`''`
`github-app-id` This input in combination with `github-app-key` allows you to use this action as a "backend" for your own Scala Steward GitHub App.	A valid GitHub App ID	`''`
`github-app-key` The private key for the GitHub App set with `github-app-id`. This value should be extracted from a secret. This input in combination with `github-app-id` allows you to use this action as a "backend" for your own Scala Steward GitHub App.	A private key	`''`
`branches` A comma-separated list of branches to update (if not provided, the repository's default branch will be updated instead). This option only has effect if updating the current repository or using the `github-repository` input. See "Updating a custom branch".	A list of branches to update	`''`
`repo-config` The path to a `.scala-steward.conf` file with default values for all repos updated with this action.	Path to a `.scala-steward.conf` default file	`.github/.scala-steward.conf`
`other-args` Other arguments to launch Scala Steward with	String	`''`

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:

- name: Set up JDK 11
  uses: actions/setup-java@v3
  with:
    java-version: 11
    distribution: temurin

Github Token

There are several options for the Github Token:

Using the default Github Action Token

By default, the action will use the default GitHub Token if none is provided via github-token.

Beware that if you use the default github-token no workflows will run on Scala Steward PRs.

Using a Personal Access Token

You will need to generate a Github Personal Access Token with repo permissions for reading/writing in the repository/repositories you wish to update.
Add it as a repository secret.
Provide it to the action using github-token input:

- name: Launch Scala Steward
  uses: scala-steward-org/scala-steward-action@v2
  with:
    github-token: ${{ secrets.REPO_GITHUB_TOKEN }}

Note on Github User account

The Github Personal Access Token can be created under your own Github user account, or under a separate account that has Collaborator permission in the repository/repositories you wish to update.

Make sure the account you choose has Name and Public email fields defined in Public Profile -- they will be used by Scala Steward to make commits. If the account has personal email address protection enabled, then you will need to explicitly specify a email to use in commits:

- 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

Using a Github App installation tokens

You can create a Github App with write access, install it in the repositories you want to update and use it to generate installation access tokens. See detailed instructions below.

Updating one repository

To update only one repository we can use the github-repository input. Just set it to the name (owner/repo) of the repository you would like to update.

- name: Launch Scala Steward
  uses: scala-steward-org/scala-steward-action@v2
  with:
    github-token: ${{ secrets.REPO_GITHUB_TOKEN }}
    github-repository: owner/repository

This input isn't required if the workflow launches from the same repository that you wish to update.

Updating multiple repositories

To update multiple repositories you can either maintain the list in a markdown file or use a Github app that you can install in each repository you want to update.

Using a file to list repositories

Create a file containing the list of repositories in markdown format:
```
# repos.md
- owner/repo_1
- owner/repo_2
```
Put that file inside the repository directory (so it is accessible to Scala Steward's action).

Provide it to the action using repos-file:

# Need to checkout to read the markdown file
- uses: actions/checkout@v2
- name: Launch Scala Steward
  uses: scala-steward-org/scala-steward-action@v2
  with:
    github-token: ${{ secrets.REPO_GITHUB_TOKEN }}
    repos-file: 'repos.md'

This input (if present) will always take precedence over github-repository.

Using a Github App to list repositories

You can create your own Scala Steward GitHub App and use this action as a backend for it:

Create a new Github App
The only permission you need for this app is Metadata: read-only. See more detailed setup instructions here.
Once you do that you will get an App ID and will be able to generate a private key file.
Save the content of that private key file to a repository secret.
Add your App ID and your secret to the scala-steward-action:

- name: Launch Scala Steward
  uses: scala-steward-org/scala-steward-action@v2
  with:
    github-token: ${{ secrets.REPO_GITHUB_TOKEN }}
    github-app-id: 123456
    github-app-key: ${{ secrets.APP_PRIVATE_KEY }}

Now Scala Steward will use Github API to list all app installations and run updates on those repositories.

Using a Github App to author pull requests

You can also use a Github App to author update pull requests. It can be the same app as above or a different one. To be able to create branches and pull requests it needs these permissions:

Contents: read & write
Pull requests: read & write

Then you can use an action like tibdex/github-app-token to generate an installation access token and pass it to the scala-steward-action:

- name: Generate token
  id: generate-token
  uses: tibdex/github-app-token@v1
  with:
    app_id: 123456
    private_key: ${{ secrets.APP_PRIVATE_KEY }}

- name: Launch Scala Steward
  uses: scala-steward-org/scala-steward-action@v2
  with:
    # used for authoring updates:
    github-token: ${{ steps.generate-token.outputs.token }}
    author-email: 123456+app-name[bot]@users.noreply.github.com
    author-name: app-name[bot]
    # used for listing repositories (optional, can be a different app):
    github-app-id: 123456
    github-app-key: ${{ secrets.APP_PRIVATE_KEY }}

author-* inputs are optional here: if you don't add them, pull requests will be authored by your app, but commits will be authored by the @github-actions[bot] account. App email is constructed from the app ID, app name and the [bot] suffix (details).
github-app-* inputs are also optional. If you have an app with write access to many repositories, but want to enable Scala Steward only in some of them, then you can use repos-file or another app with minimal permissions just to mark reposities for updates.
The app used to author updates has to be also installed in the repository where the action is running from, otherwise the first step won't be able to generate tokens.

Updating a custom branch

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:

- name: Launch Scala Steward
  uses: scala-steward-org/scala-steward-action@v2
  with:
    github-token: ${{ github.token }}
    branches: main,0.1.x,0.2.x

Take into account that this input is only used if updating the repository where the action is being run or using the github-repository input. For cases where the repos-file input is used, you should follow the instructions here and add multiple lines in the markdown file like:

- repo/owner # updates default branch
- repo/owner:0.1.x # updates 0.1.x branch
- repo/owner:0.2.x # updates 0.2.x branch

To know more about updating multiple repositories using Scala Steward and custom branches, check this blog post.

GPG

If you want commits created by Scala Steward to be automatically signed with a GPG key, follow these steps:

Generate a new GPG key following Github's own tutorial.
Add your new GPG key to your user's Github account following Github's own tutorial.

Export the GPG private key as an ASCII armored version to your clipboard (change joe@foo.bar with your key email address):

# 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

Paste your clipboard as a new GPG_PRIVATE_KEY repository secret.
If the key is passphrase protected, add the passphrase as another repository secret called GPG_PASSPHRASE.

Import it to the workflow using an action such us crazy-max/ghaction-import-gpg:

- 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 }}

Tell Scala Steward to sign commits using the sign-commits input:

- name: Launch Scala Steward
  uses: scala-steward-org/scala-steward-action@v2
  with:
    github-token: ${{ secrets.REPO_GITHUB_TOKEN }}
    sign-commits: true

Tell Scala Steward the key ID of the key to be used for signing commits using the signing-key input:

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
/Users/hubot/.gnupg/secring.gpg
------------------------------------
sec   4096R/3AA5C34371567BD2 2016-03-10 [expires: 2017-03-10]
uid                          Hubot
ssb   4096R/42B317FD4BA89E7A 2016-03-10

Copy the key ID and paste it as the content of a new repository secret, called for example GPG_SIGNING_KEY_ID.

Use the signing-key parameter to allow Scala Steward to use the correct key:

- name: Launch Scala Steward
  uses: scala-steward-org/scala-steward-action@v2
  with:
    github-token: ${{ secrets.REPO_GITHUB_TOKEN }}
    sign-commits: true
    signing-key: ${{ secrets.GPG_SIGNING_KEY_ID }}

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:

- name: Launch Scala Steward
  uses: scala-steward-org/scala-steward-action@v2
  with:
    github-token: ${{ secrets.REPO_GITHUB_TOKEN }}
    sign-commits: true
    author-email: ${{ steps.import_gpg.outputs.email }}
    author-name: ${{ steps.import_gpg.outputs.name }}

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:

- name: Launch Scala Steward
  uses: scala-steward-org/scala-steward-action@v2
  with:
    github-token: ${{ secrets.REPO_GITHUB_TOKEN }}
    ignore-opts-files: false

Run Scala Steward in debug mode

You just need to enable GitHub Actions' "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).

Contributors

Thanks goes to these wonderful people (emoji key):

_{Alejandro Hernández} 💻	_{Alexey Alekhin} 💻	_{Ali Salim Rashid} 💻	_{Antonio Gelameris} 💻	_{Arman Bilge} 🐛 💻	_{Ewout ter Hoeven} 💻	_{Francis De Brabandere} 🐛
_{Frank Thomas} 💻	_{Jamie Shiell} 🐛	_{Jeff Boutotte} 💻	_{Marcelo Carlos} 🐛	_{Matthew Tovbin} 💻	_{Michele Pinto} 🤔	_{Milan van der Meer} 🐛
_{Pavel Boldyrev} 💻	_{Stefanos Pliakos} 🤔	_{TATSUNO Yasuhiro} 💻	_{Takumi Kadowaki} 💻	_{Victor Sollerhed} 💻	_{Yannick Heiber} 💻	_{kenji yoshida} 💻
_ryota0624 💻