@zio.dev/zio-sbt 0.7.2 → 0.8.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/index.md +87 -6
- package/package.json +1 -1
package/index.md
CHANGED
|
@@ -12,9 +12,9 @@ _ZIO SBT_ contains multiple sbt plugins that are useful for ZIO projects. It pro
|
|
|
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.8.1")
|
|
16
|
+
addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.8.1")
|
|
17
|
+
addSbtPlugin("dev.zio" % "zio-sbt-website" % "0.8.1")
|
|
18
18
|
```
|
|
19
19
|
|
|
20
20
|
Then you can enable them by using the following code in your `build.sbt` file:
|
|
@@ -60,6 +60,21 @@ There are also some other settings that are useful for configuring the projects:
|
|
|
60
60
|
- `enableZIO`- a set of ZIO related settings such as enabling zio streams and ZIO test framework.
|
|
61
61
|
- `jsSettings`, `nativeSettings`- common platform specific settings for Scala.js and Scala Native.
|
|
62
62
|
|
|
63
|
+
`enableZIO` adds ZIO as a dependency using the `zioVersion` setting, which the plugin gives a
|
|
64
|
+
default value to. Always override it explicitly in your own `build.sbt`:
|
|
65
|
+
|
|
66
|
+
```scala
|
|
67
|
+
ThisBuild / zioVersion := "2.1.22"
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
:::note
|
|
71
|
+
Don't rely on `zioVersion`'s default. It's baked into whichever version of zio-sbt-ecosystem you
|
|
72
|
+
depend on, so upgrading the plugin—including via an automated dependency-update PR—can silently
|
|
73
|
+
change your project's own ZIO version along with it. Setting `zioVersion` explicitly keeps that a
|
|
74
|
+
deliberate decision you make, not a side effect of a plugin bump. Every ZIO ecosystem project
|
|
75
|
+
(zio-logging, zio-kafka, zio-cache, and others) already follows this practice.
|
|
76
|
+
:::
|
|
77
|
+
|
|
63
78
|
It also provides some helper methods that are useful for configuring a compiler option for a specific Scala version:
|
|
64
79
|
|
|
65
80
|
- `optionsOn`
|
|
@@ -115,7 +130,7 @@ ZIO SBT CI plugin generates a default GitHub workflow that includes common CI ta
|
|
|
115
130
|
To use ZIO SBT CI plugin, add the following lines to your `plugins.sbt` file:
|
|
116
131
|
|
|
117
132
|
```scala
|
|
118
|
-
addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.
|
|
133
|
+
addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.8.1")
|
|
119
134
|
|
|
120
135
|
resolvers ++= Resolver.sonatypeOssRepos("public")
|
|
121
136
|
```
|
|
@@ -181,6 +196,59 @@ The default value mirrors the bots used by the `zio/zio` repository: `Seq(Depend
|
|
|
181
196
|
>
|
|
182
197
|
> 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.
|
|
183
198
|
|
|
199
|
+
> **Note:**
|
|
200
|
+
>
|
|
201
|
+
> `GITHUB_TOKEN` can never be granted the "workflows" scope needed to auto-merge a bot PR that touches `.github/workflows/**`, so `auto-merge.yml` mints a GitHub App token for that case instead, falling back to `GITHUB_TOKEN` when no app is configured (which still auto-merges ordinary, non-workflow-touching PRs fine). This needs the same `APP_ID`/`APP_PRIVATE_KEY` secrets as `update-readme`, and the [ZIO Assistant](https://github.com/apps/zio-assistant) app installation must additionally have the **Workflows** repository permission granted and accepted — without it, workflow-touching PRs still fail to auto-merge and need a manual merge.
|
|
202
|
+
|
|
203
|
+
### Netlify Deploy Previews
|
|
204
|
+
|
|
205
|
+
Setting `ciEnableDeployPreview := true` makes `ciGenerateGithubWorkflow` also generate `deploy-preview.yml`, which deploys the built Docusaurus site to Netlify for every pull request that touches `docs/` or `website/`.
|
|
206
|
+
|
|
207
|
+
```scala
|
|
208
|
+
ThisBuild / ciEnableDeployPreview := true
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
The feature is split across two workflows, decoupled by artifacts rather than triggering the deploy directly from a pull request event:
|
|
212
|
+
|
|
213
|
+
- The `build` job gains a few extra steps. `Check website is installed` runs first, checking that `website/package.json` and `website/docusaurus.config.js` both exist — the same signal [`installWebsite`](#zio-sbt-website) itself uses to tell a real Docusaurus scaffold apart from a `website/` directory holding only `mdocOut`'s generated output. Only when the website is installed does the job go on to detect whether the pull request touched `docs/` or `website/`, and if so upload `website/build` as a `website-artifact`, plus the PR number as a `pr-metadata` artifact.
|
|
214
|
+
- `deploy-preview.yml` triggers on `workflow_run` once the CI workflow completes, downloads those two artifacts, deploys `website-artifact` to Netlify with [`nwtgck/actions-netlify`](https://github.com/nwtgck/actions-netlify) under a deterministic `pr-<number>` alias — so the preview URL for a given PR is stable across redeploys, of the shape `pr-<number>--<your-netlify-site-name>.netlify.app` — then posts a fresh comment with the preview URL via [`peter-evans/create-or-update-comment`](https://github.com/peter-evans/create-or-update-comment) — each deploy gets its own comment rather than editing one in place, so pushing a follow-up commit doesn't erase the record of the previous deploy. Earlier preview comments (tagged with an `<!-- netlify-preview-comment -->` marker) are collapsed as outdated first, via [`actions/github-script`](https://github.com/actions/github-script), so the thread doesn't accumulate clutter — the whole comment history is paginated through, not just the first page, so this still works on pull requests with a long comment history.
|
|
215
|
+
|
|
216
|
+
Using `workflow_run` instead of triggering directly on `pull_request` means the deploy step only ever runs after CI has actually succeeded, and it runs with read/write access to secrets even for pull requests from forks (where a plain `pull_request` trigger would not have that access).
|
|
217
|
+
|
|
218
|
+
`deploy-preview.yml` triggers on *every* successful pull-request CI run, not only the ones where `build` actually uploaded artifacts — a PR that doesn't touch `docs/`/`website/`, or a repo with no website installed yet, never produces `website-artifact`/`pr-metadata` at all. To handle that, the two `actions/download-artifact` steps set `continue-on-error: true`, since a missing artifact there is an expected outcome, not a failure worth stopping the job over; every step after them then checks `steps.download-website.outcome == 'success' && steps.download-pr-metadata.outcome == 'success'` before running. So a run with nothing to deploy ends with two soft-failed downloads and nothing else — no deploy call, no PR comment — instead of a hard job failure.
|
|
219
|
+
|
|
220
|
+
Put together, this makes `ciEnableDeployPreview` safe to turn on before the Docusaurus site exists: neither workflow does any real work until `website/` is a genuine installation and a pull request actually changes it.
|
|
221
|
+
|
|
222
|
+
This requires two repository secrets: `NETLIFY_AUTH_TOKEN`, a [personal access token](https://docs.netlify.com/api/get-started/#authentication) generated from the Netlify user account that owns the site, and `NETLIFY_SITE_ID`, found under the site's **Site configuration → General → Site details** in the Netlify dashboard. The default value of `ciEnableDeployPreview` is `false`, so existing builds see no change until they opt in.
|
|
223
|
+
|
|
224
|
+
### Release Drafter
|
|
225
|
+
|
|
226
|
+
`ciEnableReleaseDrafter` defaults to `true`, so `ciGenerateGithubWorkflow` generates `release-drafter.yml` automatically, which runs [`release-drafter/release-drafter`](https://github.com/release-drafter/release-drafter) on every push to the release branch to keep a draft GitHub Release up to date with categorized notes for each merged pull request. Set it to `false` to opt out:
|
|
227
|
+
|
|
228
|
+
```scala
|
|
229
|
+
ThisBuild / ciEnableReleaseDrafter := false
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
The first time the feature generates a `release-drafter.yml`, `ciGenerateGithubWorkflow` also scaffolds `.github/release-drafter.yml` — release-drafter's own config file — from `ciReleaseDrafterCategories`/`ciReleaseDrafterExcludeLabels`/`ciReleaseDrafterAutolabeler`/`ciReleaseDrafterVersionResolver`, if that file doesn't already exist. Unlike every other generated file, it is **never rewritten or deleted afterward**, even if those settings change or `ciEnableReleaseDrafter` is turned back off: category/label taxonomy is inherently per-repo and meant to be hand-customized once scaffolded, so `ciCheckGithubWorkflow`'s drift check does not cover it either — only `.github/workflows/release-drafter.yml` (the workflow file) participates in that check, the same as `ci.yml`/`auto-approve.yml`/`auto-merge.yml`/`deploy-preview.yml`.
|
|
233
|
+
|
|
234
|
+
`release-drafter.yml`'s `push` trigger runs on `ciReleaseDrafterBranch` when set, otherwise the first entry of `ciEnabledBranches`, otherwise `main` — GitHub Actions' static `on.push.branches` list can't use the same `default_branch` runtime expression this plugin uses elsewhere, so a literal branch name is always required. Repos maintaining multiple release series (e.g. `series/2.x`) should set `ciReleaseDrafterBranch` explicitly.
|
|
235
|
+
|
|
236
|
+
This is purely additive: it does not change `ci.yml`'s own triggers or jobs, and it does not publish the draft release automatically — a human still does that, which is what fires the existing `release: published`-gated release jobs. Because the feature defaults to *on*, `release-drafter.yml` is only ever written or deleted if this plugin created it in the first place — identified by the same "autogenerated" header every other generated workflow carries. A repo that already hand-maintains a `release-drafter.yml` (release-drafter's own README convention) sees that file left completely alone, whether `ciEnableReleaseDrafter` is left at its default or set explicitly either way; only a repo where the file doesn't exist yet, or where the plugin already owns it, is affected.
|
|
237
|
+
|
|
238
|
+
### Scala Steward
|
|
239
|
+
|
|
240
|
+
`ciEnableScalaSteward` defaults to `true`, so `ciGenerateGithubWorkflow` generates `scala-steward.yml` automatically, which runs [`scala-steward-org/scala-steward-action`](https://github.com/scala-steward-org/scala-steward-action) on a daily schedule (`ciScalaStewardSchedule`, default `"0 0 * * *"`) to open dependency-update pull requests, authenticating as a GitHub App via the `SCALA_STEWARD_GITHUB_APP_ID`, `SCALA_STEWARD_GITHUB_APP_INSTALLATION_ID` and `SCALA_STEWARD_GITHUB_APP_PRIVATE_KEY` repository secrets. Set it to `false` to opt out:
|
|
241
|
+
|
|
242
|
+
```scala
|
|
243
|
+
ThisBuild / ciEnableScalaSteward := false
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
`ciScalaStewardTimeoutMinutes` (default `45`), `ciScalaStewardPermissions` (default `contents: read` — the action authenticates via the GitHub App's installation token, since `github-app-auth-only` is always set, so no write scope is needed by default) and `ciScalaStewardWorkflowEnv` (default empty; a repo needing JVM tuning during dependency resolution sets `JDK_JAVA_OPTIONS`/similar here) all override the generated job.
|
|
247
|
+
|
|
248
|
+
The first time this feature renders a non-empty `.scala-steward.conf` from `ciScalaStewardConfig`, it scaffolds that file at the repository root, if it does not already exist. Like `.github/release-drafter.yml`, it is **never rewritten or deleted afterward**, even if `ciScalaStewardConfig` changes or `ciEnableScalaSteward` is turned back off — repo-specific pins/ignores/grouping are meant to be hand-customized once scaffolded, and `ciCheckGithubWorkflow`'s drift check does not cover it either, only `.github/workflows/scala-steward.yml` does. An all-default `ciScalaStewardConfig` renders to nothing, so most repos never see this file at all unless they set it.
|
|
249
|
+
|
|
250
|
+
This is purely additive: it does not change `ci.yml`'s own triggers or jobs. Because the feature defaults to *on*, `scala-steward.yml` is only ever written or deleted if this plugin created it in the first place — identified by the same "autogenerated" header every other generated workflow carries. A repo that already hand-maintains a `scala-steward.yml` (as every ZIO-ecosystem repo currently does) sees that file left completely alone until it is deliberately deleted so the plugin can take ownership.
|
|
251
|
+
|
|
184
252
|
### Keeping the Workflow in Sync
|
|
185
253
|
|
|
186
254
|
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:
|
|
@@ -207,6 +275,19 @@ All settings are `ThisBuild`-scoped.
|
|
|
207
275
|
| `ciConcurrency` | `Option[Concurrency]` | one run per branch, cancelling in progress | Concurrency group, or `None` to omit the block |
|
|
208
276
|
| `ciSwapSizeGB` | `Int` | `0` | Adds a swap-space step to every job when greater than zero |
|
|
209
277
|
| `ciBackgroundJobs` | `Seq[String]` | `Seq.empty` | Commands prefixed to each `run`, for daemons a job needs |
|
|
278
|
+
| `ciEnableDeployPreview` | `Boolean` | `false` | Adds website-artifact upload steps to `build` and generates `deploy-preview.yml`. Requires `NETLIFY_AUTH_TOKEN`/`NETLIFY_SITE_ID` secrets |
|
|
279
|
+
| `ciEnableReleaseDrafter` | `Boolean` | `true` | Generates `release-drafter.yml` and scaffolds `.github/release-drafter.yml` (once). Only writes/deletes a `release-drafter.yml` it generated itself, whether on or off |
|
|
280
|
+
| `ciReleaseDrafterCategories` | `Seq[ReleaseDrafterCategory]` | Features/Bug Fixes/Maintenance/Dependency Updates | Categories written into the scaffolded config on first generation only |
|
|
281
|
+
| `ciReleaseDrafterVersionResolver` | `Option[ReleaseDrafterVersionResolver]` | `None` | Optional `version-resolver` block for the scaffolded config |
|
|
282
|
+
| `ciReleaseDrafterAutolabeler` | `Seq[ReleaseDrafterAutolabelerRule]` | `Seq.empty` | Optional `autolabeler` rules for the scaffolded config |
|
|
283
|
+
| `ciReleaseDrafterExcludeLabels` | `Seq[String]` | `Seq("skip-changelog")` | `exclude-labels` for the scaffolded config |
|
|
284
|
+
| `ciReleaseDrafterBranch` | `Option[Branch]` | `None` | Branch `release-drafter.yml`'s `push` trigger runs on. Falls back to the first of `ciEnabledBranches`, then `"main"` |
|
|
285
|
+
| `ciEnableScalaSteward` | `Boolean` | `true` | Generates `scala-steward.yml` and scaffolds `.scala-steward.conf` (once, only if non-empty). Only writes/deletes a `scala-steward.yml` it generated itself, whether on or off |
|
|
286
|
+
| `ciScalaStewardSchedule` | `String` | `"0 0 * * *"` | Cron schedule for `scala-steward.yml`'s `schedule` trigger |
|
|
287
|
+
| `ciScalaStewardTimeoutMinutes` | `Int` | `45` | `timeout-minutes` for the scala-steward job |
|
|
288
|
+
| `ciScalaStewardPermissions` | `Map[String, String]` | `contents: read` | Permissions block for `scala-steward.yml`; the action authenticates via the GitHub App's installation token, not `GITHUB_TOKEN`, so no write scope is needed by default |
|
|
289
|
+
| `ciScalaStewardWorkflowEnv` | `Map[String, String]` | `Map.empty` | Extra env vars for the scala-steward job |
|
|
290
|
+
| `ciScalaStewardConfig` | `ScalaStewardConfig` | `ScalaStewardConfig()` | Settings scaffolded into `.scala-steward.conf` on first non-empty render |
|
|
210
291
|
|
|
211
292
|
**Test matrix**
|
|
212
293
|
|
|
@@ -249,7 +330,7 @@ All settings are `ThisBuild`-scoped.
|
|
|
249
330
|
|
|
250
331
|
| Task | Description |
|
|
251
332
|
| --- | --- |
|
|
252
|
-
| `ciGenerateGithubWorkflow` | Writes `ci.yml`, `auto-approve.yml` and `auto-merge.yml` |
|
|
333
|
+
| `ciGenerateGithubWorkflow` | Writes `ci.yml`, `auto-approve.yml` and `auto-merge.yml`, plus `deploy-preview.yml` when `ciEnableDeployPreview` is `true` and `release-drafter.yml` (and scaffolds `.github/release-drafter.yml` once) when `ciEnableReleaseDrafter` is `true`, and scala-steward.yml (and scaffolds .scala-steward.conf once, when ciScalaStewardConfig renders non-empty content) when ciEnableScalaSteward is true |
|
|
253
334
|
| `ciCheckGithubWorkflow` | Regenerates and fails if the committed files are stale |
|
|
254
335
|
| `ciGenerateAutoApproveWorkflow` | Writes `auto-approve.yml` only |
|
|
255
336
|
| `ciGenerateAutoMergeWorkflow` | Writes `auto-merge.yml` only |
|
|
@@ -394,7 +475,7 @@ ZIO SBT Source is a Scala 2.13 + Scala 3 cross-compiled library that provides ut
|
|
|
394
475
|
Add the following line to your `libraryDependencies` in `build.sbt`:
|
|
395
476
|
|
|
396
477
|
```scala
|
|
397
|
-
libraryDependencies += "dev.zio" %% "zio-sbt-source" % "0.
|
|
478
|
+
libraryDependencies += "dev.zio" %% "zio-sbt-source" % "0.8.1"
|
|
398
479
|
```
|
|
399
480
|
|
|
400
481
|
### Features
|