@zio.dev/zio-sbt 0.8.9 → 0.8.11

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 (30) hide show
  1. package/concepts/generated-files.md +22 -0
  2. package/concepts/how-the-plugins-fit-together.md +29 -0
  3. package/concepts/index.md +10 -0
  4. package/getting-started.md +91 -0
  5. package/how-to-guides/add-a-service-container-to-a-job.md +28 -0
  6. package/how-to-guides/auto-approve-and-auto-merge-dependency-update-prs.md +36 -0
  7. package/how-to-guides/build-a-workflow-of-only-custom-jobs.md +15 -0
  8. package/how-to-guides/change-the-workflow-environment.md +12 -0
  9. package/how-to-guides/configure-dependabot-updates.md +24 -0
  10. package/how-to-guides/configure-scala-steward.md +16 -0
  11. package/how-to-guides/control-ci-concurrency.md +30 -0
  12. package/how-to-guides/customize-the-generated-ci-jobs.md +54 -0
  13. package/how-to-guides/customize-the-generated-readme.md +36 -0
  14. package/how-to-guides/draft-releases-with-release-drafter.md +16 -0
  15. package/how-to-guides/enable-netlify-deploy-previews.md +42 -0
  16. package/how-to-guides/keep-the-workflow-in-sync.md +12 -0
  17. package/how-to-guides/publish-a-releases-docs-again.md +18 -0
  18. package/how-to-guides/regenerate-workflows-on-bot-prs.md +15 -0
  19. package/how-to-guides/set-job-timeouts.md +17 -0
  20. package/how-to-guides/test-against-several-scala-and-java-versions.md +101 -0
  21. package/index.md +25 -733
  22. package/package.json +1 -1
  23. package/reference/ci.md +148 -0
  24. package/reference/ecosystem.md +141 -0
  25. package/reference/githubactions.md +51 -0
  26. package/reference/index.md +15 -0
  27. package/reference/source.md +109 -0
  28. package/reference/website.md +103 -0
  29. package/sidebars.js +57 -3
  30. package/tutorials/set-up-a-new-zio-library.md +141 -0
package/index.md CHANGED
@@ -1,27 +1,43 @@
1
1
  ---
2
2
  id: index
3
- title: "ZIO SBT"
3
+ title: "Introduction to ZIO SBT"
4
+ sidebar_label: "Introduction"
4
5
  ---
5
6
 
6
7
  _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
8
 
8
9
  [![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
10
 
11
+ ## Overview
12
+
13
+ ZIO SBT is made of five modules, three of which are sbt plugins that a ZIO project enables in its build:
14
+
15
+ - **ZIO SBT Ecosystem** (`zio-sbt-ecosystem`) holds the standard settings, compiler options and commands (`fmt`, `lint`, `prepare`) that every ZIO project shares.
16
+ - **ZIO SBT Website** (`zio-sbt-website`) compiles the documentation in `docs/` with mdoc, builds and previews the Docusaurus website, publishes the docs to npm, and generates the `README.md`.
17
+ - **ZIO SBT CI** (`zio-sbt-ci`) generates the GitHub Actions workflows of a project from its `build.sbt`.
18
+ - **ZIO SBT GitHub Actions** (`zio-sbt-githubactions`) is the model of GitHub workflows (`Workflow`, `Job`, `Step`, ...) that ZIO SBT CI is built on. It comes with `zio-sbt-ci`, so it needs no installation of its own.
19
+ - **ZIO SBT Source** (`zio-sbt-source`) is a library, not an sbt plugin, that embeds source files and evaluated expressions into the documentation.
20
+
10
21
  ## Installation
11
22
 
12
23
  Add the following lines to your `project/plugins.sbt` file:
13
24
 
14
25
  ```scala
15
- addSbtPlugin("dev.zio" % "zio-sbt-ecosystem" % "0.8.9")
16
- addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.8.9")
17
- addSbtPlugin("dev.zio" % "zio-sbt-website" % "0.8.9")
26
+ // Standard settings, compiler options and the fmt, lint and prepare commands
27
+ addSbtPlugin("dev.zio" % "zio-sbt-ecosystem" % "0.8.11")
28
+
29
+ // Generates the GitHub Actions workflows from build.sbt
30
+ addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.8.11")
31
+
32
+ // Builds, previews and publishes the documentation website
33
+ addSbtPlugin("dev.zio" % "zio-sbt-website" % "0.8.11")
18
34
  ```
19
35
 
20
36
  Then you can enable them by using the following code in your `build.sbt` file:
21
37
 
22
38
  ```scala
23
39
  enablePlugins(
24
- ZioSbtWebsitePlugin,
40
+ WebsitePlugin,
25
41
  ZioSbtEcosystemPlugin,
26
42
  ZioSbtCiPlugin
27
43
  )
@@ -31,736 +47,12 @@ enablePlugins(
31
47
  Always try to keep the SBT version specified in the `project/build.properties` file up to date to ensure compatibility with the ZIO SBT plugins.
32
48
  :::
33
49
 
34
- ## ZIO SBT Ecosystem
35
-
36
- ZIO SBT Ecosystem plugin is an sbt plugin that provides a set of sbt settings and tasks that are very common and useful for configuring and managing ZIO projects. It is designed help developers to quickly set up a new ZIO project with a minimal amount of effort.
37
-
38
- This pluging provides the following settings with default values:
39
-
40
- - scala212
41
- - scala213
42
- - scala3
43
-
44
- The default values are the latest stable versions of Scala 2.12, 2.13, and Scala 3. All of these settings are of type `String` and can be overridden by the user.
45
-
46
- By having these settings, then we can use them in other sbt settings. For example, we can use them to define the `crossScalaVersions` setting:
47
-
48
- ```scala
49
- crossScalaVersions := Seq(scala212.value, scala213.value, scala3.value)
50
- ```
51
-
52
- There are also some other settings that are useful for configuring the projects:
53
-
54
- - `stdSettings`— a set of standard settings which are common for every ZIO project, which includes configuring:
55
- - silencer plugin
56
- - kind projector plugin
57
- - cross project plugin
58
- - scalafix plugin
59
- - java target platform
60
- - `enableZIO`- a set of ZIO related settings such as enabling zio streams and ZIO test framework.
61
- - `jsSettings`, `nativeSettings`- common platform specific settings for Scala.js and Scala Native.
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
-
78
- It also provides some helper methods that are useful for configuring a compiler option for a specific Scala version:
79
-
80
- - `optionsOn`
81
- - `optionsOnExcept`
82
- - `optionsOnOrElse`
83
- - `addOptionsOn`
84
- - `addOptionsOnOrElse`
85
- - `addOptionsOnExcept`
86
-
87
- And the same for adding a dependency for a specific Scala version:
88
-
89
- - `dependenciesOn`
90
- - `dependenciesOnExcept`
91
- - `dependenciesOnOrElse`
92
- - `addDependenciesOn`
93
- - `addDependenciesOnExcept`
94
- - `addDependenciesOnOrElse`
95
-
96
- ## ZIO SBT Website
97
-
98
- ZIO SBT Website is an SBT plugin that has the following tasks:
99
-
100
- - `sbt compileDocs`— compile documentation inside `docs` directory. The compilation result will be inside `website/docs` directory.
101
- - `sbt installWebsite`— creates a website for the project inside the `website` directory.
102
- - `sbt previewWebsite`— runs a local webserver that serves documentation locally on http://localhost:3000. By changing the documentation inside the `docs` directory, the website will be reloaded with new content.
103
- - `sbt publishToNpm`— publishes documentation inside the `docs` directory to the npm registry.
104
- - `sbt generateReadme`— generate README.md file from `docs/index.md` and sbt setting keys.
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
-
120
- ## ZIO SBT CI Plugin
121
-
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.
123
-
124
- ZIO SBT CI provides a simple and efficient way to configure, manage, and run CI pipelines, helping teams to deliver high-quality software faster and with greater confidence.
125
-
126
- ZIO SBT CI plugin generates a default GitHub workflow that includes common CI tasks such as building, testing, and publishing artifacts. However, users can also manually customize the workflow. This plugin is designed to be flexible and extensible, making it easy for users to tailor the workflow to their specific needs. Additionally, the plugin also provides tons of optional sbt settings that users can modify to change various aspects of the generated workflow. Overall, ZIO SBT CI plugin strikes a balance between automation and flexibility, allowing users to automate their CI process while still giving them control over how the workflow is generated.
127
-
128
- ### Getting Started
129
-
130
- To use ZIO SBT CI plugin, add the following lines to your `plugins.sbt` file:
131
-
132
- ```scala
133
- addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.8.9")
134
-
135
- resolvers ++= Resolver.sonatypeOssRepos("public")
136
- ```
137
-
138
- Then in your `build.sbt` file, enable the plugin by adding the following line:
139
-
140
- ```scala
141
- enablePlugins(ZioSbtCiPlugin)
142
- ```
143
-
144
- Now you can generate a Github workflow by running the following command:
145
-
146
- ```bash
147
- sbt ciGenerateGithubWorkflow
148
- ```
149
-
150
- This will generate a GitHub workflow file inside the `.github/workflows` directory, named `ci.yml`. The workflow file contains the following default jobs:
151
-
152
- | Job | What it does |
153
- | --- | --- |
154
- | `build` | Compiles everything, publishes locally, and builds the website |
155
- | `lint` | Checks the generated workflow is up to date, then runs `sbt lint` |
156
- | `test` | Runs the test suite across the target Java versions |
157
- | `update-readme` | Regenerates `README.md` from `docs/index.md` and opens a PR |
158
- | `ci` | Aggregate gate: succeeds only if the jobs above did. Point branch protection at this one |
159
- | `release` | Runs `sbt ci-release` on a published release, and on pushes to enabled branches for SNAPSHOTs |
160
- | `release-docs` | Publishes the docs to npm after a successful `release`, or on a manual run with `docs-only` set to `true` |
161
- | `notify-docs-release` | Tells `zio/zio` to rebuild the docs site |
162
-
163
- 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(...)`.
164
-
165
- > **Note:**
166
- >
167
- > To use this plugin, we also need to install [ZIO Assistant](https://github.com/apps/zio-assistant) bot.
168
-
169
- ### Publishing a Release's Docs Again
170
-
171
- `release-docs` needs `release`, and Maven Central rejects a version it already has. So when `release` has published a version but `release-docs` failed (for example, because the npm package was not set up yet), running `release` again fails with `already exists` and the docs are skipped again.
172
-
173
- To publish the docs without the Maven release, run the CI workflow by hand with the `docs-only` input set to `true`:
174
-
175
- ```bash
176
- gh workflow run ci.yml --ref main -f docs-only=true
177
- ```
178
-
179
- Or open **Actions → CI → Run workflow**, pick the branch, and type `true` in `docs-only`. The `release` job is skipped, `release-docs` publishes the docs, and `notify-docs-release` runs once they are published. The docs version is the newest `v*` tag in the repository; the docs content comes from the branch or tag the workflow runs on.
180
-
181
- The run uses the `ci.yml` of that branch or tag, so the input is only there once the workflow has been regenerated with this version of the plugin. Every `workflow_dispatch` trigger of `ci.yml` gets the input, including one in a custom `ciWorkflowTriggers`, as long as the workflow has a `release-docs` job.
182
-
183
- If the failure is caught right away, **Re-run failed jobs** on the original run also works: it keeps the successful `release` result and only runs `release-docs` and `notify-docs-release` again. **Re-run all jobs** runs `release` again and fails.
184
-
185
- ### Auto-Approving and Auto-Merging Dependency Update PRs
186
-
187
- Besides `ci.yml`, the `ciGenerateGithubWorkflow` task also generates two more workflow files: `auto-approve.yml` and `auto-merge.yml`. These workflows automatically approve, and squash-merge once CI is green, 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).
188
-
189
- 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.
190
-
191
- The set of trusted bots is controlled by the `ciDependencyUpdateBots` setting, which takes a `Seq[DependencyBot]`:
192
-
193
- ```scala
194
- import zio.sbt.githubactions.DependencyBot
195
-
196
- ciDependencyUpdateBots := Seq(
197
- DependencyBot.Dependabot,
198
- DependencyBot.Renovate,
199
- DependencyBot.ScalaSteward("zio-scala-steward"),
200
- DependencyBot.Custom("some-other-bot[bot]")
201
- )
202
- ```
203
-
204
- - `DependencyBot.Dependabot` — matches login `dependabot[bot]`
205
- - `DependencyBot.Renovate` — matches login `renovate[bot]`
206
- - `DependencyBot.ScalaSteward(githubAppName)` — matches login `<githubAppName>[bot]`, where `githubAppName` is the name of the GitHub App you registered for Scala Steward
207
- - `DependencyBot.Custom(login)` — matches any exact GitHub login, for bots not covered by the predefined cases
208
-
209
- 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.
210
-
211
- > **Note:**
212
- >
213
- > When the PR's base branch requires status checks (through classic branch protection or a ruleset), `auto-merge.yml` enables GitHub's native auto-merge with `gh pr merge --auto --squash` and finishes at once; GitHub merges the PR when the required checks pass. On a branch without required status checks, where `--auto` would merge before CI finishes, it instead waits for every check on the PR (other than its own bot jobs) to finish and merges with `gh pr merge --squash` only if none failed. A red check fails the job and leaves the PR open. The `workflow_dispatch` backfill still uses `gh pr merge --auto`, which merges immediately on a branch with no required status checks, so configure branch protection with required checks before relying on it.
214
-
215
- > **Note:**
216
- >
217
- > `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.
218
-
219
- ### Regenerating Workflows on Bot PRs
220
-
221
- A bot PR often changes something the generated files depend on: Scala Steward bumping `zio-sbt-ci` itself, or Dependabot bumping an action pin in a generated workflow. Either leaves `ciCheckGithubWorkflow` failing in the Lint job, so the PR is red and `auto-merge.yml` never merges it, with nobody to fix it.
222
-
223
- `ciEnableRegenerateWorkflows` defaults to `true`, so `ciGenerateGithubWorkflow` also generates `regenerate-workflows.yml`. On every same-repository PR opened by one of `ciDependencyUpdateBots`, it checks out the PR branch, runs `sbt ciGenerateGithubWorkflow`, and, if anything under `.github` changed, commits and pushes the result to that branch. The push re-runs CI on the new commit and, since `auto-merge.yml` re-evaluates on every push, the PR then merges once CI is green.
224
-
225
- Things to know:
226
-
227
- - It pushes with the GitHub App token (`APP_ID`/`APP_PRIVATE_KEY`, the same as `auto-merge.yml`): a push made with `GITHUB_TOKEN` does not trigger CI, and `GITHUB_TOKEN` cannot push changes to `.github/workflows/**` at all. The App needs the **Workflows** repository permission.
228
- - Workflows triggered by `dependabot[bot]` read the **Dependabot** secrets store, not the repository's Actions secrets. Add `APP_ID` and `APP_PRIVATE_KEY` under Settings → Secrets and variables → Dependabot.
229
- - Regeneration is driven by your build, so a Dependabot bump of an action pin *in a generated workflow* is regenerated back to the plugin's own pin and the PR ends up empty. The plugin owns those pins; they move when `zio-sbt-ci` is bumped. If you rely on this, remove the `github-actions` ecosystem from `ciDependabotConfig`.
230
- - Set `ciEnableRegenerateWorkflows := false` to opt out; the plugin then deletes only a `regenerate-workflows.yml` carrying its "autogenerated" header.
231
-
232
- ### Netlify Deploy Previews
233
-
234
- 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/`.
235
-
236
- ```scala
237
- ThisBuild / ciEnableDeployPreview := true
238
- ```
239
-
240
- The feature is split across two workflows, decoupled by artifacts rather than triggering the deploy directly from a pull request event:
241
-
242
- - 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.
243
- - `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.
244
-
245
- 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).
246
-
247
- `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.
248
-
249
- 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.
250
-
251
- 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.
252
-
253
- #### On-demand previews
254
-
255
- Every preview deploy costs Netlify credits. To deploy only when someone asks for it, switch the mode:
256
-
257
- ```scala
258
- import zio.sbt.githubactions.DeployPreviewMode
259
-
260
- ThisBuild / ciEnableDeployPreview := true
261
- ThisBuild / ciDeployPreviewMode := DeployPreviewMode.OnDemand
262
- ```
263
-
264
- `ciDeployPreviewMode` defaults to `DeployPreviewMode.Automatic`, the behavior described above, so nothing changes until you opt in. With `OnDemand`, `deploy-preview.yml` is still generated, but it works differently:
265
-
266
- 1. After a successful pull-request CI run, the `post-preview-comment` job creates one bot comment on the pull request with an unticked **Deploy preview** checkbox. Nothing is deployed yet. A later push resets the same comment to the new commit with the box unticked again.
267
- 2. When someone ticks the box, GitHub fires an `issue_comment` `edited` event and the `deploy-preview` job runs. It first checks that the person who ticked has `admin`, `maintain` or `write` access to the repository and adds a 👍 reaction to the comment to acknowledge the request, then finds the successful `ci.yml` run for the exact commit named in the comment, downloads that run's `website-artifact`, and deploys it to Netlify.
268
- 3. The comment is rewritten with the preview URL, the deploy time and the commit, plus a **Redeploy preview** checkbox. If the deployment fails, the box is unticked again and the comment links to the failed run.
269
-
270
- Deployments are serialized per pull request (a second tick waits for the first instead of cancelling it). The two Netlify secrets and the `website-artifact` / `pr-metadata` artifacts from `build` are the same as for the automatic mode, and the generated workflow looks up CI by its file name, `ci.yml`.
271
-
272
- ### Release Drafter
273
-
274
- `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:
275
-
276
- ```scala
277
- ThisBuild / ciEnableReleaseDrafter := false
278
- ```
279
-
280
- 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`.
281
-
282
- `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.
283
-
284
- 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*, a repo that already hand-maintains a `release-drafter.yml` (release-drafter's own README convention) has that file **overwritten** by the generated workflow the next time `ciGenerateGithubWorkflow` runs, exactly like `ci.yml` — silently, with no warning, so custom triggers, `runs-on` or steps are lost. `ciCheckGithubWorkflow` fails until the regenerated file is committed. The hand-edited `.github/release-drafter.yml` config file is unaffected. To keep a hand-written workflow, set `ciEnableReleaseDrafter := false`: when disabled, the plugin only deletes a `release-drafter.yml` it generated itself — identified by the "autogenerated" header every generated workflow carries — and never a hand-written one. To customize the generated workflow instead, use `ciReleaseDrafterBranch`, `ciReleaseDrafterCategories`, `ciReleaseDrafterExcludeLabels`, `ciReleaseDrafterAutolabeler` and `ciReleaseDrafterVersionResolver`.
285
-
286
- ### Dependabot
287
-
288
- `ciEnableDependabot` defaults to `true`, so `ciGenerateGithubWorkflow` also generates `.github/dependabot.yml` from `ciDependabotConfig`. The default is a single weekly `github-actions` update at the repository root, which is what the ZIO-ecosystem repos use. Add more ecosystems, directories, intervals or groups explicitly; nothing is auto-detected:
289
-
290
- ```scala
291
- import zio.sbt.githubactions.{DependabotConfig, DependabotGroup, DependabotUpdate}
292
-
293
- ThisBuild / ciDependabotConfig := DependabotConfig(
294
- Seq(
295
- DependabotUpdate("github-actions"),
296
- DependabotUpdate(
297
- "npm",
298
- directory = "/website",
299
- openPullRequestsLimit = Some(5),
300
- groups = Seq(DependabotGroup("docusaurus", patterns = Seq("@docusaurus/*", "react")))
301
- )
302
- )
303
- )
304
- ```
305
-
306
- Unlike `.scala-steward.conf`, the file is fully owned by the plugin: a hand-written `dependabot.yml` is **overwritten** on the next `ciGenerateGithubWorkflow`, and `ciCheckGithubWorkflow` fails if it differs from the generated one. Set `ciEnableDependabot := false` to opt out; the plugin then deletes only a `dependabot.yml` carrying its "autogenerated" header, never a hand-written one.
307
-
308
- ### Scala Steward
309
-
310
- `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:
311
-
312
- ```scala
313
- ThisBuild / ciEnableScalaSteward := false
314
- ```
315
-
316
- `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.
317
-
318
- 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.
319
-
320
- This is purely additive: it does not change `ci.yml`'s own triggers or jobs. Because the feature defaults to *on*, a repo that already hand-maintains a `scala-steward.yml` (as every ZIO-ecosystem repo currently does) has that file **overwritten** by the generated workflow the next time `ciGenerateGithubWorkflow` runs, exactly like `ci.yml` — silently, with no warning — and `ciCheckGithubWorkflow` fails until the regenerated file is committed. The hand-edited `.scala-steward.conf` is unaffected. To keep a hand-written workflow, set `ciEnableScalaSteward := false`: when disabled, the plugin only deletes a `scala-steward.yml` it generated itself — identified by its "autogenerated" header — and never a hand-written one. To customize the generated workflow instead, use `ciScalaStewardSchedule`, `ciScalaStewardTimeoutMinutes`, `ciScalaStewardPermissions`, `ciScalaStewardWorkflowEnv` and `ciScalaStewardConfig`.
321
-
322
- ### Keeping the Workflow in Sync
323
-
324
- 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:
325
-
326
- ```bash
327
- sbt ciCheckGithubWorkflow
328
- ```
329
-
330
- 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.
331
-
332
- ### Settings Reference
333
-
334
- All settings are `ThisBuild`-scoped.
335
-
336
- **Workflow-level**
337
-
338
- | Setting | Type | Default | Description |
339
- | --- | --- | --- | --- |
340
- | `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 |
341
- | `ciEnabledBranches` | `Seq[String]` | `Seq.empty` | Branches the workflow runs on. Empty means every branch |
342
- | `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` |
343
- | `ciJvmOptions` | `Seq[String]` | `Seq.empty` | Appended to `JDK_JAVA_OPTIONS` |
344
- | `ciNodeOptions` | `Seq[String]` | `Seq.empty` | Sets `NODE_OPTIONS` when non-empty |
345
- | `ciConcurrency` | `Option[Concurrency]` | one run per branch, cancelling in progress | Concurrency group, or `None` to omit the block |
346
- | `ciWorkflowPermissions` | `Option[Map[String, String]]` | `Some(id-token: write, contents: read)` | Workflow-level `permissions`. `None` omits the block, so the workflow runs with the repository's default token permissions; `Some(Map.empty)` instead renders `permissions: {}`, which grants nothing |
347
- | `ciSwapSizeGB` | `Int` | `0` | Adds a swap-space step to every job when greater than zero |
348
- | `ciBackgroundJobs` | `Seq[String]` | `Seq.empty` | Commands prefixed to each `run`, for daemons a job needs |
349
- | `ciEnableDeployPreview` | `Boolean` | `false` | Adds website-artifact upload steps to `build` and generates `deploy-preview.yml`. Requires `NETLIFY_AUTH_TOKEN`/`NETLIFY_SITE_ID` secrets |
350
- | `ciDeployPreviewMode` | `DeployPreviewMode` | `DeployPreviewMode.Automatic` | Only used with `ciEnableDeployPreview`. `Automatic` deploys every successful pull-request CI run; `OnDemand` posts a "Deploy preview" checkbox comment and deploys only when it is ticked |
351
- | `ciEnableReleaseDrafter` | `Boolean` | `true` | Generates `release-drafter.yml` and scaffolds `.github/release-drafter.yml` (once). Overwrites a hand-written `release-drafter.yml` when on; when off, only deletes a copy it generated itself |
352
- | `ciReleaseDrafterCategories` | `Seq[ReleaseDrafterCategory]` | Features/Bug Fixes/Maintenance/Dependency Updates | Categories written into the scaffolded config on first generation only |
353
- | `ciReleaseDrafterVersionResolver` | `Option[ReleaseDrafterVersionResolver]` | `None` | Optional `version-resolver` block for the scaffolded config |
354
- | `ciReleaseDrafterAutolabeler` | `Seq[ReleaseDrafterAutolabelerRule]` | `Seq.empty` | Optional `autolabeler` rules for the scaffolded config |
355
- | `ciReleaseDrafterExcludeLabels` | `Seq[String]` | `Seq("skip-changelog")` | `exclude-labels` for the scaffolded config |
356
- | `ciReleaseDrafterBranch` | `Option[Branch]` | `None` | Branch `release-drafter.yml`'s `push` trigger runs on. Falls back to the first of `ciEnabledBranches`, then `"main"` |
357
- | `ciEnableScalaSteward` | `Boolean` | `true` | Generates `scala-steward.yml` and scaffolds `.scala-steward.conf` (once, only if non-empty). Overwrites a hand-written `scala-steward.yml` when on; when off, only deletes a copy it generated itself |
358
- | `ciScalaStewardSchedule` | `String` | `"0 0 * * *"` | Cron schedule for `scala-steward.yml`'s `schedule` trigger |
359
- | `ciScalaStewardTimeoutMinutes` | `Int` | `45` | `timeout-minutes` for the scala-steward job |
360
- | `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 |
361
- | `ciScalaStewardWorkflowEnv` | `Map[String, String]` | `Map.empty` | Extra env vars for the scala-steward job |
362
- | `ciScalaStewardConfig` | `ScalaStewardConfig` | `ScalaStewardConfig()` | Settings scaffolded into `.scala-steward.conf` on first non-empty render |
363
- | `ciEnableDependabot` | `Boolean` | `true` | Generates `.github/dependabot.yml`. Overwrites a hand-written one when on; when off, only deletes a copy it generated itself |
364
- | `ciEnableRegenerateWorkflows` | `Boolean` | `true` | Generates `regenerate-workflows.yml`, which re-runs `ciGenerateGithubWorkflow` on bot PRs and pushes the result to the PR branch. When off, only deletes a copy it generated itself |
365
- | `ciDependabotConfig` | `DependabotConfig` | one weekly `github-actions` update at `/` | Content of the generated `dependabot.yml` |
366
-
367
- **Test matrix**
368
-
369
- | Setting | Type | Default | Description |
370
- | --- | --- | --- | --- |
371
- | `ciTargetJavaVersions` | `Seq[String]` | `Seq("17", "21", "25")` | Java versions in the test matrix |
372
- | `ciDefaultJavaVersion` | `String` | `"17"` | Java version for the non-matrix jobs |
373
- | `ciTargetScalaVersions` | `Map[String, Seq[String]]` | `Map.empty` | Module to Scala versions. Empty runs a plain `sbt +test` |
374
- | `ciTargetMinJavaVersions` | `Map[String, String]` | `Map.empty` | Module to minimum Java version, gating modules per matrix entry |
375
- | `ciGroupSimilarTests` | `Boolean` | `false` | Groups by Java and Scala version instead of one entry per module |
376
- | `ciMatrixMaxParallel` | `Option[Int]` | `None` | `strategy.max-parallel` |
377
-
378
- **Jobs and steps**
379
-
380
- | Setting | Type | Default | Description |
381
- | --- | --- | --- | --- |
382
- | `ciBuildJobs` | `Seq[Job]` | one `build` job | Replaces or extends the build jobs |
383
- | `ciLintJobs` | `Seq[Job]` | one `lint` job | |
384
- | `ciTestJobs` | `Seq[Job]` | one `test` job | |
385
- | `ciUpdateReadmeJobs` | `Seq[Job]` | one `update-readme` job | Set to `Seq.empty` if the README is maintained by hand |
386
- | `ciReportSuccessfulJobs` | `Seq[Job]` | the aggregate `ci` job | Set to `Seq.empty` for a workflow made up entirely of custom jobs that does not want one |
387
- | `ciReleaseJobs` | `Seq[Job]` | one `release` job | |
388
- | `ciPostReleaseJobs` | `Seq[Job]` | `release-docs`, `notify-docs-release` | |
389
- | `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 |
390
- | `ciReleaseApprovalJobs` | `Seq[String]` | `Seq("ci")` | Job ids the release waits on |
391
- | `ciCheckArtifactsCompilationSteps` | `Seq[Step]` | `sbt +Test/compile` | |
392
- | `ciCheckArtifactsBuildSteps` | `Seq[Step]` | `sbt +publishLocal` | |
393
- | `ciCheckWebsiteBuildProcess` | `Seq[Step]` | `sbt docs/buildWebsite` | Set to `Seq.empty` in a build with no `docs` project |
394
- | `ciCheckGithubWorkflowSteps` | `Seq[Step]` | `sbt ciCheckGithubWorkflow` | |
395
-
396
- **Release and docs**
397
-
398
- | Setting | Type | Default | Description |
399
- | --- | --- | --- | --- |
400
- | `ciPublishSnapshots` | `Boolean` | `true` | Also publish SNAPSHOTs on pushes to enabled branches |
401
- | `ciUpdateReadmeCondition` | `Option[Condition]` | `None` | When to run the README job. Defaults to published releases |
402
- | `ciDocsVersioningScheme` | `DocsVersioning` | `SemanticVersioning` | `SemanticVersioning` or `HashVersioning` |
403
- | `ciDependencyUpdateBots` | `Seq[DependencyBot]` | Dependabot, Renovate, `ScalaSteward("zio-scala-steward")` | Bots whose PRs are auto-approved and auto-merged |
404
-
405
- **Tasks**
406
-
407
- | Task | Description |
408
- | --- | --- |
409
- | `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, `.github/dependabot.yml` when `ciEnableDependabot` is `true`, and `regenerate-workflows.yml` when `ciEnableRegenerateWorkflows` is `true` |
410
- | `ciCheckGithubWorkflow` | Regenerates and fails if the committed files are stale |
411
- | `ciGenerateAutoApproveWorkflow` | Writes `auto-approve.yml` only |
412
- | `ciGenerateAutoMergeWorkflow` | Writes `auto-merge.yml` only |
413
-
414
- ### Customizing Jobs
415
-
416
- 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.
417
-
418
- To adjust the generated jobs, map over them:
419
-
420
- ```scala
421
- import zio.sbt.githubactions.Job
422
-
423
- def onUbuntu22(job: Job): Job = job.copy(runsOn = "ubuntu-22.04")
424
-
425
- inThisBuild(
426
- List(
427
- ciTestJobs := ciTestJobs.value.map(onUbuntu22),
428
- ciBuildJobs := ciBuildJobs.value.map(onUbuntu22)
429
- )
430
- )
431
- ```
432
-
433
- To write one from scratch, build it from the exported steps:
434
-
435
- ```scala
436
- import zio.sbt.ZioSbtCiPlugin._
437
- import zio.sbt.githubactions.{Job, Step, Strategy}
438
-
439
- ciTestJobs := Seq(
440
- Job(
441
- id = "integration-test",
442
- name = "Integration Test",
443
- jobTimeout = Some(30),
444
- strategy = Some(Strategy(matrix = Map("java" -> List("17", "21")), failFast = false)),
445
- steps = Seq(
446
- Checkout.value,
447
- SetupJava("17"),
448
- SetupSBT,
449
- CacheDependencies,
450
- Step.SingleStep(name = "Test", run = Some("sbt it:test"))
451
- )
452
- )
453
- )
454
- ```
455
-
456
- The aggregate `ci` job waits on the ids of whatever `ciLintJobs`, `ciTestJobs` and `ciBuildJobs`
457
- produce, so replacing `test` with `integration-test` above is enough on its own. Set
458
- `ciPullRequestApprovalJobs` only to wait on a different set than those three:
459
-
460
- ```scala
461
- ciPullRequestApprovalJobs := Seq("lint", "integration-test")
462
- ```
463
-
464
- `Checkout`, `SetupJava(version)`, `SetupSBT`, `CacheDependencies`, `SetupNodeJs` and `SetSwapSpace` are all available; the ones defined as settings need `.value`. (`SetupLibuv` is deprecated and no longer used by the generated jobs; Scala Native does not need libuv, so drop it from custom jobs.)
465
-
466
- ### A Workflow of Only Custom Jobs
467
-
468
- A build that replaces every stock job, for instance one whose jobs are generated from its module list, can also drop the two things the plugin adds around them: the aggregate `ci` job, and the workflow-level `permissions` block.
469
-
470
- ```scala
471
- ciReportSuccessfulJobs := Seq.empty // no aggregate `ci` job
472
- ciWorkflowPermissions := None // inherit the repository's default token permissions
473
- ciConcurrency := None
474
- ciWorkflowEnv := Map.empty
475
- ```
476
-
477
- Omit `permissions` when a job needs more than the default `contents: read`, such as one that pushes a release tag with `GITHUB_TOKEN`. `None` is not the same as `Some(Map.empty)`, which renders `permissions: {}` and grants the token nothing.
478
-
479
- ### Job Timeouts
480
-
481
- A job with no timeout inherits GitHub's default of six hours, which is a long time to wait for a hung build:
482
-
483
- ```scala
484
- Job(id = "test", name = "Test", jobTimeout = Some(25), steps = ...)
485
-
486
- // or on an existing job
487
- ciTestJobs := ciTestJobs.value.map(_.withTimeout(25))
488
- ```
489
-
490
- > **Note:**
491
- >
492
- > `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.
493
-
494
- ### Concurrency
495
-
496
- 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:
497
-
498
- ```scala
499
- import zio.sbt.githubactions.{CancelInProgress, Concurrency, Condition}
500
-
501
- ciConcurrency := Some(
502
- Concurrency(
503
- group = "ci-pr-${{ github.event_name == 'pull_request' && github.event.pull_request.number || github.ref }}",
504
- cancelInProgress = CancelInProgress.When(Condition.Expression("github.event_name == 'pull_request'"))
505
- )
506
- )
507
- ```
508
-
509
- Individual jobs can override it. A release should generally not be cancelled halfway through:
510
-
511
- ```scala
512
- Job(
513
- id = "release",
514
- name = "Release",
515
- concurrency = Some(
516
- Concurrency(group = "release-${{ github.ref }}", cancelInProgress = CancelInProgress.Never)
517
- ),
518
- steps = ...
519
- )
520
- ```
521
-
522
- ### Service Containers
523
-
524
- 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:
525
-
526
- ```scala
527
- import zio.Chunk
528
- import zio.sbt.githubactions.{ImageRef, Service, ServicePort}
529
-
530
- Job(
531
- id = "test",
532
- name = "Test",
533
- services = Seq(
534
- Service(
535
- name = "postgres",
536
- image = ImageRef("postgres:16"),
537
- env = Map("POSTGRES_USER" -> "postgres", "POSTGRES_PASSWORD" -> "postgres"),
538
- ports = Chunk(ServicePort(5432, 5432)),
539
- options = Some("--health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5")
540
- )
541
- ),
542
- steps = ...
543
- )
544
- ```
545
-
546
- `ServicePort(inner, outer)` renders as `inner:outer`, which GitHub reads as `<host>:<container>` — so `inner` is the port a step connects to on `localhost`.
547
-
548
- ### The Workflow Environment
549
-
550
- 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:
551
-
552
- ```scala
553
- ciWorkflowEnv := Map(
554
- "SBT_OPTS" -> "-XX:+PrintCommandLineFlags -Djava.locale.providers=CLDR,JRE"
555
- )
556
- ```
557
-
558
- ## ZIO SBT Source
559
-
560
- 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.
561
-
562
- ### Installation
563
-
564
- Add the following line to your `libraryDependencies` in `build.sbt`:
565
-
566
- ```scala
567
- libraryDependencies += "dev.zio" %% "zio-sbt-source" % "0.8.9"
568
- ```
569
-
570
- ### Features
571
-
572
- The `ExprEval.show` macro provides an intuitive way to write self-documenting example code:
573
-
574
- ```scala
575
- import zio.sbt.ExprEval.show
576
-
577
- // Print expression source and result
578
- show(
579
- 42 + 8,
580
- "Hello, " + "World!"
581
- )
582
- ```
583
-
584
- Output:
585
- ```
586
- 42 + 8
587
- // 50
588
- "Hello, " + "World!"
589
- // Hello, World!
590
- ```
591
-
592
- ### Comment Labels
593
-
594
- Add `//` comments above your `show` call to add context labels to the output:
50
+ To embed source files into the documentation, also add `zio-sbt-source`, which is a regular library dependency and belongs in the `build.sbt` of the docs project:
595
51
 
596
52
  ```scala
597
- // Calculate the answer to life, the universe, and everything
598
- show(6 * 7)
53
+ libraryDependencies += "dev.zio" %% "zio-sbt-source" % "0.8.11"
599
54
  ```
600
55
 
601
- Output:
602
- ```
603
- // Calculate the answer to life, the universe, and everything
604
- 6 * 7
605
- // 42
606
- ```
56
+ ## Where to Go Next
607
57
 
608
- ### Block Form
609
-
610
- For multiple expressions, use the block form:
611
-
612
- ```scala
613
- show {
614
- 1 + 2
615
- 3 * 4
616
- "hello"
617
- }
618
- ```
619
-
620
- ### SourceFile: Embedding Source Code in Documentation
621
-
622
- The `SourceFile` utility provides methods for embedding source files into mdoc documentation with support for syntax highlighting and line numbers:
623
-
624
- ```scala
625
- import zio.sbt.SourceFile
626
-
627
- // Embed a source file in mdoc
628
- SourceFile.printSource("path/to/Example.scala")
629
- ```
630
-
631
- This generates a fenced code block with the file's language tag detected from its extension.
632
-
633
- ### EmbedSourceModifier: mdoc Plugin for Source Embedding
634
-
635
- The `EmbedSourceModifier` extends mdoc with an `embed` directive for embedding source files directly from markdown.
636
- Use the modifier name `embed` followed by the file path:
637
-
638
- ```
639
- \`\`\`scala mdoc:embed:path/to/Example.scala
640
- \`\`\`
641
- ```
642
-
643
- Renders as a fenced code block with syntax highlighting based on file extension.
644
-
645
- #### Docusaurus Line Numbers
646
-
647
- To enable line numbers in [Docusaurus](https://docusaurus.io) code blocks, add the `:showLineNumbers` flag (or kebab-case `:show-line-numbers` alias):
648
-
649
- ```
650
- \`\`\`scala mdoc:embed:path/to/Example.scala:showLineNumbers
651
- \`\`\`
652
- ```
653
-
654
- or
655
-
656
- ```
657
- \`\`\`scala mdoc:embed:path/to/Example.scala:show-line-numbers
658
- \`\`\`
659
- ```
660
-
661
- Both forms emit `showLineNumbers` in the code fence header, enabling line numbering in the rendered documentation.
662
-
663
- ### Implementation Details
664
-
665
- - **Scala 3**: Uses `scala.quoted.*` with `inline def` for compile-time source capture
666
- - **Scala 2.13**: Uses `scala.reflect.macros.whitebox` to achieve the same behavior
667
- - **Runtime Helper**: `SourceReader` utility reads comment lines from source files
668
-
669
- ## Testing Strategies
670
-
671
- ### Default Testing Strategy
672
-
673
- 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:
674
-
675
- ```yaml
676
- test:
677
- name: Test
678
- runs-on: ubuntu-latest
679
- continue-on-error: false
680
- strategy:
681
- fail-fast: false
682
- matrix:
683
- java: ['17', '21', '25']
684
- steps:
685
- - name: Setup Scala
686
- uses: actions/setup-java@v5
687
- with:
688
- distribution: corretto
689
- java-version: ${{ matrix.java }}
690
- check-latest: true
691
- - name: Cache Dependencies
692
- uses: coursier/cache-action@v6
693
- - name: Git Checkout
694
- uses: actions/checkout@v6
695
- with:
696
- fetch-depth: '0'
697
- - name: Test
698
- run: sbt --no-colors +test
699
- ```
700
-
701
- The `sbt +test` command will run the `test` task for all submodules in the project against all Scala versions defined in the `crossScalaVersions` setting.
702
-
703
- ### Concurrent Testing Strategy
704
-
705
- In some cases, we may have multiple submodules in our project and we want to test them concurrently using GitHub Actions matrix strategy.
706
-
707
- The `ciTargetScalaVersions` setting key is used to define a mapping of project names to the Scala versions that should be used for testing phase of continuous integration (CI).
708
-
709
- For example, suppose we have a project with the name "submoduleA" and we want to test it against Scala `2.12.20`, and for the "submoduleB" we want to test it against Scala `2.12.20` and `2.13.18` and `3.3.7`, We can define the `ciTargetScalaVersions` setting as follows:
710
-
711
- ```scala
712
- ThisBuild / ciTargetScalaVersions := Map(
713
- "submoduleA" -> Seq("2.12.20"),
714
- "submoduleB" -> Seq("2.12.20", "2.13.18", "3.3.7")
715
- )
716
- ```
717
-
718
- In the example provided, `ciTargetScalaVersions` is defined at the `ThisBuild` level, meaning that the setting will apply to all projects within the build. The setting defines a Map where the key is the name of the current project, obtained by calling the `id` method on the `thisProject` setting, and the value is a sequence of Scala versions obtained from the `crossScalaVersions` of each submodule setting.
719
-
720
- To simplify this process, we can populate the versions using each submodule's crossScalaVersions setting as follows:
721
-
722
- ```scala
723
- ThisBuild / ciTargetScalaVersions := Map(
724
- (submoduleA / thisProject).value.id -> (submoduleA / crossScalaVersions).value,
725
- (submoduleB / thisProject).value.id -> (submoduleB / crossScalaVersions).value
726
- )
727
- ```
728
-
729
- The above code can be simplified further by using `targetScalaVersionsFor` helper method, it takes a list of submodules and returns a Map of project names to their `crossScalaVersions`:
730
-
731
- ```scala
732
- ThisBuild / ciTargetScalaVersions := targetScalaVersionsFor(submoduleA, submoduleB).value
733
- ```
734
-
735
- This will generate the following job:
736
-
737
- ```yaml
738
- test:
739
- name: Test
740
- runs-on: ubuntu-latest
741
- continue-on-error: false
742
- strategy:
743
- fail-fast: false
744
- matrix:
745
- java: ['17', '21', '25']
746
- scala-project:
747
- - ++2.12.20 submoduleA
748
- - ++2.12.20 submoduleB
749
- - ++2.13.18 submoduleB
750
- - ++3.3.7 submoduleB
751
- steps:
752
- - name: Setup Scala
753
- uses: actions/setup-java@v5
754
- with:
755
- distribution: corretto
756
- java-version: ${{ matrix.java }}
757
- check-latest: true
758
- - name: Cache Dependencies
759
- uses: coursier/cache-action@v6
760
- - name: Git Checkout
761
- uses: actions/checkout@v6
762
- with:
763
- fetch-depth: '0'
764
- - name: Test
765
- run: sbt --no-colors ${{ matrix.scala-project }}/test
766
- ```
58
+ Read [Getting Started](https://zio.dev/zio-sbt/getting-started) to set up a project, the [Reference](https://zio.dev/zio-sbt/reference/) for every setting, task and command, and the [How-to Guides](https://zio.dev/zio-sbt/how-to-guides/publish-a-releases-docs-again) for common CI tasks.