@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.
- package/concepts/generated-files.md +22 -0
- package/concepts/how-the-plugins-fit-together.md +29 -0
- package/concepts/index.md +10 -0
- package/getting-started.md +91 -0
- package/how-to-guides/add-a-service-container-to-a-job.md +28 -0
- package/how-to-guides/auto-approve-and-auto-merge-dependency-update-prs.md +36 -0
- package/how-to-guides/build-a-workflow-of-only-custom-jobs.md +15 -0
- package/how-to-guides/change-the-workflow-environment.md +12 -0
- package/how-to-guides/configure-dependabot-updates.md +24 -0
- package/how-to-guides/configure-scala-steward.md +16 -0
- package/how-to-guides/control-ci-concurrency.md +30 -0
- package/how-to-guides/customize-the-generated-ci-jobs.md +54 -0
- package/how-to-guides/customize-the-generated-readme.md +36 -0
- package/how-to-guides/draft-releases-with-release-drafter.md +16 -0
- package/how-to-guides/enable-netlify-deploy-previews.md +42 -0
- package/how-to-guides/keep-the-workflow-in-sync.md +12 -0
- package/how-to-guides/publish-a-releases-docs-again.md +18 -0
- package/how-to-guides/regenerate-workflows-on-bot-prs.md +15 -0
- package/how-to-guides/set-job-timeouts.md +17 -0
- package/how-to-guides/test-against-several-scala-and-java-versions.md +101 -0
- package/index.md +25 -733
- package/package.json +1 -1
- package/reference/ci.md +148 -0
- package/reference/ecosystem.md +141 -0
- package/reference/githubactions.md +51 -0
- package/reference/index.md +15 -0
- package/reference/source.md +109 -0
- package/reference/website.md +103 -0
- package/sidebars.js +57 -3
- package/tutorials/set-up-a-new-zio-library.md +141 -0
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: generated-files
|
|
3
|
+
title: "Generated Files Are Owned by the Build"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
The CI plugin writes workflow files, so the question is who owns a file: the plugin or the developer. ZIO SBT gives two different answers, depending on the file.
|
|
7
|
+
|
|
8
|
+
## Files the Build Owns
|
|
9
|
+
|
|
10
|
+
`ci.yml`, `auto-approve.yml`, `auto-merge.yml` and the other generated workflows belong to `build.sbt`. Every one starts with an "autogenerated" header and is rewritten by `ciGenerateGithubWorkflow`. A hand edit is lost at the next generation, and `ciCheckGithubWorkflow` fails until the file matches what the build would write. This is deliberate: the build is the single source of truth, and a pull request that changes a workflow shows the change in `build.sbt` too.
|
|
11
|
+
|
|
12
|
+
The same applies to `.github/dependabot.yml`. When a feature is switched off, the plugin deletes only a file that carries its header, never a hand-written one.
|
|
13
|
+
|
|
14
|
+
## Files That Are Scaffolded Once
|
|
15
|
+
|
|
16
|
+
Two files are configuration of another tool and are expected to be edited by hand: `.github/release-drafter.yml` and `.scala-steward.conf`. The plugin writes them only the first time, when they do not exist. It never rewrites or deletes them afterward, and the drift check does not cover them.
|
|
17
|
+
|
|
18
|
+
## Why a Check Exists
|
|
19
|
+
|
|
20
|
+
A bot can change something that a generated file depends on, for example a Scala Steward bump of `zio-sbt-ci` itself. The committed files then no longer match what the build would write, and the `lint` job fails. The `regenerate-workflows.yml` workflow exists to fix exactly this on bot pull requests.
|
|
21
|
+
|
|
22
|
+
To keep the files in sync yourself, see [Keep the Generated Workflow in Sync](../how-to-guides/keep-the-workflow-in-sync.md).
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: how-the-plugins-fit-together
|
|
3
|
+
title: "How the Plugins Fit Together"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
ZIO SBT splits the build of a ZIO library into three sbt plugins that each own one concern, and two modules that support them.
|
|
7
|
+
|
|
8
|
+
## One Plugin per Concern
|
|
9
|
+
|
|
10
|
+
The ecosystem plugin owns how the code is compiled and checked. It decides the Scala versions, the compiler options and the `fmt`, `lint` and `prepare` commands, so every ZIO library builds the same way.
|
|
11
|
+
|
|
12
|
+
The website plugin owns the documentation. It compiles the Markdown in `docs/` with mdoc, so every Scala example is type-checked, and wraps the result in a Docusaurus website. It also generates the `README.md` from `docs/index.md`, so the README and the first page of the website never disagree.
|
|
13
|
+
|
|
14
|
+
The CI plugin owns the GitHub workflows. It describes the whole pipeline in Scala, using the model of `zio-sbt-githubactions`, and writes the YAML files that GitHub runs. The workflow calls back into the other plugins: the `lint` job runs the `lint` command of the ecosystem plugin, and the `build` job runs the website build.
|
|
15
|
+
|
|
16
|
+
## How Documentation Reaches zio.dev
|
|
17
|
+
|
|
18
|
+
A documentation change travels through four stages:
|
|
19
|
+
|
|
20
|
+
1. `compileDocs` runs mdoc over `docs/` and writes the compiled pages to `website/docs`.
|
|
21
|
+
2. On a release, the `release-docs` job publishes `website/docs` to npm as the package `@zio.dev/<project>`.
|
|
22
|
+
3. The `notify-docs-release` job tells the `zio/zio` repository that a new version of the package exists.
|
|
23
|
+
4. The ZIO website, built from `zio/zio`, picks up the new package version and shows the pages under `zio.dev/<project>/`.
|
|
24
|
+
|
|
25
|
+
The first stage runs on a laptop, which is why `previewWebsite` can show the same pages locally. The other three run in CI.
|
|
26
|
+
|
|
27
|
+
## Source Embedding
|
|
28
|
+
|
|
29
|
+
`zio-sbt-source` is not a plugin. It is a library on the classpath of the docs project, so mdoc can load its `mdoc:embed` modifier. Embedding examples from real source files keeps the documentation compiling against the code it describes.
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: index
|
|
3
|
+
title: "Concepts"
|
|
4
|
+
sidebar_label: "Concepts"
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
These pages explain how the parts of ZIO SBT fit together and why the plugins work the way they do. They contain no recipes. For the exact names and defaults of settings, see the [Reference](../reference/index.md).
|
|
8
|
+
|
|
9
|
+
- [How the Plugins Fit Together](./how-the-plugins-fit-together.md) explains what each plugin owns and how the documentation travels from `docs/` to zio.dev.
|
|
10
|
+
- [Generated Files Are Owned by the Build](./generated-files.md) explains which files the CI plugin writes, which it only scaffolds, and why `build.sbt` stays the single source of truth.
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: getting-started
|
|
3
|
+
title: "Getting Started with ZIO SBT"
|
|
4
|
+
sidebar_label: "Getting Started"
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
This page takes an sbt project from nothing to a formatted, linted build with a generated CI workflow. Each step uses one of the plugins listed in the [introduction](./index.md).
|
|
8
|
+
|
|
9
|
+
## Prerequisites
|
|
10
|
+
|
|
11
|
+
We need an sbt build with a `project/build.properties` file that names a current sbt version. The installation steps are in [Installation](./index.md#installation).
|
|
12
|
+
|
|
13
|
+
## Step 1: Add the Plugins
|
|
14
|
+
|
|
15
|
+
To add the plugins, put these lines in `project/plugins.sbt`:
|
|
16
|
+
|
|
17
|
+
```scala
|
|
18
|
+
addSbtPlugin("dev.zio" % "zio-sbt-ecosystem" % "0.8.11")
|
|
19
|
+
|
|
20
|
+
addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.8.11")
|
|
21
|
+
|
|
22
|
+
addSbtPlugin("dev.zio" % "zio-sbt-website" % "0.8.11")
|
|
23
|
+
|
|
24
|
+
resolvers ++= Resolver.sonatypeOssRepos("public")
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
The `resolvers` line is only needed to use SNAPSHOT versions of the plugins.
|
|
28
|
+
|
|
29
|
+
## Step 2: Configure the Build
|
|
30
|
+
|
|
31
|
+
To apply the standard ZIO settings, set the ZIO version explicitly and call `stdSettings` in the build:
|
|
32
|
+
|
|
33
|
+
```scala
|
|
34
|
+
ThisBuild / zioVersion := "2.1.22"
|
|
35
|
+
|
|
36
|
+
lazy val root = project
|
|
37
|
+
.in(file("."))
|
|
38
|
+
.settings(stdSettings(name = Some("my-library")))
|
|
39
|
+
.settings(enableZIO())
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
`zioVersion` has a default, but the default changes with every release of `zio-sbt-ecosystem`, so set it explicitly. The other settings are described in the [ZIO SBT Ecosystem reference](./reference/ecosystem.md).
|
|
43
|
+
|
|
44
|
+
## Step 3: Format and Lint
|
|
45
|
+
|
|
46
|
+
The ecosystem plugin adds the `fmt`, `lint` and `prepare` commands. To format all sources and apply scalafix rules before a pull request:
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
sbt prepare
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
To check that formatting and scalafix are clean, the same way CI does:
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
sbt lint
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## Step 4: Generate the CI Workflow
|
|
59
|
+
|
|
60
|
+
The CI plugin generates `.github/workflows/ci.yml` and the other workflow files from `build.sbt`:
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
sbt ciGenerateGithubWorkflow
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Commit the generated files and never edit them by hand. The [ZIO SBT CI reference](./reference/ci.md) lists the generated files, the default jobs and every setting that changes them.
|
|
67
|
+
|
|
68
|
+
:::note
|
|
69
|
+
To use the CI plugin, install the [ZIO Assistant](https://github.com/apps/zio-assistant) GitHub App on the repository.
|
|
70
|
+
:::
|
|
71
|
+
|
|
72
|
+
## Step 5: Build the Documentation
|
|
73
|
+
|
|
74
|
+
The website plugin compiles the documentation in `docs/` and scaffolds the Docusaurus website. To compile the docs, then create the website the first time:
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
sbt docs/compileDocs
|
|
78
|
+
sbt docs/installWebsite
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
To preview the website on `http://localhost:3000`:
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
sbt docs/previewWebsite
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
The compiled output goes to `website/docs`, which is generated and must stay out of version control. The [ZIO SBT Website reference](./reference/website.md) shows the `.gitignore` entries.
|
|
88
|
+
|
|
89
|
+
## Next Steps
|
|
90
|
+
|
|
91
|
+
To see the whole path with a worked project, follow the [tutorial](./tutorials/set-up-a-new-zio-library.md). To solve a specific problem, pick a guide from the How-to Guides section.
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: add-a-service-container-to-a-job
|
|
3
|
+
title: "Add a Service Container to a Job"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
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:
|
|
7
|
+
|
|
8
|
+
```scala
|
|
9
|
+
import zio.Chunk
|
|
10
|
+
import zio.sbt.githubactions.{ImageRef, Service, ServicePort}
|
|
11
|
+
|
|
12
|
+
Job(
|
|
13
|
+
id = "test",
|
|
14
|
+
name = "Test",
|
|
15
|
+
services = Seq(
|
|
16
|
+
Service(
|
|
17
|
+
name = "postgres",
|
|
18
|
+
image = ImageRef("postgres:16"),
|
|
19
|
+
env = Map("POSTGRES_USER" -> "postgres", "POSTGRES_PASSWORD" -> "postgres"),
|
|
20
|
+
ports = Chunk(ServicePort(5432, 5432)),
|
|
21
|
+
options = Some("--health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5")
|
|
22
|
+
)
|
|
23
|
+
),
|
|
24
|
+
steps = ...
|
|
25
|
+
)
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
`ServicePort(inner, outer)` renders as `inner:outer`, which GitHub reads as `<host>:<container>` — so `inner` is the port a step connects to on `localhost`.
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: auto-approve-and-auto-merge-dependency-update-prs
|
|
3
|
+
title: "Auto-Approve and Auto-Merge Dependency Update PRs"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
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).
|
|
7
|
+
|
|
8
|
+
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.
|
|
9
|
+
|
|
10
|
+
The set of trusted bots is controlled by the `ciDependencyUpdateBots` setting, which takes a `Seq[DependencyBot]`:
|
|
11
|
+
|
|
12
|
+
```scala
|
|
13
|
+
import zio.sbt.githubactions.DependencyBot
|
|
14
|
+
|
|
15
|
+
ciDependencyUpdateBots := Seq(
|
|
16
|
+
DependencyBot.Dependabot,
|
|
17
|
+
DependencyBot.Renovate,
|
|
18
|
+
DependencyBot.ScalaSteward("zio-scala-steward"),
|
|
19
|
+
DependencyBot.Custom("some-other-bot[bot]")
|
|
20
|
+
)
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
- `DependencyBot.Dependabot` — matches login `dependabot[bot]`
|
|
24
|
+
- `DependencyBot.Renovate` — matches login `renovate[bot]`
|
|
25
|
+
- `DependencyBot.ScalaSteward(githubAppName)` — matches login `<githubAppName>[bot]`, where `githubAppName` is the name of the GitHub App you registered for Scala Steward
|
|
26
|
+
- `DependencyBot.Custom(login)` — matches any exact GitHub login, for bots not covered by the predefined cases
|
|
27
|
+
|
|
28
|
+
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.
|
|
29
|
+
|
|
30
|
+
> **Note:**
|
|
31
|
+
>
|
|
32
|
+
> 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.
|
|
33
|
+
|
|
34
|
+
> **Note:**
|
|
35
|
+
>
|
|
36
|
+
> `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.
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: build-a-workflow-of-only-custom-jobs
|
|
3
|
+
title: "Build a Workflow of Only Custom Jobs"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
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.
|
|
7
|
+
|
|
8
|
+
```scala
|
|
9
|
+
ciReportSuccessfulJobs := Seq.empty // no aggregate `ci` job
|
|
10
|
+
ciWorkflowPermissions := None // inherit the repository's default token permissions
|
|
11
|
+
ciConcurrency := None
|
|
12
|
+
ciWorkflowEnv := Map.empty
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
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.
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: change-the-workflow-environment
|
|
3
|
+
title: "Change the Workflow Environment"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
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:
|
|
7
|
+
|
|
8
|
+
```scala
|
|
9
|
+
ciWorkflowEnv := Map(
|
|
10
|
+
"SBT_OPTS" -> "-XX:+PrintCommandLineFlags -Djava.locale.providers=CLDR,JRE"
|
|
11
|
+
)
|
|
12
|
+
```
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: configure-dependabot-updates
|
|
3
|
+
title: "Configure Dependabot Updates"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
`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:
|
|
7
|
+
|
|
8
|
+
```scala
|
|
9
|
+
import zio.sbt.githubactions.{DependabotConfig, DependabotGroup, DependabotUpdate}
|
|
10
|
+
|
|
11
|
+
ThisBuild / ciDependabotConfig := DependabotConfig(
|
|
12
|
+
Seq(
|
|
13
|
+
DependabotUpdate("github-actions"),
|
|
14
|
+
DependabotUpdate(
|
|
15
|
+
"npm",
|
|
16
|
+
directory = "/website",
|
|
17
|
+
openPullRequestsLimit = Some(5),
|
|
18
|
+
groups = Seq(DependabotGroup("docusaurus", patterns = Seq("@docusaurus/*", "react")))
|
|
19
|
+
)
|
|
20
|
+
)
|
|
21
|
+
)
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
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.
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: configure-scala-steward
|
|
3
|
+
title: "Configure Scala Steward"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
`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:
|
|
7
|
+
|
|
8
|
+
```scala
|
|
9
|
+
ThisBuild / ciEnableScalaSteward := false
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
`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.
|
|
13
|
+
|
|
14
|
+
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.
|
|
15
|
+
|
|
16
|
+
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`.
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: control-ci-concurrency
|
|
3
|
+
title: "Control CI Concurrency"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
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:
|
|
7
|
+
|
|
8
|
+
```scala
|
|
9
|
+
import zio.sbt.githubactions.{CancelInProgress, Concurrency, Condition}
|
|
10
|
+
|
|
11
|
+
ciConcurrency := Some(
|
|
12
|
+
Concurrency(
|
|
13
|
+
group = "ci-pr-${{ github.event_name == 'pull_request' && github.event.pull_request.number || github.ref }}",
|
|
14
|
+
cancelInProgress = CancelInProgress.When(Condition.Expression("github.event_name == 'pull_request'"))
|
|
15
|
+
)
|
|
16
|
+
)
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Individual jobs can override it. A release should generally not be cancelled halfway through:
|
|
20
|
+
|
|
21
|
+
```scala
|
|
22
|
+
Job(
|
|
23
|
+
id = "release",
|
|
24
|
+
name = "Release",
|
|
25
|
+
concurrency = Some(
|
|
26
|
+
Concurrency(group = "release-${{ github.ref }}", cancelInProgress = CancelInProgress.Never)
|
|
27
|
+
),
|
|
28
|
+
steps = ...
|
|
29
|
+
)
|
|
30
|
+
```
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: customize-the-generated-ci-jobs
|
|
3
|
+
title: "Customize the Generated CI Jobs"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
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.
|
|
7
|
+
|
|
8
|
+
To adjust the generated jobs, map over them:
|
|
9
|
+
|
|
10
|
+
```scala
|
|
11
|
+
import zio.sbt.githubactions.Job
|
|
12
|
+
|
|
13
|
+
def onUbuntu22(job: Job): Job = job.copy(runsOn = "ubuntu-22.04")
|
|
14
|
+
|
|
15
|
+
inThisBuild(
|
|
16
|
+
List(
|
|
17
|
+
ciTestJobs := ciTestJobs.value.map(onUbuntu22),
|
|
18
|
+
ciBuildJobs := ciBuildJobs.value.map(onUbuntu22)
|
|
19
|
+
)
|
|
20
|
+
)
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
To write one from scratch, build it from the exported steps:
|
|
24
|
+
|
|
25
|
+
```scala
|
|
26
|
+
import zio.sbt.ZioSbtCiPlugin._
|
|
27
|
+
import zio.sbt.githubactions.{Job, Step, Strategy}
|
|
28
|
+
|
|
29
|
+
ciTestJobs := Seq(
|
|
30
|
+
Job(
|
|
31
|
+
id = "integration-test",
|
|
32
|
+
name = "Integration Test",
|
|
33
|
+
jobTimeout = Some(30),
|
|
34
|
+
strategy = Some(Strategy(matrix = Map("java" -> List("17", "21")), failFast = false)),
|
|
35
|
+
steps = Seq(
|
|
36
|
+
Checkout.value,
|
|
37
|
+
SetupJava("17"),
|
|
38
|
+
SetupSBT,
|
|
39
|
+
CacheDependencies,
|
|
40
|
+
Step.SingleStep(name = "Test", run = Some("sbt it:test"))
|
|
41
|
+
)
|
|
42
|
+
)
|
|
43
|
+
)
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
The aggregate `ci` job waits on the ids of whatever `ciLintJobs`, `ciTestJobs` and `ciBuildJobs`
|
|
47
|
+
produce, so replacing `test` with `integration-test` above is enough on its own. Set
|
|
48
|
+
`ciPullRequestApprovalJobs` only to wait on a different set than those three:
|
|
49
|
+
|
|
50
|
+
```scala
|
|
51
|
+
ciPullRequestApprovalJobs := Seq("lint", "integration-test")
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
`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.)
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: customize-the-generated-readme
|
|
3
|
+
title: "Customize the Generated README"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
The `README.md` of a project is generated by `sbt docs/generateReadme` from the introduction in `docs/index.md` and a set of `readme*` settings, so edit those instead of the file. This guide shows how to change a section and how to keep the README up to date.
|
|
7
|
+
|
|
8
|
+
To replace the title with a banner, set `readmeBanner`. When a banner is set, the `# <projectName>` title is left out unless `readmeShowTitle` says otherwise:
|
|
9
|
+
|
|
10
|
+
```scala
|
|
11
|
+
readmeBanner := "<p align=\"center\"><img src=\"logo.png\" /></p>"
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
To add to a default section instead of replacing it, append to its current value:
|
|
15
|
+
|
|
16
|
+
```scala
|
|
17
|
+
readmeContribution := readmeContribution.value + "\n\nRun `sbt prepare` before you submit a pull request."
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
To fill a section that is empty by default, such as the maintainers, assign a Markdown string:
|
|
21
|
+
|
|
22
|
+
```scala
|
|
23
|
+
readmeMaintainers := "- [A Maintainer](https://github.com/a-maintainer)"
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
An empty string for `readmeAcknowledgement`, `readmeCredits` or `readmeMaintainers` leaves the section out.
|
|
27
|
+
|
|
28
|
+
To regenerate the README after a change:
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
sbt docs/generateReadme
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
To fail a build when the committed README is out of date, run `sbt docs/checkReadme`. The generated CI workflow regenerates the README with the `update-readme` job, which is described in [ZIO SBT CI](../reference/ci.md#default-jobs).
|
|
35
|
+
|
|
36
|
+
The list of settings and their defaults is in the [ZIO SBT Website reference](../reference/website.md#readme-settings).
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: draft-releases-with-release-drafter
|
|
3
|
+
title: "Draft Releases with Release Drafter"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
`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:
|
|
7
|
+
|
|
8
|
+
```scala
|
|
9
|
+
ThisBuild / ciEnableReleaseDrafter := false
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
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`.
|
|
13
|
+
|
|
14
|
+
`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.
|
|
15
|
+
|
|
16
|
+
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`.
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: enable-netlify-deploy-previews
|
|
3
|
+
title: "Enable Netlify Deploy Previews"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
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/`.
|
|
7
|
+
|
|
8
|
+
```scala
|
|
9
|
+
ThisBuild / ciEnableDeployPreview := true
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
The feature is split across two workflows, decoupled by artifacts rather than triggering the deploy directly from a pull request event:
|
|
13
|
+
|
|
14
|
+
- 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`](../reference/website.md) 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.
|
|
15
|
+
- `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.
|
|
16
|
+
|
|
17
|
+
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).
|
|
18
|
+
|
|
19
|
+
`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.
|
|
20
|
+
|
|
21
|
+
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.
|
|
22
|
+
|
|
23
|
+
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.
|
|
24
|
+
|
|
25
|
+
#### On-demand previews
|
|
26
|
+
|
|
27
|
+
Every preview deploy costs Netlify credits. To deploy only when someone asks for it, switch the mode:
|
|
28
|
+
|
|
29
|
+
```scala
|
|
30
|
+
import zio.sbt.githubactions.DeployPreviewMode
|
|
31
|
+
|
|
32
|
+
ThisBuild / ciEnableDeployPreview := true
|
|
33
|
+
ThisBuild / ciDeployPreviewMode := DeployPreviewMode.OnDemand
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
`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:
|
|
37
|
+
|
|
38
|
+
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.
|
|
39
|
+
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.
|
|
40
|
+
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.
|
|
41
|
+
|
|
42
|
+
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`.
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: keep-the-workflow-in-sync
|
|
3
|
+
title: "Keep the Generated Workflow in Sync"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
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:
|
|
7
|
+
|
|
8
|
+
```bash
|
|
9
|
+
sbt ciCheckGithubWorkflow
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
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.
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: publish-a-releases-docs-again
|
|
3
|
+
title: "Publish a Release's Docs Again"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
`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.
|
|
7
|
+
|
|
8
|
+
To publish the docs without the Maven release, run the CI workflow by hand with the `docs-only` input set to `true`:
|
|
9
|
+
|
|
10
|
+
```bash
|
|
11
|
+
gh workflow run ci.yml --ref main -f docs-only=true
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
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.
|
|
15
|
+
|
|
16
|
+
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.
|
|
17
|
+
|
|
18
|
+
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.
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: regenerate-workflows-on-bot-prs
|
|
3
|
+
title: "Regenerate Workflows on Bot PRs"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
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.
|
|
7
|
+
|
|
8
|
+
`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.
|
|
9
|
+
|
|
10
|
+
Things to know:
|
|
11
|
+
|
|
12
|
+
- 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.
|
|
13
|
+
- 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.
|
|
14
|
+
- 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`.
|
|
15
|
+
- Set `ciEnableRegenerateWorkflows := false` to opt out; the plugin then deletes only a `regenerate-workflows.yml` carrying its "autogenerated" header.
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: set-job-timeouts
|
|
3
|
+
title: "Set Job Timeouts"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
A job with no timeout inherits GitHub's default of six hours, which is a long time to wait for a hung build:
|
|
7
|
+
|
|
8
|
+
```scala
|
|
9
|
+
Job(id = "test", name = "Test", jobTimeout = Some(25), steps = ...)
|
|
10
|
+
|
|
11
|
+
// or on an existing job
|
|
12
|
+
ciTestJobs := ciTestJobs.value.map(_.withTimeout(25))
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
> **Note:**
|
|
16
|
+
>
|
|
17
|
+
> `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.
|