GitHub bulk issue creator

Bulk opens batches of issues (or posts comments) across GitHub repositories based on a template and CSV of values. Think of it like "mail merge" for GitHub issues. It can be run locally, via Codespaces, or via GitHub Actions.

How it works

1. You create a CSV of repositories where you'd like issues opened and any fill-in fields you'd like to include in the resulting issues. It might look something like this:
2. You create a template of what you'd like to use as the basis for the resulting issue body. You can even reference those per-issue fill-in fields. If we wanted to reference the name field in the example above, it might look something like this:
   
3. You run the bulk issue creator script (either locally, via Codespaces, or via GitHub Actions - see below)
4. Customized issues (or comments) are created on your behalf for every row you defined in the CSV.
5. Profit! 🎉

Running locally

1. git clone https://github.com/benbalter/bulk-issue-creator
2. bulk-issue-creator init to create a ./config/data.csv and ./config/template.md.mustache files
3. Follow the "Setup" instructions below to customize the data file and template.
4. Export the personal access token you create as the GITHUB_TOKEN environmental variable, or add it to a .env file in the root of the repository in the form of GITHUB_TOKEN=XXX.
5. Run bulk-issue-creator to preview the output
6. Run bulk-issue-creator --write to create the issues.

Running via GitHub actions

Don't want to deal with the hassle of setting up a local Ruby environment? No worries. With a little copy/paste can use GitHub actions to open issues from the cloud!:

1. Create a new repository (public or private)

2. Follow the "Setup" instructions below to add the CSV and template to the repository.

3. If you'd like to open issues in a repository other than the one containing the action, store a personal access token you create as the PERSONAL_ACCESS_TOKEN Actions Secret within the repository settings

4. Create a .github/workflows/bulk-issue-creator.yml file with the following contents:

   on:
     workflow_dispatch:
       inputs:
         write:
           description: "Change to 'true' to create issues, leave as 'false' to preview output"
           default: "false"
           type: boolean
   
   name: Bulk issue creator
   
   jobs:
     bulk_issue_creator:
       runs-on: ubuntu-latest
       name: Bulk Issue Creator
       steps:
         - name: Checkout template and data
           uses: actions/checkout@v2
         - name: Create bulk issues
           uses: benbalter/bulk-issue-creator@v2
           with:
             write: ${{ github.event.inputs.write }}
             github_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}

5. Navigate to Actions -> Bulk issue creator -> Run Workflow and click Run Workflow to preview the output.

   Note: once you run the workflow, you can see the output by clicking Bulk issue creator in the side bar, and then clicking into the most recent run.

   

6. Repeat step 5, changing the false text input to true in the final dialog to create issues.

Setup

1. Run bulk-issue-creator init or manually create a CSV file in ./config/data.csv. The CSV must have columns for repository and title (for issues) or issue_number (for comments). All field names are case sensitive. You can also add any other columns you would like, which will be available to the template. It should look something like this:

   repository,title,project,labels
   benbalter/gman,Update GMan,GMan,"Red,Blue"
   benbalter/jekyll-auth,Update Jekyll Auth,Jekyll Auth,"Green,Blue"
   

2. Edit (or create) the ./config/template.md.mustache file in the same directory with the content you want in the issue body. You can reference CSV fields like {{project}} using the Mustache syntax. It should look something like this:

   Hey there! It looks like it's time to update {{project}}!

3. Create a personal access token with repo scope.

Templating

Templates (and issue titles) support the Mustache syntax syntax by default. Field names in the CSV should be lower case, and should use _s to separate multiple words like_this, instead of spaces.

Note: You can also use the slightly more advanced Liquid templating system by passing the liquid option (see below).

Advanced usage

Optional arguments

Options can be passed as command-line arguments when running locally or via the with: property of GitHub Actions. Both locally and when running via GitHub actions, options can also be passed via environment variables. See the table below for available options and how to pass them:

Command line	GitHub Actions with:	GitHub Actions env:	Description
--write	write:	WRITE:	Write issues to GitHub (default: false)
--comment	comment:	COMMENT:	Create comments instead of issues
--template-path	template_path:	TEMPLATE_PATH:	Path to the template file
--csv-path	csv_path:	CSV_PATH:	Path to the CSV file
--liquid	liquid:	LIQUID:	Use Liquid template engine (default: false)
--github-token	github_token:	GITHUB_TOKEN:	GitHub Token for authenticating with GitHub

Special fields

• You can add a labels or assignees column to the CSV, with a comma-separated list of labels or assignees that you'd like added to the issue.
• You can add an issue_number column to the CSV, with the issue number you'd like the comment added to. Note: You must pass the --comment flag

Adding issues to a project board

If you'd like to add created issues to a project board, I suggest adding a specific label and using actions/add-to-project to add the issue to the project board.