@zio.dev/zio-sbt 0.7.2 → 0.8.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.
- package/index.md +47 -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.0")
|
|
16
|
+
addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.8.0")
|
|
17
|
+
addSbtPlugin("dev.zio" % "zio-sbt-website" % "0.8.0")
|
|
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.0")
|
|
119
134
|
|
|
120
135
|
resolvers ++= Resolver.sonatypeOssRepos("public")
|
|
121
136
|
```
|
|
@@ -181,6 +196,31 @@ 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
|
+
|
|
184
224
|
### Keeping the Workflow in Sync
|
|
185
225
|
|
|
186
226
|
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 +247,7 @@ All settings are `ThisBuild`-scoped.
|
|
|
207
247
|
| `ciConcurrency` | `Option[Concurrency]` | one run per branch, cancelling in progress | Concurrency group, or `None` to omit the block |
|
|
208
248
|
| `ciSwapSizeGB` | `Int` | `0` | Adds a swap-space step to every job when greater than zero |
|
|
209
249
|
| `ciBackgroundJobs` | `Seq[String]` | `Seq.empty` | Commands prefixed to each `run`, for daemons a job needs |
|
|
250
|
+
| `ciEnableDeployPreview` | `Boolean` | `false` | Adds website-artifact upload steps to `build` and generates `deploy-preview.yml`. Requires `NETLIFY_AUTH_TOKEN`/`NETLIFY_SITE_ID` secrets |
|
|
210
251
|
|
|
211
252
|
**Test matrix**
|
|
212
253
|
|
|
@@ -249,7 +290,7 @@ All settings are `ThisBuild`-scoped.
|
|
|
249
290
|
|
|
250
291
|
| Task | Description |
|
|
251
292
|
| --- | --- |
|
|
252
|
-
| `ciGenerateGithubWorkflow` | Writes `ci.yml`, `auto-approve.yml` and `auto-merge.yml` |
|
|
293
|
+
| `ciGenerateGithubWorkflow` | Writes `ci.yml`, `auto-approve.yml` and `auto-merge.yml`, plus `deploy-preview.yml` when `ciEnableDeployPreview` is `true` |
|
|
253
294
|
| `ciCheckGithubWorkflow` | Regenerates and fails if the committed files are stale |
|
|
254
295
|
| `ciGenerateAutoApproveWorkflow` | Writes `auto-approve.yml` only |
|
|
255
296
|
| `ciGenerateAutoMergeWorkflow` | Writes `auto-merge.yml` only |
|
|
@@ -394,7 +435,7 @@ ZIO SBT Source is a Scala 2.13 + Scala 3 cross-compiled library that provides ut
|
|
|
394
435
|
Add the following line to your `libraryDependencies` in `build.sbt`:
|
|
395
436
|
|
|
396
437
|
```scala
|
|
397
|
-
libraryDependencies += "dev.zio" %% "zio-sbt-source" % "0.
|
|
438
|
+
libraryDependencies += "dev.zio" %% "zio-sbt-source" % "0.8.0"
|
|
398
439
|
```
|
|
399
440
|
|
|
400
441
|
### Features
|