@zio.dev/zio-sbt 0.8.5 → 0.8.7

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 (2) hide show
  1. package/index.md +56 -7
  2. 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.5")
16
- addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.8.5")
17
- addSbtPlugin("dev.zio" % "zio-sbt-website" % "0.8.5")
15
+ addSbtPlugin("dev.zio" % "zio-sbt-ecosystem" % "0.8.7")
16
+ addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.8.7")
17
+ addSbtPlugin("dev.zio" % "zio-sbt-website" % "0.8.7")
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.5")
133
+ addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.8.7")
134
134
 
135
135
  resolvers ++= Resolver.sonatypeOssRepos("public")
136
136
  ```
@@ -194,12 +194,25 @@ The default value mirrors the bots used by the `zio/zio` repository: `Seq(Depend
194
194
 
195
195
  > **Note:**
196
196
  >
197
- > `auto-merge.yml` 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, so it is safe on branches without required status checks. 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.
197
+ > 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.
198
198
 
199
199
  > **Note:**
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/`.
@@ -221,6 +234,25 @@ Put together, this makes `ciEnableDeployPreview` safe to turn on before the Docu
221
234
 
222
235
  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
236
 
237
+ #### On-demand previews
238
+
239
+ Every preview deploy costs Netlify credits. To deploy only when someone asks for it, switch the mode:
240
+
241
+ ```scala
242
+ import zio.sbt.githubactions.DeployPreviewMode
243
+
244
+ ThisBuild / ciEnableDeployPreview := true
245
+ ThisBuild / ciDeployPreviewMode := DeployPreviewMode.OnDemand
246
+ ```
247
+
248
+ `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:
249
+
250
+ 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.
251
+ 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.
252
+ 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.
253
+
254
+ 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`.
255
+
224
256
  ### Release Drafter
225
257
 
226
258
  `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:
@@ -295,9 +327,11 @@ All settings are `ThisBuild`-scoped.
295
327
  | `ciJvmOptions` | `Seq[String]` | `Seq.empty` | Appended to `JDK_JAVA_OPTIONS` |
296
328
  | `ciNodeOptions` | `Seq[String]` | `Seq.empty` | Sets `NODE_OPTIONS` when non-empty |
297
329
  | `ciConcurrency` | `Option[Concurrency]` | one run per branch, cancelling in progress | Concurrency group, or `None` to omit the block |
330
+ | `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 |
298
331
  | `ciSwapSizeGB` | `Int` | `0` | Adds a swap-space step to every job when greater than zero |
299
332
  | `ciBackgroundJobs` | `Seq[String]` | `Seq.empty` | Commands prefixed to each `run`, for daemons a job needs |
300
333
  | `ciEnableDeployPreview` | `Boolean` | `false` | Adds website-artifact upload steps to `build` and generates `deploy-preview.yml`. Requires `NETLIFY_AUTH_TOKEN`/`NETLIFY_SITE_ID` secrets |
334
+ | `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 |
301
335
  | `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 |
302
336
  | `ciReleaseDrafterCategories` | `Seq[ReleaseDrafterCategory]` | Features/Bug Fixes/Maintenance/Dependency Updates | Categories written into the scaffolded config on first generation only |
303
337
  | `ciReleaseDrafterVersionResolver` | `Option[ReleaseDrafterVersionResolver]` | `None` | Optional `version-resolver` block for the scaffolded config |
@@ -311,6 +345,7 @@ All settings are `ThisBuild`-scoped.
311
345
  | `ciScalaStewardWorkflowEnv` | `Map[String, String]` | `Map.empty` | Extra env vars for the scala-steward job |
312
346
  | `ciScalaStewardConfig` | `ScalaStewardConfig` | `ScalaStewardConfig()` | Settings scaffolded into `.scala-steward.conf` on first non-empty render |
313
347
  | `ciEnableDependabot` | `Boolean` | `true` | Generates `.github/dependabot.yml`. Overwrites a hand-written one when on; when off, only deletes a copy it generated itself |
348
+ | `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 |
314
349
  | `ciDependabotConfig` | `DependabotConfig` | one weekly `github-actions` update at `/` | Content of the generated `dependabot.yml` |
315
350
 
316
351
  **Test matrix**
@@ -332,6 +367,7 @@ All settings are `ThisBuild`-scoped.
332
367
  | `ciLintJobs` | `Seq[Job]` | one `lint` job | |
333
368
  | `ciTestJobs` | `Seq[Job]` | one `test` job | |
334
369
  | `ciUpdateReadmeJobs` | `Seq[Job]` | one `update-readme` job | Set to `Seq.empty` if the README is maintained by hand |
370
+ | `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 |
335
371
  | `ciReleaseJobs` | `Seq[Job]` | one `release` job | |
336
372
  | `ciPostReleaseJobs` | `Seq[Job]` | `release-docs`, `notify-docs-release` | |
337
373
  | `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 |
@@ -354,7 +390,7 @@ All settings are `ThisBuild`-scoped.
354
390
 
355
391
  | Task | Description |
356
392
  | --- | --- |
357
- | `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, and `.github/dependabot.yml` when `ciEnableDependabot` is `true` |
393
+ | `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` |
358
394
  | `ciCheckGithubWorkflow` | Regenerates and fails if the committed files are stale |
359
395
  | `ciGenerateAutoApproveWorkflow` | Writes `auto-approve.yml` only |
360
396
  | `ciGenerateAutoMergeWorkflow` | Writes `auto-merge.yml` only |
@@ -411,6 +447,19 @@ ciPullRequestApprovalJobs := Seq("lint", "integration-test")
411
447
 
412
448
  `Checkout`, `SetupLibuv`, `SetupJava(version)`, `SetupSBT`, `CacheDependencies`, `SetupNodeJs` and `SetSwapSpace` are all available; the ones defined as settings need `.value`.
413
449
 
450
+ ### A Workflow of Only Custom Jobs
451
+
452
+ 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.
453
+
454
+ ```scala
455
+ ciReportSuccessfulJobs := Seq.empty // no aggregate `ci` job
456
+ ciWorkflowPermissions := None // inherit the repository's default token permissions
457
+ ciConcurrency := None
458
+ ciWorkflowEnv := Map.empty
459
+ ```
460
+
461
+ 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.
462
+
414
463
  ### Job Timeouts
415
464
 
416
465
  A job with no timeout inherits GitHub's default of six hours, which is a long time to wait for a hung build:
@@ -499,7 +548,7 @@ ZIO SBT Source is a Scala 2.13 + Scala 3 cross-compiled library that provides ut
499
548
  Add the following line to your `libraryDependencies` in `build.sbt`:
500
549
 
501
550
  ```scala
502
- libraryDependencies += "dev.zio" %% "zio-sbt-source" % "0.8.5"
551
+ libraryDependencies += "dev.zio" %% "zio-sbt-source" % "0.8.7"
503
552
  ```
504
553
 
505
554
  ### Features
package/package.json CHANGED
@@ -2,7 +2,7 @@
2
2
  "name": "@zio.dev/zio-sbt",
3
3
  "description": "ZIO SBT Documentation",
4
4
  "license": "Apache-2.0",
5
- "version": "0.8.5",
5
+ "version": "0.8.7",
6
6
  "repository": {
7
7
  "url": "https://github.com/zio/zio-sbt"
8
8
  }