Skip to content

Latest commit

 

History

History
135 lines (103 loc) · 6.38 KB

README.md

File metadata and controls

135 lines (103 loc) · 6.38 KB
Raw

Turn your TODO comments into GitHub Issues

Build Integration Test

GitHub Action that will manage issues based on TODO/BUG/FIXME/HACK comments in the source code. Optionally issues are added to a Project Column that you specify. Source code is parsed using tdg which supports comments for almost all existing languages.

When a new todo comment is added, a new issue is created. When this comment is removed on the branch it was added, the corresponding issue is closed. Each issue is added with a special label so you can build more automation on top of it.

Screenshot

TDG result

Usage

Create a workflow file in your .github/workflows/ directory with the following contents:

Basic example

name: TODO workflow
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@master
    - name: Run tdg-github-action
      uses: ribtoks/tdg-github-action@master
      with:
        TOKEN: ${{ secrets.GITHUB_TOKEN }}
        REPO: ${{ github.repository }}
        SHA: ${{ github.sha }}
        REF: ${{ github.ref }}

NOTE: Please note that currently GitHub has 5000 requests per hour limit so if you are running it on a fresh repository and you have lots of todos in comments, you may hit this limit.

You can use this action together with parent issue updater in order to automatically keep track of child TODO items in parent issues. For that you need to use issue=123 extension in the TODO comment - see example below.

Inputs

Input Description
REPO Repository name in the format of owner/repo (required)
TOKEN Github token used to create or close issues (required)
REF Git ref: branch or pull request (required)
SHA SHA-1 value of the commit (required)
ROOT Source code root (defaults to .)
LABEL Label to add to the new issues (defaults to todo comment)
EXTENDED_LABELS Add additional labels to mark branch, code language, issue type and estimate
CLOSE_ON_SAME_BRANCH Close issues only if they are missing from the same branch as they were created on (by default)
PROJECT_COLUMN_ID Automatically create a project card in this column for new issue (none by default)
INCLUDE_PATTERN Regex to include source code files (includes all by default)
EXCLUDE_PATTERN Regex to exclude source code files (excludes none by default)
MIN_WORDS Minimum number of words in the comment to become an issue (defaults to 3)
MIN_CHARACTERS Minimum number of characters in the comment to become an issue (defaults to 30)
DRY_RUN Do not open or close real issues (used for debugging)
ADD_LIMIT Upper cap on the number of issues to create (defaults to 0 - unlimited)
CLOSE_LIMIT Upper cap on the number of issues to close (defaults to 0 - unlimited)
COMMENT_ON_ISSUES Leave a comment in which commit the issue was closed (defaults to 0 - do not comment)
CONCURRENCY How many files to process in parallel (defaults to 128)
ASSIGN_FROM_BLAME Get the author of the comment via git API from the commit hash of the comment and assign to the issue created (defaults to 0 - do not use)

NOTE: Keep in mind that you have to escape slashes in regex patterns when putting them to yaml

Flag values like CLOSE_ON_SAME_BRANCH or DRY_RUN use values 1/true/y as ON switch.

In order to get a column ID, you can go to your project and press "Copy column link" in the column 3 dots menu. ID is the last part of the URL https://github.com/owner/repo/projects/5#column-823438 (ID would be 823438).

In case you are disabling EXTENDED_LABELS, then CLOSE_ON_SAME_BRANCH logic will be broken since there will be no knowledge on which branch the issue was created (for new issues), effectively making it disabled.

Security (token)

You can of course use a private token or, if you want to use a default GITHUB_TOKEN, available for CI, you need to add read and write permissions in the Repository -> Settings -> Actions -> General -> Workflow permissions select "Read and write permissions".

Outputs

Output Description
scannedIssues Equals to 1 if completed successfully

Examples

Workflow

name: TDG
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@master
    - name: Run tdg-github-action
      uses: ribtoks/tdg-github-action@master
      with:
        TOKEN: ${{ secrets.GITHUB_TOKEN }}
        REPO: ${{ github.repository }}
        SHA: ${{ github.sha }}
        REF: ${{ github.ref }}
        LABEL: "my label"
        MIN_WORDS: 3
        MIN_CHARACTERS: 40
        ADD_LIMIT: 1
        CLOSE_LIMIT: 1
        ROOT: "src"
        PROJECT_COLUMN_ID: 824533
        INCLUDE_PATTERN: "\\.(cpp|h)$"

Note escaped regex.

If you want to only process TODO comments from master branch, modify the workflow on section like this:

on:
  # only for the master branch
  push:
    branches:
    - master

TODO comments

Comments are parsed using tdg. Supported comments: //, #, %, ;, *.

Example of the comment (everything but the first line is optional):

// TODO: This is title of the issue to create
// category=SomeCategory issue=123 estimate=30m author=alias
// This is a multiline description of the issue
// that will be in the "Body" property of the comment

Note that second line has some optional "extensions" added as metadata to the issue by tdg. Some are turned into labels and also used by parent issue updater.