@zio.dev/zio-sbt 0.6.3 → 0.7.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.gitkeep +0 -0
- package/index.md +228 -16
- package/package.json +1 -1
package/.gitkeep
ADDED
|
File without changes
|
package/index.md
CHANGED
|
@@ -5,16 +5,16 @@ title: "ZIO SBT"
|
|
|
5
5
|
|
|
6
6
|
_ZIO SBT_ contains multiple sbt plugins that are useful for ZIO projects. It provides high-level SBT utilities that simplify the development of ZIO applications.
|
|
7
7
|
|
|
8
|
-
[](https://github.com/zio/zio/wiki/Project-Stages)  [](https://github.com/zio/zio/wiki/Project-Stages)  [](https://central.sonatype.com/artifact/dev.zio/zio-sbt-website_2.12_1.0) [](https://central.sonatype.com/repository/maven-snapshots/dev/zio/zio-sbt-website_2.12_1.0/) [](https://javadoc.io/doc/dev.zio/zio-sbt-website_2.12_1.0) [](https://github.com/zio/zio-sbt)
|
|
9
9
|
|
|
10
10
|
## Installation
|
|
11
11
|
|
|
12
12
|
Add the following lines to your `project/plugins.sbt` file:
|
|
13
13
|
|
|
14
14
|
```scala
|
|
15
|
-
addSbtPlugin("dev.zio" % "zio-sbt-ecosystem" % "0.
|
|
16
|
-
addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.
|
|
17
|
-
addSbtPlugin("dev.zio" % "zio-sbt-website" % "0.
|
|
15
|
+
addSbtPlugin("dev.zio" % "zio-sbt-ecosystem" % "0.7.1")
|
|
16
|
+
addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.7.1")
|
|
17
|
+
addSbtPlugin("dev.zio" % "zio-sbt-website" % "0.7.1")
|
|
18
18
|
```
|
|
19
19
|
|
|
20
20
|
Then you can enable them by using the following code in your `build.sbt` file:
|
|
@@ -101,7 +101,7 @@ ZIO SBT CI plugin generates a default GitHub workflow that includes common CI ta
|
|
|
101
101
|
To use ZIO SBT CI plugin, add the following lines to your `plugins.sbt` file:
|
|
102
102
|
|
|
103
103
|
```scala
|
|
104
|
-
addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.
|
|
104
|
+
addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.7.1")
|
|
105
105
|
|
|
106
106
|
resolvers ++= Resolver.sonatypeOssRepos("public")
|
|
107
107
|
```
|
|
@@ -118,12 +118,20 @@ Now you can generate a Github workflow by running the following command:
|
|
|
118
118
|
sbt ciGenerateGithubWorkflow
|
|
119
119
|
```
|
|
120
120
|
|
|
121
|
-
This will generate a GitHub workflow file inside the `.github/workflows` directory, named `ci.yml`. The workflow file contains following default
|
|
121
|
+
This will generate a GitHub workflow file inside the `.github/workflows` directory, named `ci.yml`. The workflow file contains the following default jobs:
|
|
122
122
|
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
123
|
+
| Job | What it does |
|
|
124
|
+
| --- | --- |
|
|
125
|
+
| `build` | Compiles everything, publishes locally, and builds the website |
|
|
126
|
+
| `lint` | Checks the generated workflow is up to date, then runs `sbt lint` |
|
|
127
|
+
| `test` | Runs the test suite across the target Java versions |
|
|
128
|
+
| `update-readme` | Regenerates `README.md` from `docs/index.md` and opens a PR |
|
|
129
|
+
| `ci` | Aggregate gate: succeeds only if the jobs above did. Point branch protection at this one |
|
|
130
|
+
| `release` | Runs `sbt ci-release` on a published release, and on pushes to enabled branches for SNAPSHOTs |
|
|
131
|
+
| `release-docs` | Publishes the docs to npm |
|
|
132
|
+
| `notify-docs-release` | Tells `zio/zio` to rebuild the docs site |
|
|
133
|
+
|
|
134
|
+
Note that the plugin declares `trigger = allRequirements`, so having it on the classpath is enough — `enablePlugins(ZioSbtCiPlugin)` is not strictly required. Its settings are defined at `ThisBuild` level, so set them as `ThisBuild / ciSomething := ...`, or inside `inThisBuild(...)`.
|
|
127
135
|
|
|
128
136
|
> **Note:**
|
|
129
137
|
>
|
|
@@ -159,6 +167,210 @@ The default value mirrors the bots used by the `zio/zio` repository: `Seq(Depend
|
|
|
159
167
|
>
|
|
160
168
|
> For `gh pr merge --auto` to actually merge a PR (rather than just queue it), the target repository needs "Allow auto-merge" enabled under **Settings → General**, and branch protection with required status checks configured on the target branch.
|
|
161
169
|
|
|
170
|
+
### Keeping the Workflow in Sync
|
|
171
|
+
|
|
172
|
+
The generated files are meant to be committed and never edited by hand. To stop them drifting from the build, run the check in CI — the default `lint` job already does:
|
|
173
|
+
|
|
174
|
+
```bash
|
|
175
|
+
sbt ciCheckGithubWorkflow
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
It regenerates the workflows and fails if the result differs from what is committed, naming the files that are stale. If a generated file is edited directly, the next run of this check fails, which is what keeps `build.sbt` the single source of truth.
|
|
179
|
+
|
|
180
|
+
### Settings Reference
|
|
181
|
+
|
|
182
|
+
All settings are `ThisBuild`-scoped.
|
|
183
|
+
|
|
184
|
+
**Workflow-level**
|
|
185
|
+
|
|
186
|
+
| Setting | Type | Default | Description |
|
|
187
|
+
| --- | --- | --- | --- |
|
|
188
|
+
| `ciWorkflowTitle` | `String` | `"CI"` | Workflow name, lowercased to form the filename (`ci.yml`). Named this way to avoid colliding with zio-sbt-website's `ciWorkflowName`, which sets the README badge |
|
|
189
|
+
| `ciEnabledBranches` | `Seq[String]` | `Seq.empty` | Branches the workflow runs on. Empty means every branch |
|
|
190
|
+
| `ciWorkflowEnv` | `Map[String, String]` | derived from `ciJvmOptions`/`ciNodeOptions` | Workflow-level environment. Assigning **replaces** the derived map, which is how a build opts out of `JDK_JAVA_OPTIONS` |
|
|
191
|
+
| `ciJvmOptions` | `Seq[String]` | `Seq.empty` | Appended to `JDK_JAVA_OPTIONS` |
|
|
192
|
+
| `ciNodeOptions` | `Seq[String]` | `Seq.empty` | Sets `NODE_OPTIONS` when non-empty |
|
|
193
|
+
| `ciConcurrency` | `Option[Concurrency]` | one run per branch, cancelling in progress | Concurrency group, or `None` to omit the block |
|
|
194
|
+
| `ciSwapSizeGB` | `Int` | `0` | Adds a swap-space step to every job when greater than zero |
|
|
195
|
+
| `ciBackgroundJobs` | `Seq[String]` | `Seq.empty` | Commands prefixed to each `run`, for daemons a job needs |
|
|
196
|
+
|
|
197
|
+
**Test matrix**
|
|
198
|
+
|
|
199
|
+
| Setting | Type | Default | Description |
|
|
200
|
+
| --- | --- | --- | --- |
|
|
201
|
+
| `ciTargetJavaVersions` | `Seq[String]` | `Seq("17", "21", "25")` | Java versions in the test matrix |
|
|
202
|
+
| `ciDefaultJavaVersion` | `String` | `"17"` | Java version for the non-matrix jobs |
|
|
203
|
+
| `ciTargetScalaVersions` | `Map[String, Seq[String]]` | `Map.empty` | Module to Scala versions. Empty runs a plain `sbt +test` |
|
|
204
|
+
| `ciTargetMinJavaVersions` | `Map[String, String]` | `Map.empty` | Module to minimum Java version, gating modules per matrix entry |
|
|
205
|
+
| `ciGroupSimilarTests` | `Boolean` | `false` | Groups by Java and Scala version instead of one entry per module |
|
|
206
|
+
| `ciMatrixMaxParallel` | `Option[Int]` | `None` | `strategy.max-parallel` |
|
|
207
|
+
|
|
208
|
+
**Jobs and steps**
|
|
209
|
+
|
|
210
|
+
| Setting | Type | Default | Description |
|
|
211
|
+
| --- | --- | --- | --- |
|
|
212
|
+
| `ciBuildJobs` | `Seq[Job]` | one `build` job | Replaces or extends the build jobs |
|
|
213
|
+
| `ciLintJobs` | `Seq[Job]` | one `lint` job | |
|
|
214
|
+
| `ciTestJobs` | `Seq[Job]` | one `test` job | |
|
|
215
|
+
| `ciUpdateReadmeJobs` | `Seq[Job]` | one `update-readme` job | Set to `Seq.empty` if the README is maintained by hand |
|
|
216
|
+
| `ciReleaseJobs` | `Seq[Job]` | one `release` job | |
|
|
217
|
+
| `ciPostReleaseJobs` | `Seq[Job]` | `release-docs`, `notify-docs-release` | |
|
|
218
|
+
| `ciPullRequestApprovalJobs` | `Seq[String]` | the ids of `ciLintJobs`, `ciTestJobs` and `ciBuildJobs` | Job ids the aggregate `ci` job waits on. Follows the jobs those three settings produce, so renaming or adding one is picked up without touching this |
|
|
219
|
+
| `ciReleaseApprovalJobs` | `Seq[String]` | `Seq("ci")` | Job ids the release waits on |
|
|
220
|
+
| `ciCheckArtifactsCompilationSteps` | `Seq[Step]` | `sbt +Test/compile` | |
|
|
221
|
+
| `ciCheckArtifactsBuildSteps` | `Seq[Step]` | `sbt +publishLocal` | |
|
|
222
|
+
| `ciCheckWebsiteBuildProcess` | `Seq[Step]` | `sbt docs/buildWebsite` | Set to `Seq.empty` in a build with no `docs` project |
|
|
223
|
+
| `ciCheckGithubWorkflowSteps` | `Seq[Step]` | `sbt ciCheckGithubWorkflow` | |
|
|
224
|
+
|
|
225
|
+
**Release and docs**
|
|
226
|
+
|
|
227
|
+
| Setting | Type | Default | Description |
|
|
228
|
+
| --- | --- | --- | --- |
|
|
229
|
+
| `ciPublishSnapshots` | `Boolean` | `true` | Also publish SNAPSHOTs on pushes to enabled branches |
|
|
230
|
+
| `ciUpdateReadmeCondition` | `Option[Condition]` | `None` | When to run the README job. Defaults to published releases |
|
|
231
|
+
| `ciDocsVersioningScheme` | `DocsVersioning` | `SemanticVersioning` | `SemanticVersioning` or `HashVersioning` |
|
|
232
|
+
| `ciDependencyUpdateBots` | `Seq[DependencyBot]` | Dependabot, Renovate, `ScalaSteward("zio-scala-steward")` | Bots whose PRs are auto-approved and auto-merged |
|
|
233
|
+
|
|
234
|
+
**Tasks**
|
|
235
|
+
|
|
236
|
+
| Task | Description |
|
|
237
|
+
| --- | --- |
|
|
238
|
+
| `ciGenerateGithubWorkflow` | Writes `ci.yml`, `auto-approve.yml` and `auto-merge.yml` |
|
|
239
|
+
| `ciCheckGithubWorkflow` | Regenerates and fails if the committed files are stale |
|
|
240
|
+
| `ciGenerateAutoApproveWorkflow` | Writes `auto-approve.yml` only |
|
|
241
|
+
| `ciGenerateAutoMergeWorkflow` | Writes `auto-merge.yml` only |
|
|
242
|
+
|
|
243
|
+
### Customizing Jobs
|
|
244
|
+
|
|
245
|
+
Jobs are values, so they can be transformed or replaced. The types live in `zio.sbt.githubactions` and the reusable steps in `zio.sbt.ZioSbtCiPlugin`; neither is exported through `autoImport`, so import them explicitly.
|
|
246
|
+
|
|
247
|
+
To adjust the generated jobs, map over them:
|
|
248
|
+
|
|
249
|
+
```scala
|
|
250
|
+
import zio.sbt.githubactions.Job
|
|
251
|
+
|
|
252
|
+
def onUbuntu22(job: Job): Job = job.copy(runsOn = "ubuntu-22.04")
|
|
253
|
+
|
|
254
|
+
inThisBuild(
|
|
255
|
+
List(
|
|
256
|
+
ciTestJobs := ciTestJobs.value.map(onUbuntu22),
|
|
257
|
+
ciBuildJobs := ciBuildJobs.value.map(onUbuntu22)
|
|
258
|
+
)
|
|
259
|
+
)
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
To write one from scratch, build it from the exported steps:
|
|
263
|
+
|
|
264
|
+
```scala
|
|
265
|
+
import zio.sbt.ZioSbtCiPlugin._
|
|
266
|
+
import zio.sbt.githubactions.{Job, Step, Strategy}
|
|
267
|
+
|
|
268
|
+
ciTestJobs := Seq(
|
|
269
|
+
Job(
|
|
270
|
+
id = "integration-test",
|
|
271
|
+
name = "Integration Test",
|
|
272
|
+
jobTimeout = Some(30),
|
|
273
|
+
strategy = Some(Strategy(matrix = Map("java" -> List("17", "21")), failFast = false)),
|
|
274
|
+
steps = Seq(
|
|
275
|
+
Checkout.value,
|
|
276
|
+
SetupJava("17"),
|
|
277
|
+
SetupSBT,
|
|
278
|
+
CacheDependencies,
|
|
279
|
+
Step.SingleStep(name = "Test", run = Some("sbt it:test"))
|
|
280
|
+
)
|
|
281
|
+
)
|
|
282
|
+
)
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
The aggregate `ci` job waits on the ids of whatever `ciLintJobs`, `ciTestJobs` and `ciBuildJobs`
|
|
286
|
+
produce, so replacing `test` with `integration-test` above is enough on its own. Set
|
|
287
|
+
`ciPullRequestApprovalJobs` only to wait on a different set than those three:
|
|
288
|
+
|
|
289
|
+
```scala
|
|
290
|
+
ciPullRequestApprovalJobs := Seq("lint", "integration-test")
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
`Checkout`, `SetupLibuv`, `SetupJava(version)`, `SetupSBT`, `CacheDependencies`, `SetupNodeJs` and `SetSwapSpace` are all available; the ones defined as settings need `.value`.
|
|
294
|
+
|
|
295
|
+
### Job Timeouts
|
|
296
|
+
|
|
297
|
+
A job with no timeout inherits GitHub's default of six hours, which is a long time to wait for a hung build:
|
|
298
|
+
|
|
299
|
+
```scala
|
|
300
|
+
Job(id = "test", name = "Test", jobTimeout = Some(25), steps = ...)
|
|
301
|
+
|
|
302
|
+
// or on an existing job
|
|
303
|
+
ciTestJobs := ciTestJobs.value.map(_.withTimeout(25))
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
> **Note:**
|
|
307
|
+
>
|
|
308
|
+
> `Job` also has an older `timeoutMinutes: Int` field. It predates `jobTimeout` and was accepted but never rendered, so it is deprecated. It is still honoured when set to anything other than its historical default of `30`, so builds that set it keep working.
|
|
309
|
+
|
|
310
|
+
### Concurrency
|
|
311
|
+
|
|
312
|
+
By default one run per branch is kept and in-progress runs are cancelled. `cancelInProgress` accepts an expression as well as a boolean, which is what lets a workflow cancel superseded pull request runs while letting releases finish:
|
|
313
|
+
|
|
314
|
+
```scala
|
|
315
|
+
import zio.sbt.githubactions.{CancelInProgress, Concurrency, Condition}
|
|
316
|
+
|
|
317
|
+
ciConcurrency := Some(
|
|
318
|
+
Concurrency(
|
|
319
|
+
group = "ci-pr-${{ github.event_name == 'pull_request' && github.event.pull_request.number || github.ref }}",
|
|
320
|
+
cancelInProgress = CancelInProgress.When(Condition.Expression("github.event_name == 'pull_request'"))
|
|
321
|
+
)
|
|
322
|
+
)
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
Individual jobs can override it. A release should generally not be cancelled halfway through:
|
|
326
|
+
|
|
327
|
+
```scala
|
|
328
|
+
Job(
|
|
329
|
+
id = "release",
|
|
330
|
+
name = "Release",
|
|
331
|
+
concurrency = Some(
|
|
332
|
+
Concurrency(group = "release-${{ github.ref }}", cancelInProgress = CancelInProgress.Never)
|
|
333
|
+
),
|
|
334
|
+
steps = ...
|
|
335
|
+
)
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
### Service Containers
|
|
339
|
+
|
|
340
|
+
Jobs that need a database can attach a service. `options` carries the raw `docker create` arguments, which is where the health check goes — without one the job races the container and steps can start before it accepts connections:
|
|
341
|
+
|
|
342
|
+
```scala
|
|
343
|
+
import zio.Chunk
|
|
344
|
+
import zio.sbt.githubactions.{ImageRef, Service, ServicePort}
|
|
345
|
+
|
|
346
|
+
Job(
|
|
347
|
+
id = "test",
|
|
348
|
+
name = "Test",
|
|
349
|
+
services = Seq(
|
|
350
|
+
Service(
|
|
351
|
+
name = "postgres",
|
|
352
|
+
image = ImageRef("postgres:16"),
|
|
353
|
+
env = Map("POSTGRES_USER" -> "postgres", "POSTGRES_PASSWORD" -> "postgres"),
|
|
354
|
+
ports = Chunk(ServicePort(5432, 5432)),
|
|
355
|
+
options = Some("--health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5")
|
|
356
|
+
)
|
|
357
|
+
),
|
|
358
|
+
steps = ...
|
|
359
|
+
)
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
`ServicePort(inner, outer)` renders as `inner:outer`, which GitHub reads as `<host>:<container>` — so `inner` is the port a step connects to on `localhost`.
|
|
363
|
+
|
|
364
|
+
### The Workflow Environment
|
|
365
|
+
|
|
366
|
+
By default the workflow exports `JDK_JAVA_OPTIONS`, built from `ciJvmOptions`. That is not always wanted: it makes `java -version` print a note containing commas, which corrupts the cache keys computed by `setup-sbt` and `coursier/cache-action`. Assigning `ciWorkflowEnv` replaces the derived map, so JVM flags can go through `SBT_OPTS` instead:
|
|
367
|
+
|
|
368
|
+
```scala
|
|
369
|
+
ciWorkflowEnv := Map(
|
|
370
|
+
"SBT_OPTS" -> "-XX:+PrintCommandLineFlags -Djava.locale.providers=CLDR,JRE"
|
|
371
|
+
)
|
|
372
|
+
```
|
|
373
|
+
|
|
162
374
|
## ZIO SBT Source
|
|
163
375
|
|
|
164
376
|
ZIO SBT Source is a Scala 2.13 + Scala 3 cross-compiled library that provides utilities for self-documenting example code. It includes the `ExprEval` macro, which captures the source text of expressions at compile time and prints them alongside their evaluated results at runtime.
|
|
@@ -168,7 +380,7 @@ ZIO SBT Source is a Scala 2.13 + Scala 3 cross-compiled library that provides ut
|
|
|
168
380
|
Add the following line to your `libraryDependencies` in `build.sbt`:
|
|
169
381
|
|
|
170
382
|
```scala
|
|
171
|
-
libraryDependencies += "dev.zio" %% "zio-sbt-source" % "0.
|
|
383
|
+
libraryDependencies += "dev.zio" %% "zio-sbt-source" % "0.7.1"
|
|
172
384
|
```
|
|
173
385
|
|
|
174
386
|
### Features
|
|
@@ -274,7 +486,7 @@ Both forms emit `showLineNumbers` in the code fence header, enabling line number
|
|
|
274
486
|
|
|
275
487
|
### Default Testing Strategy
|
|
276
488
|
|
|
277
|
-
The default testing strategy for ZIO SBT CI plugin is to run `sbt +test` on Corretto Java
|
|
489
|
+
The default testing strategy for ZIO SBT CI plugin is to run `sbt +test` on Corretto Java 17, 21 and 25. So this will generate the following job:
|
|
278
490
|
|
|
279
491
|
```yaml
|
|
280
492
|
test:
|
|
@@ -284,12 +496,12 @@ test:
|
|
|
284
496
|
strategy:
|
|
285
497
|
fail-fast: false
|
|
286
498
|
matrix:
|
|
287
|
-
java: ['
|
|
499
|
+
java: ['17', '21', '25']
|
|
288
500
|
steps:
|
|
289
501
|
- name: Install libuv
|
|
290
502
|
run: sudo apt-get update && sudo apt-get install -y libuv1-dev
|
|
291
503
|
- name: Setup Scala
|
|
292
|
-
uses: actions/setup-java@
|
|
504
|
+
uses: actions/setup-java@v5
|
|
293
505
|
with:
|
|
294
506
|
distribution: corretto
|
|
295
507
|
java-version: ${{ matrix.java }}
|
|
@@ -348,7 +560,7 @@ test:
|
|
|
348
560
|
strategy:
|
|
349
561
|
fail-fast: false
|
|
350
562
|
matrix:
|
|
351
|
-
java: ['
|
|
563
|
+
java: ['17', '21', '25']
|
|
352
564
|
scala-project:
|
|
353
565
|
- ++2.12.20 submoduleA
|
|
354
566
|
- ++2.12.20 submoduleB
|
|
@@ -358,7 +570,7 @@ test:
|
|
|
358
570
|
- name: Install libuv
|
|
359
571
|
run: sudo apt-get update && sudo apt-get install -y libuv1-dev
|
|
360
572
|
- name: Setup Scala
|
|
361
|
-
uses: actions/setup-java@
|
|
573
|
+
uses: actions/setup-java@v5
|
|
362
574
|
with:
|
|
363
575
|
distribution: corretto
|
|
364
576
|
java-version: ${{ matrix.java }}
|