@zio.dev/zio-sbt 0.7.1 → 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 +63 -8
- 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`
|
|
@@ -88,6 +103,20 @@ ZIO SBT Website is an SBT plugin that has the following tasks:
|
|
|
88
103
|
- `sbt publishToNpm`— publishes documentation inside the `docs` directory to the npm registry.
|
|
89
104
|
- `sbt generateReadme`— generate README.md file from `docs/index.md` and sbt setting keys.
|
|
90
105
|
|
|
106
|
+
`website/docs` is generated output, not source. `mdocOut` points there, so `compileDocs` — and
|
|
107
|
+
anything that sequences it, including `generateReadme` — writes compiled documentation into it.
|
|
108
|
+
Add it to `.gitignore`:
|
|
109
|
+
|
|
110
|
+
```gitignore
|
|
111
|
+
/website/docs
|
|
112
|
+
/website/build
|
|
113
|
+
/website/node_modules
|
|
114
|
+
/website/.docusaurus
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Committing `website/docs` leaves a `website` directory that holds generated output but no
|
|
118
|
+
Docusaurus scaffold, and `buildWebsite` then has no `package.json` to install from.
|
|
119
|
+
|
|
91
120
|
## ZIO SBT CI Plugin
|
|
92
121
|
|
|
93
122
|
ZIO SBT CI is an sbt plugin which generates a GitHub workflow for a project, making it easier to set up continuous integration (CI) pipelines for Scala projects. With this plugin, developers can streamline their development workflow by automating the testing and deployment process, reducing manual effort and errors. The plugin is designed to work seamlessly with sbt, the popular build tool for Scala projects, and integrates smoothly with GitHub Actions, the CI/CD platform provided by GitHub.
|
|
@@ -101,7 +130,7 @@ ZIO SBT CI plugin generates a default GitHub workflow that includes common CI ta
|
|
|
101
130
|
To use ZIO SBT CI plugin, add the following lines to your `plugins.sbt` file:
|
|
102
131
|
|
|
103
132
|
```scala
|
|
104
|
-
addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.
|
|
133
|
+
addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.8.0")
|
|
105
134
|
|
|
106
135
|
resolvers ++= Resolver.sonatypeOssRepos("public")
|
|
107
136
|
```
|
|
@@ -167,6 +196,31 @@ The default value mirrors the bots used by the `zio/zio` repository: `Seq(Depend
|
|
|
167
196
|
>
|
|
168
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.
|
|
169
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
|
+
|
|
170
224
|
### Keeping the Workflow in Sync
|
|
171
225
|
|
|
172
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:
|
|
@@ -193,6 +247,7 @@ All settings are `ThisBuild`-scoped.
|
|
|
193
247
|
| `ciConcurrency` | `Option[Concurrency]` | one run per branch, cancelling in progress | Concurrency group, or `None` to omit the block |
|
|
194
248
|
| `ciSwapSizeGB` | `Int` | `0` | Adds a swap-space step to every job when greater than zero |
|
|
195
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 |
|
|
196
251
|
|
|
197
252
|
**Test matrix**
|
|
198
253
|
|
|
@@ -235,7 +290,7 @@ All settings are `ThisBuild`-scoped.
|
|
|
235
290
|
|
|
236
291
|
| Task | Description |
|
|
237
292
|
| --- | --- |
|
|
238
|
-
| `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` |
|
|
239
294
|
| `ciCheckGithubWorkflow` | Regenerates and fails if the committed files are stale |
|
|
240
295
|
| `ciGenerateAutoApproveWorkflow` | Writes `auto-approve.yml` only |
|
|
241
296
|
| `ciGenerateAutoMergeWorkflow` | Writes `auto-merge.yml` only |
|
|
@@ -380,7 +435,7 @@ ZIO SBT Source is a Scala 2.13 + Scala 3 cross-compiled library that provides ut
|
|
|
380
435
|
Add the following line to your `libraryDependencies` in `build.sbt`:
|
|
381
436
|
|
|
382
437
|
```scala
|
|
383
|
-
libraryDependencies += "dev.zio" %% "zio-sbt-source" % "0.
|
|
438
|
+
libraryDependencies += "dev.zio" %% "zio-sbt-source" % "0.8.0"
|
|
384
439
|
```
|
|
385
440
|
|
|
386
441
|
### Features
|
|
@@ -513,7 +568,7 @@ test:
|
|
|
513
568
|
with:
|
|
514
569
|
fetch-depth: '0'
|
|
515
570
|
- name: Test
|
|
516
|
-
run: sbt +test
|
|
571
|
+
run: sbt --no-colors +test
|
|
517
572
|
```
|
|
518
573
|
|
|
519
574
|
The `sbt +test` command will run the `test` task for all submodules in the project against all Scala versions defined in the `crossScalaVersions` setting.
|
|
@@ -582,5 +637,5 @@ test:
|
|
|
582
637
|
with:
|
|
583
638
|
fetch-depth: '0'
|
|
584
639
|
- name: Test
|
|
585
|
-
run: sbt ${{ matrix.scala-project }}/test
|
|
640
|
+
run: sbt --no-colors ${{ matrix.scala-project }}/test
|
|
586
641
|
```
|