Import and export GitHub issues via CSV

Usage

Prerequisite: Install Node.js, then run this to install:

npm install -g github-csv-tools

After install, githubCsvTools --help for info on how to use, or see below.

Instructions for exporting or importing:

To Import Issues

Currently imports title, body, labels, status (closed or open) and milestones. See the test folder for example input formats.

githubCsvTools myFile.csv

To Export Issues

githubCsvTools

Option	Default	Notes
-f, --exportFileName	YYYY-MM-DD-hh-mm-ss-issues.csv	The name of the CSV you'd like to export to.
-a, --exportAttributes	number, title, labels, state, assignees, milestone, comments, created_at, updated_at, closed_at, body	Comma-separated list of attributes (columns) in the export**.
-c, --exportComments	n/a	Include comments in the export. If using in combination with --exportAttributes, id must be included.
-e, --exportAll	n/a	Export all possible values from the GitHub API. If not included, a subset of attributes (see --exportAttributes above) that are known to be compatible with GitHub import will be included in the export.

** List of all possible options for exportAttributes includes every option in the GitHub API Export. Values in child objects can be referenced using a "dot" - for example, a user's avatar_url can be accessed via user.avatar_url.

Tokens

For all actions, the tool will ask you to input a GitHub token. To obtain this token:

1. Go to https://github.com/settings/tokens
2. Click "Generate New Token"
3. Check on repo
4. Copy/paste the token provided when the tool asks for it.

Other Options

Option	Notes
-V, --version	Output the version number
-g, --github_enterprise	Your GitHub Enterprise URL. https://your-internal-githubenterprise.com/api/v3 (Reminder: do not forget the /api/v3 at the end)
-t, --token	The GitHub token. https://github.com/settings/tokens
-o, --organization	The User or Organization slug that the repo lives under. Example: For /myOrg/my-repo, this value would be myOrg.
-r, --repository	The repository name (slug). Example: For /myOrg/my-repo, this value would be my-repo.
--csvDelimiter	The CSV delimiter character (defaults to ',')
-v, --verbose	Include additional logging information.
-h, --help	See all the options and help.

Development

1. Clone the repo.
2. Browse to repo, then run npm install -g

Changelog

See CHANGELOG.md

Hosted version

This software can be used without download/install by going to repoio.com.

Running as a GitHub Action

If you wish to periodically save your issues CSV as a file in your repo, create a YAML file inside .github/workflows/

name: Run GitHub CSV Tools

on:
  schedule:
    # Runs at 00:00 UTC every Sunday
    - cron: '0 0 * * 0'
  workflow_dispatch:

jobs:
  run-csv-tools:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout repository
      uses: actions/checkout@v2

    - name: Install github-csv-tools globally
      run: npm install -g github-csv-tools

    - name: Create archive directory
      run: mkdir -p archive

    - name: Export issues to CSV
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      run: |
        cd archive
        githubCsvTools -t "${GITHUB_TOKEN}" -o YOUR_ORGANIZATION -r YOUR_REPO -e -c

    - name: Configure Git
      run: |
        git config user.email "YOUR_HANDLE@github.com"
        git config user.name "YOUR NAME"

    - name: Commit and push CSV file
      run: |
        cd archive
        git add *-issues.csv
        git commit -m "Update issues CSV" || true
        git pull --no-rebase
        git push

This will run weekly, creating a new CSV file under the "archive" folder (rename if desired), and can also be executed manually in the Actions tab of your repo.

Be sure to replace the following values:

• YOUR_ORGANIZATION: The User or Organization slug that the repo lives under
• YOUR_REPO: The repository name (slug)
• YOUR_HANDLE: Your GitHub handle
• YOUR NAME: Your name as you wish it to appear in the commit history

Thanks

• octokit/rest.js
• nodeCSV
• commander
• co
• Tim Patterson's Post on Atlassian.com