Back to overview

Run Zeitlicht in GitHub Actions

I want to …

… let a GitHub workflow change tasks, for example hand a task to testing when its pull request is merged.

Before you start

  • You need an API key of this workspace, see "Create and revoke API keys". Create one just for GitHub, with Read and write and only the boards the workflow needs.
  • The action runs the zl command line, see "Use the zl command line".
  • API keys need the Ultra plan of the Owner or Admin who creates them, and they are in beta.

Here's how

  1. In your GitHub repository, open Settings, then Secrets and variables, then Actions, and add the key as a secret named ZEITLICHT_API_KEY.
  2. Name branches after the task's short ID, such as 3f2a9c1e-login-fix, or put the short ID in the pull request title. The action finds it there.
  3. Add a workflow file in .github/workflows/ with a step uses: vince8000/zeitlicht-action@ followed by a commit SHA. Under with, set api-key to ${{ secrets.ZEITLICHT_API_KEY }}, task-from to branch or pr-title, and args to the zl command, one argument per line.
  4. In args, {task} stands for the task ID the action found. To hand the task to testing, the lines are test, request, {task}, --instructions-file, and TESTING.md, and optionally --tester with an email and --move-to with a column ID.
  5. To link the pull request as well, add a second step whose lines are link, add, {task}, and the pull request's address.
  6. Merge a pull request. The workflow run shows the command's answer, and the task shows the change.

The result

The workflow changes the task as you, with the key's name next to the change in the task's history. Every request shows up in the key's access log.

Common questions

Why one argument per line?

So that nothing in a branch name or pull request title can run as a command. The action never passes your arguments through a shell.

Can the pull request text become the test instructions?

Yes. In an earlier step, write the text into a file, with the pull request body passed in an environment variable, and give that file to --instructions-file.

Should I pin the action?

Yes, by commit SHA rather than a tag such as v1. A changed action then cannot slip into your workflow unnoticed.

Related topics