API and integrations
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 writeand only the boards the workflow needs. - The action runs the
zlcommand line, see "Use the zl command line". - API keys need the Ultra plan of the
OwnerorAdminwho creates them, and they are in beta.
Here's how
- In your GitHub repository, open Settings, then Secrets and variables, then Actions, and add the key as a secret named
ZEITLICHT_API_KEY. - 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. - Add a workflow file in
.github/workflows/with a stepuses: vince8000/zeitlicht-action@followed by a commit SHA. Underwith, setapi-keyto${{ secrets.ZEITLICHT_API_KEY }},task-fromtobranchorpr-title, andargsto thezlcommand, one argument per line. - In
args,{task}stands for the task ID the action found. To hand the task to testing, the lines aretest,request,{task},--instructions-file, andTESTING.md, and optionally--testerwith an email and--move-towith a column ID. - To link the pull request as well, add a second step whose lines are
link,add,{task}, and the pull request's address. - 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.