@zio.dev/zio-sbt 0.8.4 → 0.8.6
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 +59 -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.8.
|
|
16
|
-
addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.8.
|
|
17
|
-
addSbtPlugin("dev.zio" % "zio-sbt-website" % "0.8.
|
|
15
|
+
addSbtPlugin("dev.zio" % "zio-sbt-ecosystem" % "0.8.6")
|
|
16
|
+
addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.8.6")
|
|
17
|
+
addSbtPlugin("dev.zio" % "zio-sbt-website" % "0.8.6")
|
|
18
18
|
```
|
|
19
19
|
|
|
20
20
|
Then you can enable them by using the following code in your `build.sbt` file:
|
|
@@ -130,7 +130,7 @@ ZIO SBT CI plugin generates a default GitHub workflow that includes common CI ta
|
|
|
130
130
|
To use ZIO SBT CI plugin, add the following lines to your `plugins.sbt` file:
|
|
131
131
|
|
|
132
132
|
```scala
|
|
133
|
-
addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.8.
|
|
133
|
+
addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.8.6")
|
|
134
134
|
|
|
135
135
|
resolvers ++= Resolver.sonatypeOssRepos("public")
|
|
136
136
|
```
|
|
@@ -200,6 +200,19 @@ The default value mirrors the bots used by the `zio/zio` repository: `Seq(Depend
|
|
|
200
200
|
>
|
|
201
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
202
|
|
|
203
|
+
### Regenerating Workflows on Bot PRs
|
|
204
|
+
|
|
205
|
+
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.
|
|
206
|
+
|
|
207
|
+
`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.
|
|
208
|
+
|
|
209
|
+
Things to know:
|
|
210
|
+
|
|
211
|
+
- 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.
|
|
212
|
+
- 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.
|
|
213
|
+
- 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`.
|
|
214
|
+
- Set `ciEnableRegenerateWorkflows := false` to opt out; the plugin then deletes only a `regenerate-workflows.yml` carrying its "autogenerated" header.
|
|
215
|
+
|
|
203
216
|
### Netlify Deploy Previews
|
|
204
217
|
|
|
205
218
|
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,6 +248,28 @@ The first time the feature generates a `release-drafter.yml`, `ciGenerateGithubW
|
|
|
235
248
|
|
|
236
249
|
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`.
|
|
237
250
|
|
|
251
|
+
### Dependabot
|
|
252
|
+
|
|
253
|
+
`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:
|
|
254
|
+
|
|
255
|
+
```scala
|
|
256
|
+
import zio.sbt.githubactions.{DependabotConfig, DependabotGroup, DependabotUpdate}
|
|
257
|
+
|
|
258
|
+
ThisBuild / ciDependabotConfig := DependabotConfig(
|
|
259
|
+
Seq(
|
|
260
|
+
DependabotUpdate("github-actions"),
|
|
261
|
+
DependabotUpdate(
|
|
262
|
+
"npm",
|
|
263
|
+
directory = "/website",
|
|
264
|
+
openPullRequestsLimit = Some(5),
|
|
265
|
+
groups = Seq(DependabotGroup("docusaurus", patterns = Seq("@docusaurus/*", "react")))
|
|
266
|
+
)
|
|
267
|
+
)
|
|
268
|
+
)
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
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.
|
|
272
|
+
|
|
238
273
|
### Scala Steward
|
|
239
274
|
|
|
240
275
|
`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:
|
|
@@ -273,6 +308,7 @@ All settings are `ThisBuild`-scoped.
|
|
|
273
308
|
| `ciJvmOptions` | `Seq[String]` | `Seq.empty` | Appended to `JDK_JAVA_OPTIONS` |
|
|
274
309
|
| `ciNodeOptions` | `Seq[String]` | `Seq.empty` | Sets `NODE_OPTIONS` when non-empty |
|
|
275
310
|
| `ciConcurrency` | `Option[Concurrency]` | one run per branch, cancelling in progress | Concurrency group, or `None` to omit the block |
|
|
311
|
+
| `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 |
|
|
276
312
|
| `ciSwapSizeGB` | `Int` | `0` | Adds a swap-space step to every job when greater than zero |
|
|
277
313
|
| `ciBackgroundJobs` | `Seq[String]` | `Seq.empty` | Commands prefixed to each `run`, for daemons a job needs |
|
|
278
314
|
| `ciEnableDeployPreview` | `Boolean` | `false` | Adds website-artifact upload steps to `build` and generates `deploy-preview.yml`. Requires `NETLIFY_AUTH_TOKEN`/`NETLIFY_SITE_ID` secrets |
|
|
@@ -288,6 +324,9 @@ All settings are `ThisBuild`-scoped.
|
|
|
288
324
|
| `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
325
|
| `ciScalaStewardWorkflowEnv` | `Map[String, String]` | `Map.empty` | Extra env vars for the scala-steward job |
|
|
290
326
|
| `ciScalaStewardConfig` | `ScalaStewardConfig` | `ScalaStewardConfig()` | Settings scaffolded into `.scala-steward.conf` on first non-empty render |
|
|
327
|
+
| `ciEnableDependabot` | `Boolean` | `true` | Generates `.github/dependabot.yml`. Overwrites a hand-written one when on; when off, only deletes a copy it generated itself |
|
|
328
|
+
| `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 |
|
|
329
|
+
| `ciDependabotConfig` | `DependabotConfig` | one weekly `github-actions` update at `/` | Content of the generated `dependabot.yml` |
|
|
291
330
|
|
|
292
331
|
**Test matrix**
|
|
293
332
|
|
|
@@ -308,6 +347,7 @@ All settings are `ThisBuild`-scoped.
|
|
|
308
347
|
| `ciLintJobs` | `Seq[Job]` | one `lint` job | |
|
|
309
348
|
| `ciTestJobs` | `Seq[Job]` | one `test` job | |
|
|
310
349
|
| `ciUpdateReadmeJobs` | `Seq[Job]` | one `update-readme` job | Set to `Seq.empty` if the README is maintained by hand |
|
|
350
|
+
| `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 |
|
|
311
351
|
| `ciReleaseJobs` | `Seq[Job]` | one `release` job | |
|
|
312
352
|
| `ciPostReleaseJobs` | `Seq[Job]` | `release-docs`, `notify-docs-release` | |
|
|
313
353
|
| `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 |
|
|
@@ -330,7 +370,7 @@ All settings are `ThisBuild`-scoped.
|
|
|
330
370
|
|
|
331
371
|
| Task | Description |
|
|
332
372
|
| --- | --- |
|
|
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 |
|
|
373
|
+
| `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` |
|
|
334
374
|
| `ciCheckGithubWorkflow` | Regenerates and fails if the committed files are stale |
|
|
335
375
|
| `ciGenerateAutoApproveWorkflow` | Writes `auto-approve.yml` only |
|
|
336
376
|
| `ciGenerateAutoMergeWorkflow` | Writes `auto-merge.yml` only |
|
|
@@ -387,6 +427,19 @@ ciPullRequestApprovalJobs := Seq("lint", "integration-test")
|
|
|
387
427
|
|
|
388
428
|
`Checkout`, `SetupLibuv`, `SetupJava(version)`, `SetupSBT`, `CacheDependencies`, `SetupNodeJs` and `SetSwapSpace` are all available; the ones defined as settings need `.value`.
|
|
389
429
|
|
|
430
|
+
### A Workflow of Only Custom Jobs
|
|
431
|
+
|
|
432
|
+
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.
|
|
433
|
+
|
|
434
|
+
```scala
|
|
435
|
+
ciReportSuccessfulJobs := Seq.empty // no aggregate `ci` job
|
|
436
|
+
ciWorkflowPermissions := None // inherit the repository's default token permissions
|
|
437
|
+
ciConcurrency := None
|
|
438
|
+
ciWorkflowEnv := Map.empty
|
|
439
|
+
```
|
|
440
|
+
|
|
441
|
+
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.
|
|
442
|
+
|
|
390
443
|
### Job Timeouts
|
|
391
444
|
|
|
392
445
|
A job with no timeout inherits GitHub's default of six hours, which is a long time to wait for a hung build:
|
|
@@ -475,7 +528,7 @@ ZIO SBT Source is a Scala 2.13 + Scala 3 cross-compiled library that provides ut
|
|
|
475
528
|
Add the following line to your `libraryDependencies` in `build.sbt`:
|
|
476
529
|
|
|
477
530
|
```scala
|
|
478
|
-
libraryDependencies += "dev.zio" %% "zio-sbt-source" % "0.8.
|
|
531
|
+
libraryDependencies += "dev.zio" %% "zio-sbt-source" % "0.8.6"
|
|
479
532
|
```
|
|
480
533
|
|
|
481
534
|
### Features
|