A Rust tool to check TODO comments against issue and merge request status across GitHub and GitLab repositories.
To check for stale references, you need API tokens for GitHub and GitLab.
If you have glab and gh installed and authenticated,
you can use scripts/autoauth-todo-curator.sh to run todo-curator (if it's on the PATH),
which will automatically use glab and gh for authentication.
GitLab auth scheme is selected by GITLAB_TOKEN_TYPE (or GL_TOKEN_TYPE):
pat(default): personal access token, sent asPRIVATE-TOKEN.oauth2(aliasesoauth,bearer): OAuth2 token, sent asAuthorization: Bearer.job: GitLab CI job token, sent asJOB-TOKEN.
Unknown values are an error.
Inside GitLab CI, set GITLAB_TOKEN=$CI_JOB_TOKEN and GITLAB_TOKEN_TYPE=job.
If neither GITLAB_TOKEN nor GL_TOKEN is set and GITLAB_TOKEN_TYPE is unset,
CI_JOB_TOKEN is used automatically in job mode.
A job token can only read what the CI job token allowlist permits.
For local development, you can source auth-setup.sh before running the API integration tests.
The tests for each forge are not run unless corresponding feature flag,
test-integration-github or test-integration-gitlab, is enabled.
In each pattern, #ref must be a valid reference (see supported formats below).
- single reference:
TODO(#ref)- a space after
TODOis permitted.
- a space after
- alternate:
TODO #ref: - multiple references:
TODO(#ref, #ref, #ref)- multiple references are not supported without parentheses.
- work-item in the current repo:
#123 - work-item in another repo:
group/subgroup/repo#123 - merge request for the current repo:
!123 - merge request in another repo:
group/subgroup/repo!123 - epic under the current project's supgroup:
&123- this uses the "most specific" path, i.e. for
group/sub1/sub2/project, the short-form epic reference only checks for epics ingroup/sub1/sub2.
- this uses the "most specific" path, i.e. for
- full path to an epic:
group/subgroup&123 - group-level work-item:
group#123- only a single-segment group is supported in this short form,
since
group/subgroup#123means a work-item in the projectgroup/subgroup. - the full URL form
gitlab.com/groups/group/subgroup/-/work_items/123supports nested groups. - checked via the GitLab GraphQL API.
- only a single-segment group is supported in this short form,
since
- Full URL:
https://gitlab.com/group/subgroup/repo/-/issues/123- Schema is optional (the reference can start with
gitlab.comorgithub.com). - This works for GitLab work-items (project and group level), merge-requests, and epics, and for GitHub issues and pull-requests.
- Schema is optional (the reference can start with
- Shortened URL:
github.com/owner/repo#7
The "short" versions of references are generally preferred.
When todo-curator encounters full URLs,
it prints TODO references that can be shortened with a suggested shorter form.
todo-curator --usage-spec prints a usage spec.
With the usage CLI installed, generate completions from it, e.g. for zsh:
usage generate completion zsh todo-curator --usage-cmd "todo-curator --usage-spec" --installSupported shells include bash, zsh, fish, PowerShell, and nushell.
This repository ships an action that installs todo-curator from its GitHub
releases with ubi and runs a check:
- uses: rigetti/todo-curator@v0.1.12
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
gitlab-token: ${{ secrets.MY_GITLAB_TOKEN }} # only for GitLab references
command: check-all # or check-closed / check-invalid /
# check-mr-todos / validate-auth
args: --format json # optional
path: . # optional
exclude-file-regex: "" # optional; a single regex, not a listThe version to install defaults to the ref the action was called with, so
@v0.1.12 above installs v0.1.12 and there is only one version to pin.
secrets.GITHUB_TOKEN covers both the download and same-repository references.
References to other repositories, or to GitLab, need a token with access to
them. check-invalid needs no credentials at all. A token is also what keeps
the install off GitHub's unauthenticated API rate limit, which can be as low as
60 requests per hour per IP.
If a repository's own tests or docs contain TODO-shaped text, set
exclude-file-regex or the checks will flag them.
Releases go through a release PR, with release-plz
configured in release-plz.toml.
Merging the release PR creates a GitHub release; nothing else does.
- Run the
Prepare releaseworkflow onmain. It opens or updates a release PR (version bump and changelog) from the Conventional Commits since the last release, with release-plz's defaults: any commit that changes a packaged file counts, whatever its type. For example, a history of onlychore(deps)lockfile bumps still opens a patch-bump PR, and no new commits opens none. In 0.x, a breaking change bumps the minor version, anything else the patch. - Approve the release PR's workflow runs.
Because release-plz opens and updates the PR with
GITHUB_TOKEN, itspull_requestruns wait inaction_requireduntil a maintainer approves them in the Actions tab ("Approve and run" on the PR or the run). Each push by release-plz needs a new approval. If no runs appear, close and reopen the PR instead;ci.ymlruns onreopened. The required-checks ruleset is strict, so after any later push tomain, either click "Update branch" on the PR, or dispatchPrepare releaseagain and approve the new runs. Then review and merge. - Merging starts the
Releaseworkflow (any merge method). It tags the merge commit, creates a draft release, builds the binaries, attaches them, and only then publishes the release. It runs for merged PRs labeledrelease, which release-plz adds. If the build or publish fails, use "Re-run failed jobs" on that run. If a release PR was merged without itsreleaselabel, dispatchReleaseonmain: it releases the version inCargo.tomlif it has no tag yet.
For a build of unmerged work, run Prepare prerelease on a branch.
It pushes a tag only; nothing lands on the branch.