Nightly Patch Machine


    1.2.1 • Public • Published

    Todo 2 Issue

    CLI tool to synchronize code-base TODO into GitHub issues.

    What does it do?

    At the first run, it:

    • finds TODOs and FIXMEs in your code
    • groups them using their text
    • creates a GitHub issue for each group with a specific label
    • optionally assigns a user to the issue based on the author of the label (see authorsByEmail configuration option)
    • references the issue in the code-base like TODO(#123) Do something

    When ran again, it:

    • discovers new TODOs and handles them with the steps above
    • updates GitHub issues with current location of the TODOs (file and line)
    • closes GitHub issues with no corresponding TODO in the code-base

    The tool works with a sub-set of issues tagged by a specific label (by default that is TODO). This label should not be assigned to issues manually, because such issues will be closed on the next run as there are no corresponding TODOs in the code-base.


    npm i todo2issue --save-dev


    yarn add todo2issue --dev


    The tool is configurable through package.json.


    First you need to ensure that the repository property is present and properly populated:

      // ...
      "repository": {
        "type": "git",
        "url": "git+"
      // ...


    Then you should configure behavior of the tool using todo2issue property:

      // ...
      "todo2issue": {
        "filePatterns": [
        "issueLabel": "TODO",
        "branch": "develop",
        "authorsByEmail": {
          "": "goce-cz"
      // ...  
    • filePatterns - a list of glob patterns matching files in which the tool should search for TODOs
      • .gitignore files are respected
      • defaults to ['**/*.[tj]s?(x)'] (JavaScript and TypeScript files)
    • issueLabel - name of the label that defines a set of GitHub issues governed by the tool
      • this label should not be used for anything else than for the purpose of this tool
      • this label MUST NOT be assigned / unassigned manually
    • branch - name of the branch to be used when referencing code from the generated issues
      • defaults to active Git branch, but it is highly recommended fixing this in the config
    • authorsByEmail - mapping between email of a commit author and a GitHub username
      • if present, authors of TODOs are assigned to the created issues
      • if present, and a mapping for particular email is missing, the sync fails (can be overridden by --ignore-unresolved-users)
      • if the emails and/or usernames are considered sensitive, one can supply the mapping as a JSON object serialized into a AUTHORS_BY_EMAIL environment variable

    GitHub token

    The tool needs GitHub personal access token to interact with GitHub API on your behalf. You can provide it in various ways:

    • through an GITHUB_TOKEN environment variable
    • through .env file with GITHUB_TOKEN variable
      • needs reside in the directory where the tool is executed
    • through the --token command line option


    Ensure you're running the commands in the root directory of your project - where package.json resides.

    Full sync

    Simply run the tool with no parameters:


    This will perform create, update and close issues using the configuration specified in package.json. Newly discovered TODOs will be updated to reference the issues that were created. This will yield a change in the code-base. Make sure you commit and push these changes.


    todo2issue --dry-run

    This will simulate the full sync, but it won't write anything to GitHub. Todos will still be updated with references, but the issue numbers will be just sequentially generated locally.

    This is useful for validating settings and TODO discovery. Each mocked operation is also logged into the console, and you can review the issues about to be created in detail before running the sync for real.

    DO NOT COMMIT the generated changes from a dry-run since the TODOs don't reference actual issues, but rather some fake numbers.

    ROLL BACK the changes before making a real sync!


    The tool's commandline API is self-descriptive through the standard --help option.

    todo2issue --help


    npm i todo2issue

    DownloadsWeekly Downloads






    Unpacked Size

    141 kB

    Total Files


    Last publish


    • salsita-npm