Reference

Sources

Where aki reads from: GitLab, GitHub and Jira Cloud.

Without configuration

aki uses gitlab.com when glab is installed and github.com when gh is, with their own logins. Nothing to write.

aki doctor

It checks every source and prints who you are signed in as.

Declare your sources

Declaring [[sources]] replaces the detection: list every source you want.

GitLab

[[sources]]
kind = "gitlab"
host = "gitlab.acme.io"

host defaults to gitlab.com. The token comes from $GITLAB_TOKEN when set, else from glab config get token. When the token is refused, aki has glab renew it and tries again.

GitHub

[[sources]]
kind = "github"

host defaults to github.com. The token comes from $GITHUB_TOKEN when set, else from gh auth token.

Jira

[[sources]]
kind = "jira"
site = "https://your-company.atlassian.net"
email = "you@your-company.com"
token_env = "JIRA_API_TOKEN"

Jira Cloud, with an API token. jql changes which tickets are yours; the default is:

jql = "assignee = currentUser() AND statusCategory != Done ORDER BY updated DESC"

Keys

Key	Meaning
`kind`	`gitlab`, `github` or `jira`.
`name`	Shown on the board and used by `source:` filters. Defaults to the kind. Two sources of the same kind need different names.
`host`	GitLab and GitHub: the instance.
`site`, `email`, `jql`	Jira: the site, your account, the query.
`token_env`	An environment variable holding the token.
`token_command`	A command that prints the token, for a keychain or a password manager.
`token_renew_command`	A command run when the token is refused, before trying again.

a token from the macOS keychain

token_command = "security find-generic-password -s aki-jira -w"

Tokens are read from the environment or a command each time. aki never stores one.

What is read

Source	Items
GitLab	Open merge requests you wrote, review or are assigned to, with their threads, approvals, pipeline and branch state; issues assigned to you.
GitHub	Open pull requests you are involved in (author, assignee, commenter, mentioned), are asked to review or have reviewed, with their review threads, reviews and checks; issues assigned to you.
Jira	The tickets your query returns, with status, priority, blocking links and mentions; and the priority of tickets your changes name.

The cache

Everything read is kept in one SQLite file, ~/.cache/aki/cache.db.

The board opens at once on what was known last time, then refreshes.
A source that is down still shows what it said last, marked as such.
Discussions are read again only when the item moved; a ticket looked up for its priority is trusted for half an hour. A refresh is a handful of light requests.
It holds who spoke when and where. It holds neither what was said nor any token.

aki cache path
aki cache clear

Known limits

GitLab: merge requests where you only commented, without being author, assignee or reviewer, are not listed.
GitLab tells its history in English system notes; pushes and re-requests are read from those.
GitHub says a branch is behind its target only where the branch must be up to date to merge.
Jira: Cloud only. "Flagged" is not read; use waiting_statuses or "is blocked by" links.

PreviousConfiguration NextCommand line