README

It scans PHP and YAML source files for TODO/FIXME and other configured tags, registers them as issues in trackers such as JIRA or GitHub, and injects issue keys back into comments — with labels, linked issues, assignees, and other metadata as you configure.

Motivation

Developers often leave notes in code so they do not forget to fix something — and then forget anyway. One reason is that such comments are hard to manage centrally.

Why write a comment in code instead of creating an issue? It is convenient: no issue tracker UI, no repeated form filling, and the note sits exactly where the change is needed. Whatever the reason, those comments can stay in the codebase for years.

Someone has to manage them.

This tool registers issues with the parameters you need and injects ticket IDs/keys into the original comments. That prevents duplicate issues and makes it easy to jump from a tracker ticket to the right place in code.

How it works

1. Detect a TODO (or other configured tag) in a comment.
2. Create an issue in the issue tracker (list of supported).
3. Inject the ticket key into the comment and save the source file.

See latest benchmark here.

According to benchmark TODO Registrar became quicker 20% since version 4.0.0.

Using

Basic usage:

1. Create a configuration file.
2. Run the CLI with the needed command line options.
3. Commit updated files. You can configure a CI job to run the tool and commit changes automatically.

Prepared ways to run:

1. TODO Registrar Action for GitHub repositories.
2. Docker container.
3. PHAR file.
4. Composer package.

For GitHub-hosted repositories, the GitHub Action is the simplest option.

Docker provides a fully isolated environment — no dependency on your local PHP version or Composer packages.

A single PHAR file also avoids dependency conflicts, but you must match PHP version and extensions on the host.

The Composer package is the most common integration, but less flexible than Docker or PHAR.

Documentation references

1. Processing flow — what happens on each run
2. Features — index of all capabilities
3. Command line options
4. Configuration:
   1. General config
      1. Config format:
         1. YAML file
         2. PHP file
         3. YAML from STDIN
   2. Inline config
   3. Issue trackers:
      1. GitHub
      2. GitLab
      3. JIRA
      4. Redmine
      5. Yandex Tracker
5. Supported formats of comments
6. Integration on CI
7. Customization

Supported Issue Trackers

Issue Tracker	Description
GitHub	See description of configuration. Supported via API tokens.
GitLab	See description of configuration. Supported via API tokens (HTTP Token or OAuth).
JIRA	See description of configuration. Supported via API tokens.
Redmine	See description of configuration. Supported via API keys or Basic Auth.
Yandex Tracker	See description of configuration. Supported via OAuth tokens.
Other Issue Trackers	Request an implementation through the issues section or see customization section to do it yourself.

GitHub Actions based on the project

• TODO Registrar Action — register issues and create Pull Request on GitHub.
• TODO Registrar Statistic Action — add sticky-comment Pull Request on GitHub with statistic about not registered TODOs code

Articles

RU: https://habr.com/ru/articles/832994/

Contributing

Read contributing instructions.