Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update GitHub Actions guide to include setup-sbt action #1274

Merged
merged 2 commits into from
Jan 11, 2025
Merged

Update GitHub Actions guide to include setup-sbt action #1274

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
def5327
Update GH actions instructions to include sbt setup
stringbean Jan 8, 2025
8090a32
Update sbt version in docs
stringbean Jan 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
182 changes: 101 additions & 81 deletions ...nce/02-DetailTopics/05-Plugins-and-Best-Practices/04-GitHub-Actions-with-sbt.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ out: GitHub-Actions-with-sbt.html
[GA]: https://docs.github.com/en/free-pro-team@latest/actions
[GA-Reference]: https://docs.github.com/en/free-pro-team@latest/actions/reference
[Setup-Java]: https://github.com/actions/setup-java
[Setup-sbt]: https://github.com/sbt/setup-sbt
[GA-Matrix]: https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-syntax-for-github-actions#jobsjob_idstrategy
[sbt-github-actions]: https://github.com/sbt/sbt-github-actions

Expand Down Expand Up @@ -33,7 +34,8 @@ Use this guide as an inspiration, but consult the official source for more detai

### Basic setup

Setting up your build for GitHub Actions is mostly about setting up `.github/workflows/ci.yml`. Here's what a minimal CI workflow could look like using [setup-java][Setup-Java]:
To build an sbt project on GitHub Actions you will need to config Java (using [actions/setup-java][Setup-Java]) and an sbt launcher
(using [actions/setup-sbt][Setup-sbt]). A minimal CI workflow for running tests would look something like:

```yml
name: CI
Expand All @@ -44,20 +46,30 @@ jobs:
test:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup JDK
uses: actions/setup-java@v3
with:
distribution: temurin
java-version: 8
- name: Build and Test
run: sbt -v +test
- name: Checkout
uses: actions/checkout@v4
- name: Setup JDK
uses: actions/setup-java@v4
with:
distribution: temurin
java-version: 11
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it is good to specify sbt caching: https://github.com/actions/setup-java#caching-packages-dependencies
It's use like this here, e.g.: https://github.com/sbt/sbt-native-packager/blob/main/.github/workflows/validate-pr.yml#L19-L24

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is already a section on caching on that page that talks about adding that exact option.

The whole page could do with a full rewrite to bring it up date but that can be done on the new docs site. For now I wanted to do a quick update so that the examples work.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, my bad I was only looking at the diff 🙈

- name: Setup sbt launcher
uses: sbt/setup-sbt@v1
- name: Build and Test
run: sbt +test
```

### Custom JVM options

The default JVM options are provided by the official sbt runner adopted by [setup-java][Setup-Java], and it should work for most cases. If you do decide to customize it, use `-v` option to let the script output the current options first:
The default JVM options provided by the sbt runner installed by actions/setup-sbt should work for most cases. If you do decide to customize it,
add the `-v` parameter to your sbt call to enable verbose output:

```yml
- name: Build and Test (with debug)
run: sbt -v +test
```

This will cause the Java command line to be logged along with the JVM arguments:

```
# Executing command line:
Expand All @@ -82,26 +94,27 @@ jobs:
test:
runs-on: ubuntu-latest
env:
# define Java options for both official sbt and sbt-extras
JAVA_OPTS: -Xms2048M -Xmx2048M -Xss6M -XX:ReservedCodeCacheSize=256M -Dfile.encoding=UTF-8
JVM_OPTS: -Xms2048M -Xmx2048M -Xss6M -XX:ReservedCodeCacheSize=256M -Dfile.encoding=UTF-8
JVM_OPTS: -Xms2048M -Xmx2048M -Xss6M -XX:ReservedCodeCacheSize=256M -Dfile.encoding=UTF-8
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup JDK
uses: actions/setup-java@v3
with:
distribution: temurin
java-version: 8
- name: Build and Test
run: sbt -v +test
- name: Checkout
uses: actions/checkout@v4
- name: Setup JDK
uses: actions/setup-java@v4
with:
distribution: temurin
java-version: 11
- name: Setup sbt launcher
uses: sbt/setup-sbt@v1
- name: Build and Test
run: sbt -v +test
```

Again, let's check the log to see if the flags are taking effect:

```
# Executing command line:
[process_args] java_version = '8'
[process_args] java_version = '11'
java
-Xms2048M
-Xmx2048M
Expand All @@ -124,11 +137,13 @@ To use it, set the input parameter `cache` of the action `setup-java` to the val

```yml
- name: Setup JDK
uses: actions/setup-java@v3
uses: actions/setup-java@v4
with:
distribution: temurin
java-version: 8
cache: sbt
- name: Setup sbt launcher
uses: sbt/setup-sbt@v1
- name: Build and test
run: sbt -v +test
```
Expand Down Expand Up @@ -167,16 +182,18 @@ jobs:
java: 17
runs-on: \${{ matrix.os }}
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup JDK
uses: actions/setup-java@v3
with:
distribution: temurin
java-version: \${{ matrix.java }}
- name: Build and test
shell: bash
run: sbt -v +test
- name: Checkout
uses: actions/checkout@v4
- name: Setup JDK
uses: actions/setup-java@v4
with:
distribution: temurin
java-version: \${{ matrix.java }}
- name: Setup sbt launcher
uses: sbt/setup-sbt@v1
- name: Build and test
shell: bash
run: sbt -v +test
```

Note that there's nothing magical about the `os` or `java` keys in the build matrix.
Expand Down Expand Up @@ -207,28 +224,30 @@ jobs:
jobtype: 3
runs-on: \${{ matrix.os }}
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup JDK
uses: actions/setup-java@v3
with:
distribution: temurin
java-version: \${{ matrix.java }}
- name: Build and test (1)
if: \${{ matrix.jobtype == 1 }}
shell: bash
run: |
sbt -v "mimaReportBinaryIssues; scalafmtCheckAll; +test;"
- name: Build and test (2)
if: \${{ matrix.jobtype == 2 }}
shell: bash
run: |
sbt -v "scripted actions/*"
- name: Build and test (3)
if: \${{ matrix.jobtype == 3 }}
shell: bash
run: |
sbt -v "dependency-management/*"
- name: Checkout
uses: actions/checkout@v4
- name: Setup JDK
uses: actions/setup-java@v4
with:
distribution: temurin
java-version: \${{ matrix.java }}
- name: Setup sbt launcher
uses: sbt/setup-sbt@v1
- name: Build and test (1)
if: \${{ matrix.jobtype == 1 }}
shell: bash
run: |
sbt -v "mimaReportBinaryIssues; scalafmtCheckAll; +test;"
- name: Build and test (2)
if: \${{ matrix.jobtype == 2 }}
shell: bash
run: |
sbt -v "scripted actions/*"
- name: Build and test (3)
if: \${{ matrix.jobtype == 3 }}
shell: bash
run: |
sbt -v "dependency-management/*"
```

### Sample .github/workflows/ci.yml setting
Expand Down Expand Up @@ -260,33 +279,34 @@ jobs:
jobtype: 3
runs-on: \${{ matrix.os }}
env:
# define Java options for both official sbt and sbt-extras
JAVA_OPTS: -Xms2048M -Xmx2048M -Xss6M -XX:ReservedCodeCacheSize=256M -Dfile.encoding=UTF-8
JVM_OPTS: -Xms2048M -Xmx2048M -Xss6M -XX:ReservedCodeCacheSize=256M -Dfile.encoding=UTF-8
JVM_OPTS: -Xms2048M -Xmx2048M -Xss6M -XX:ReservedCodeCacheSize=256M -Dfile.encoding=UTF-8
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup JDK
uses: actions/setup-java@v3
with:
distribution: temurin
java-version: \${{ matrix.java }}
cache: sbt
- name: Build and test (1)
if: \${{ matrix.jobtype == 1 }}
shell: bash
run: |
sbt -v "mimaReportBinaryIssues; scalafmtCheckAll; +test;"
- name: Build and test (2)
if: \${{ matrix.jobtype == 2 }}
shell: bash
run: |
sbt -v "scripted actions/*"
- name: Build and test (3)
if: \${{ matrix.jobtype == 3 }}
shell: bash
run: |
sbt -v "dependency-management/*"
- name: Checkout
uses: actions/checkout@v4
- name: Setup JDK
uses: actions/setup-java@v4
with:
distribution: temurin
java-version: \${{ matrix.java }}
cache: sbt
- name: Setup sbt launcher
uses: sbt/setup-sbt@v1
- name: Build and test (1)
if: \${{ matrix.jobtype == 1 }}
shell: bash
run: |
sbt -v "mimaReportBinaryIssues; scalafmtCheckAll; +test;"
- name: Build and test (2)
if: \${{ matrix.jobtype == 2 }}
shell: bash
run: |
sbt -v "scripted actions/*"
- name: Build and test (3)
if: \${{ matrix.jobtype == 3 }}
shell: bash
run: |
sbt -v "dependency-management/*"
```

### sbt-github-actions
Expand Down
4 changes: 2 additions & 2 deletions src/reference/template.properties
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
app_version=1.9.8
windows_app_version=1.9.8
app_version=1.10.7
windows_app_version=1.10.7

color_scheme=github
example_scala_version=2.12.18
Expand Down
Loading