@zio.dev/zio-sbt 0.6.0 → 0.7.0

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.
Files changed (3) hide show
  1. package/.gitkeep +0 -0
  2. package/index.md +258 -16
  3. 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
- [![Production Ready](https://img.shields.io/badge/Project%20Stage-Production%20Ready-brightgreen.svg)](https://github.com/zio/zio/wiki/Project-Stages) ![CI Badge](https://github.com/zio/zio-sbt/workflows/CI/badge.svg) [![Sonatype Releases](https://img.shields.io/nexus/r/https/oss.sonatype.org/dev.zio/zio-sbt-website_2.12.svg?label=Sonatype%20Release)](https://oss.sonatype.org/content/repositories/releases/dev/zio/zio-sbt-website_2.12/) [![Sonatype Snapshots](https://img.shields.io/nexus/s/https/oss.sonatype.org/dev.zio/zio-sbt-website_2.12.svg?label=Sonatype%20Snapshot)](https://oss.sonatype.org/content/repositories/snapshots/dev/zio/zio-sbt-website_2.12/) [![javadoc](https://javadoc.io/badge2/dev.zio/zio-sbt-docs_2.12/javadoc.svg)](https://javadoc.io/doc/dev.zio/zio-sbt-docs_2.12) [![ZIO SBT](https://img.shields.io/github/stars/zio/zio-sbt?style=social)](https://github.com/zio/zio-sbt)
8
+ [![Production Ready](https://img.shields.io/badge/Project%20Stage-Production%20Ready-brightgreen.svg)](https://github.com/zio/zio/wiki/Project-Stages) ![CI Badge](https://github.com/zio/zio-sbt/workflows/CI/badge.svg) [![Sonatype Releases](https://img.shields.io/maven-central/v/dev.zio/zio-sbt-website_2.12_1.0.svg?label=Sonatype%20Release)](https://central.sonatype.com/artifact/dev.zio/zio-sbt-website_2.12_1.0) [![Sonatype Snapshots](https://img.shields.io/maven-metadata/v?metadataUrl=https%3A%2F%2Fcentral.sonatype.com%2Frepository%2Fmaven-snapshots%2Fdev%2Fzio%2Fzio-sbt-website_2.12_1.0%2Fmaven-metadata.xml&label=Sonatype%20Snapshot)](https://central.sonatype.com/repository/maven-snapshots/dev/zio/zio-sbt-website_2.12_1.0/) [![javadoc](https://javadoc.io/badge2/dev.zio/zio-sbt-website_2.12_1.0/javadoc.svg)](https://javadoc.io/doc/dev.zio/zio-sbt-website_2.12_1.0) [![ZIO SBT](https://img.shields.io/github/stars/zio/zio-sbt?style=social)](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.6.0")
16
- addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.6.0")
17
- addSbtPlugin("dev.zio" % "zio-sbt-website" % "0.6.0")
15
+ addSbtPlugin("dev.zio" % "zio-sbt-ecosystem" % "0.7.0")
16
+ addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.7.0")
17
+ addSbtPlugin("dev.zio" % "zio-sbt-website" % "0.7.0")
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.6.0")
104
+ addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.7.0")
105
105
 
106
106
  resolvers ++= Resolver.sonatypeOssRepos("public")
107
107
  ```
@@ -118,17 +118,259 @@ 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 Jobs:
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
- - Build
124
- - Lint
125
- - Test
126
- - Update Readme
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
  >
130
138
  > To use this plugin, we also need to install [ZIO Assistant](https://github.com/apps/zio-assistant) bot.
131
139
 
140
+ ### Auto-Approving and Auto-Merging Dependency Update PRs
141
+
142
+ Besides `ci.yml`, the `ciGenerateGithubWorkflow` task also generates two more workflow files: `auto-approve.yml` and `auto-merge.yml`. These workflows automatically approve and enable GitHub's native auto-merge (squash strategy) on pull requests opened by dependency-update bots, such as [Scala Steward](https://github.com/scala-steward-org/scala-steward), [Dependabot](https://github.com/dependabot), and [Renovate](https://github.com/renovatebot/renovate).
143
+
144
+ Both workflows trigger on `pull_request_target` and also support `workflow_dispatch`, which backfills the approval/auto-merge on every currently open PR from the configured bots—handy for recovering PRs that were opened before the workflow existed, or after a workflow bug is fixed.
145
+
146
+ The set of trusted bots is controlled by the `ciDependencyUpdateBots` setting, which takes a `Seq[DependencyBot]`:
147
+
148
+ ```scala
149
+ import zio.sbt.githubactions.DependencyBot
150
+
151
+ ciDependencyUpdateBots := Seq(
152
+ DependencyBot.Dependabot,
153
+ DependencyBot.Renovate,
154
+ DependencyBot.ScalaSteward("zio-scala-steward"),
155
+ DependencyBot.Custom("some-other-bot[bot]")
156
+ )
157
+ ```
158
+
159
+ - `DependencyBot.Dependabot` — matches login `dependabot[bot]`
160
+ - `DependencyBot.Renovate` — matches login `renovate[bot]`
161
+ - `DependencyBot.ScalaSteward(githubAppName)` — matches login `<githubAppName>[bot]`, where `githubAppName` is the name of the GitHub App you registered for Scala Steward
162
+ - `DependencyBot.Custom(login)` — matches any exact GitHub login, for bots not covered by the predefined cases
163
+
164
+ The default value mirrors the bots used by the `zio/zio` repository: `Seq(DependencyBot.Dependabot, DependencyBot.Renovate, DependencyBot.ScalaSteward("zio-scala-steward"))`. If your Scala Steward GitHub App has a different name, override the setting with the correct `ScalaSteward` app name.
165
+
166
+ > **Note:**
167
+ >
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.
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
+
132
374
  ## ZIO SBT Source
133
375
 
134
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.
@@ -138,7 +380,7 @@ ZIO SBT Source is a Scala 2.13 + Scala 3 cross-compiled library that provides ut
138
380
  Add the following line to your `libraryDependencies` in `build.sbt`:
139
381
 
140
382
  ```scala
141
- libraryDependencies += "dev.zio" %% "zio-sbt-source" % "0.6.0"
383
+ libraryDependencies += "dev.zio" %% "zio-sbt-source" % "0.7.0"
142
384
  ```
143
385
 
144
386
  ### Features
@@ -244,7 +486,7 @@ Both forms emit `showLineNumbers` in the code fence header, enabling line number
244
486
 
245
487
  ### Default Testing Strategy
246
488
 
247
- The default testing strategy for ZIO SBT CI plugin is to run `sbt +test` on Corretto Java 11, 17 and 21. So this will generate the following job:
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:
248
490
 
249
491
  ```yaml
250
492
  test:
@@ -254,12 +496,12 @@ test:
254
496
  strategy:
255
497
  fail-fast: false
256
498
  matrix:
257
- java: ['11', '17', '21']
499
+ java: ['17', '21', '25']
258
500
  steps:
259
501
  - name: Install libuv
260
502
  run: sudo apt-get update && sudo apt-get install -y libuv1-dev
261
503
  - name: Setup Scala
262
- uses: actions/setup-java@v3.13.0
504
+ uses: actions/setup-java@v5
263
505
  with:
264
506
  distribution: corretto
265
507
  java-version: ${{ matrix.java }}
@@ -318,7 +560,7 @@ test:
318
560
  strategy:
319
561
  fail-fast: false
320
562
  matrix:
321
- java: ['11', '17', '21']
563
+ java: ['17', '21', '25']
322
564
  scala-project:
323
565
  - ++2.12.20 submoduleA
324
566
  - ++2.12.20 submoduleB
@@ -328,7 +570,7 @@ test:
328
570
  - name: Install libuv
329
571
  run: sudo apt-get update && sudo apt-get install -y libuv1-dev
330
572
  - name: Setup Scala
331
- uses: actions/setup-java@v3.10.0
573
+ uses: actions/setup-java@v5
332
574
  with:
333
575
  distribution: corretto
334
576
  java-version: ${{ matrix.java }}
package/package.json CHANGED
@@ -2,7 +2,7 @@
2
2
  "name": "@zio.dev/zio-sbt",
3
3
  "description": "ZIO SBT Documentation",
4
4
  "license": "Apache-2.0",
5
- "version": "0.6.0",
5
+ "version": "0.7.0",
6
6
  "repository": {
7
7
  "url": "https://github.com/zio/zio-sbt"
8
8
  }