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
Credit
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'

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

How can I trigger a run?

If you want to be able to trigger the action manually, you make it respond to repository_dispatch events:

on:
  schedule:
    - cron: '0 0 * * 0'
  repository_dispatch:
    types: [scala-steward]

Then, you can call the trigger from your local machine with:

# Change `owner/repo` to your own repository
curl -d "{\"event_type\": \"scala-steward\"}" \
    -H "Content-Type: application/json" \
    -H "Authorization: token ${GITHUB_TOKEN}" \
    "https://api.github.com/repos/owner/repo/dispatches"

Remember to have a valid github token exported as GITHUB_TOKEN in your local environment:
export GITHUB_TOKEN="your_github_token"

Configuration

The following inputs are available:

Input	Allowed values	Required	Default	Description
`repos-file`	File paths	no	''	Path to a file containing the list of repositories to update in markdown format (- owner/repo)
`github-repository`	{{owner}}/{{repo}}	no	$GITHUB_REPOSITORY	Repository to update. The current repository will be used by default
`github-token`	Valid Github Token	yes	''	Github Personal Access Token with permission to create branches on repo
`author-email`	Email address	no	Github user's Public email	Author email address to use in commits
`author-name`	String	no	Github user's Name	Author name to use in commits
`scala-steward-version`	Valid Scala Steward's version	no	0.6.0	Scala Steward version to use
`ignore-opts-files`	true/false	no	true	Whether to ignore "opts" files (such as `.jvmopts` or `.sbtopts`) when found on repositories or not
`sign-commits`	true/false	no	false	Whether to sign commits or not
`cache-ttl`	like 24hours, 5min, 10s, or 0s	no	2hours	TTL of cache for fetching dependency versions and metadata

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@v1.3.0
  with:
    java-version: 1.11

Github Token

You will need to generate a Github Personal Access Token with permissions for reading/writing in the repository/repositories you wish to update.
Add it as a secret repository.
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.ADMIN_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 using 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.ADMIN_GITHUB_TOKEN }}
    author-email: 12345+octocat@users.noreply.github.com

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.ADMIN_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 would need to perform the following steps:

Create a markdown 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.ADMIN_GITHUB_TOKEN }}
    repos-file: 'repos.md'

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

GPG

If you want commits created by Scala Steward to be automatically signed with a GPG key, follow this 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.ADMIN_GITHUB_TOKEN }}
    sign-commits: true

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.ADMIN_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.ADMIN_GITHUB_TOKEN }}
    ignore-opts-files: false

Credit

All the credit goes to fthomas for creating such an awesome tool as Scala Steward

License

Scala Steward Action is licensed under the Apache License, Version 2.0.

laughedelic / scala-steward-action