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

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:

Create a new GitHub App. To do so, follow the GitHub's 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
5. 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.
Install the App for the repo in which you're setting up this Action.
1. At the App Settings (see step 1.iv.a of this tutorial on how to access it), 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), you'll be able to use this App to power this Action with any repo which that account owns.
3. Click "Install".
Copy the App id and the App private key into a text file for usage in the next step of this tutorial. Both of them can be accessed from your App's Settings (see step 1.iv.a of this tutorial).
1. App id is available in the "About" section of the Settings.
2. 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. Open that file 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-----.
Create repo secrets for the private key and the app id in the repository where you're installing 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. At the "Value" text area, paste the private key you copied at step (3.ii) of this tutorial. Click "Add Secret".
3. Repeat the previous steps (4.i-4.ii) to add a secret for the app id. Specify APP_ID as the name. For the value, paste the app id you copied at the step (3.i) of this tutorial.
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:

# 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: Generate token
        id: generate-token
        uses: tibdex/github-app-token@v1
        with:
          app_id: ${{ secrets.APP_ID }}
          private_key: ${{ secrets.APP_PRIVATE_KEY }}

      - name: Launch Scala Steward
        uses: scala-steward-org/scala-steward-action@v2
        with:
          github-token: ${{ steps.generate-token.outputs.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.15.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

Alternative Options for the GitHub Token

If for some reason the token provided by the GitHub App (as described in the Usage section) doesn't work for you, you can use a default GitHub Action token or a personal one.

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

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

Update targets

By deafult, this GitHub Action updates the default branch of the repo where it runs. This, however, can be changed, as specified below.

Updating a different repository

To update a repository other than the one where the Action runs, 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

Using a file to list repositories

You can specify a list of multiple repositories to update in a markdown file.

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.

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.

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.

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} 💻	_{Anatolii Kmetiuk} 📖	_{Antonio Gelameris} 💻	_{Arman Bilge} 🐛 💻	_{Elias Court} 💻
_{Ewout ter Hoeven} 💻	_{Francis De Brabandere} 🐛	_{Frank Thomas} 💻	_{Jamie Shiell} 🐛	_{Jeff Boutotte} 💻	_{Jyrki Hokkanen} 🐛	_{Leo Benkel} 🐛
_{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 💻	_yokra 📖

This project follows the all-contributors specification. Contributions of any kind welcome!

License

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

Name		Name	Last commit message	Last commit date
Latest commit History 947 Commits
.github		.github
data/images		data/images
src		src
tests		tests
.all-contributorsrc		.all-contributorsrc
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
LICENSE		LICENSE
README.md		README.md
action.yml		action.yml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Scala Steward Github Action

What does this action do?

Usage

How can I trigger a run?

Configuration

Specify JVM version

Alternative Options for the GitHub Token

Using the default Github Action Token

Using a Personal Access Token

Update targets

Updating a different repository

Using a file to list repositories

Updating a custom branch

GPG

Ignoring OPTS files

Run Scala Steward in debug mode

Contributors

License

About

Releases

Packages

Languages

License

sbuild-ci/scala-steward-action

Folders and files

Latest commit

History

Repository files navigation

Scala Steward Github Action

What does this action do?

Usage

How can I trigger a run?

Configuration

Specify JVM version

Alternative Options for the GitHub Token

Using the default Github Action Token

Using a Personal Access Token

Update targets

Updating a different repository

Using a file to list repositories

Updating a custom branch

GPG

Ignoring OPTS files

Run Scala Steward in debug mode

Contributors

License

About

Resources

License

Code of conduct

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages