If you are creating a GitHub App for your personal account, just click here 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 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 👇

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 just download it to a folder in your computer and upload it back using the input. Then set "Badge background color" to #3d5a80

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.

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.

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-4.2) 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-4.2) to add a secret for the installation id you recover on step (3.3). Specify APP_INSTALLATION_ID as the name.

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:

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

name: Launch Scala Steward

jobs:
  scala-steward:
    runs-on: ubuntu-22.04
    name: Launch Scala Steward
    steps:
      - 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 }}

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.

When it launches it will send PR to update all the repos selected in step (2.2).

You can manually trigger workflow runs using the workflow_dispatch event:

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

If you would like to specify a specific Java version (e.g Java 11) please add the following step before Launch Scala Steward step:

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

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

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

- 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

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:

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

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

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.

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:

- 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

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-app-id: ${{ secrets.APP_ID }}
    github-app-installation-id: ${{ secrets.APP_INSTALLATION_ID }}
    github-app-key: ${{ secrets.APP_PRIVATE_KEY }}
    ignore-opts-files: false

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

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.

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, which may provide a helpful example if you need to do that in your own organisation.

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. Also beware that if you use the default github-token no workflows will run on Scala Steward PRs. If you still want to use it you just need to remove all the github-app-* inputs and follow either the Updating a specific repository or the Update specific repositories (listed on a file) guides to provide a repository to update.

Example updating the current repository with the default GitHub Token

- name: Launch Scala Steward
  uses: scala-steward-org/scala-steward-action@v2

Example updating a specific repository with the default GitHub Token

- name: Launch Scala Steward
  uses: scala-steward-org/scala-steward-action@v2
  with:
    github-repository: owner/repo

Example updating a list of repositories (from a file) with the default GitHub Token

- name: Launch Scala Steward
  uses: scala-steward-org/scala-steward-action@v2
  with:
    github-repository: owner/repo
    repos-file: 'repos.md'

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 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.
4. Provide the token to the action using the github-token input.

Example updating the current repository with the default GitHub Token

- 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

- 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

- 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 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, as 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 an 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: [email protected]

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.
2. Add your new GPG key to your user's GitHub account following GitHub's own tutorial.
3. Export the GPG private key as an ASCII armored version to your clipboard (change [email protected] with your key email address):

# macOS
gpg --armor --export-secret-key [email protected] | pbcopy

# Ubuntu (assuming GNU base64)
gpg --armor --export-secret-key [email protected] -w0 | xclip

# Arch
gpg --armor --export-secret-key [email protected] | sed -z 's;\n;;g' | xclip -selection clipboard -i

# FreeBSD (assuming BSD base64)
gpg --armor --export-secret-key [email protected] | 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:

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

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

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