---
kind: guide
zz: "0.9.0"
updated: 2026-10-16
state: draft
rules: https://zriz.io/llms.txt
---
# Run zriz tests in GitHub Actions

Run `zz ci github --env staging` in your repository. It writes the workflow and stores a CI key as a GitHub secret.

## One command {#one-command}

The GitHub CLI `gh` must be signed in. Commit the workflow and the folder `.zriz`.

```sh
zz ci github --env staging
```

The command does three things:

- It writes `.github/workflows/zriz-<project>.yml` at the top level of the git repository.
- It makes a CI key and puts it in the secret `ZZ_KEY_<PROJECT>` through `gh`. The key is never shown.
- It names the GitHub secrets that the workflow needs.

The secret name is the project name in upper case, with `_` for each other character. The workflow maps it to `ZZ_KEY`.

`--env` is necessary when the default env is `local`. CI cannot use `local`, because `environments/local.json` is not in git.

Without `gh`, make a CI key on the page `/app/runners`. Store it as the secret `ZZ_KEY_<PROJECT>` yourself.

## The workflow {#workflow}

- It runs one time each day, at a time from a hash of the project name.
- It runs on a push to the default branch. No other branch starts it.
- It pins the zz version in `ZZ_VERSION`. CI does not change when zriz makes a release. Change the value to upgrade.
- It runs `zz run --env <env>` with `ZZ_KEY` (set from the secret `ZZ_KEY_<PROJECT>`).

## Secrets {#secrets}

With a deployed runner connected for the env, the secrets stay on the runner.

With no deployed runner, the runner of zz runs in the job. Each `sensitive` name comes from a GitHub secret of the same name.

Keep values of `sensitive` names out of env files that are not `local`. `zz validate` refuses them with `secret-in-file`.

## No runs left today {#no-runs-left}

When the org has no runs left for the day, the job shows a notice, not a failed test. The message gives the limit and the time when it starts again.

## Where you see the results {#results}

The page `/app` shows the status of the runs of CI. Run e-mail is off by default. [Team](https://zriz.io/docs/team.md#email) tells how to turn it on.

A CI key can start runs, cancel runs, read runs, and connect a local runner. It cannot change members, invites, the space, or other keys. An admin revokes it on `/app/runners`.