How to export issues to CSV file using GitHub CLI

When you want to import a GitHub issue into another issue management system, use the GitHub CLI to export the issues to a file and then import that file into another issue management system.

Upon evaluating different import methods available in JIRA, I found CSV files to be the easiest format to import. Therefore, I exported GitHub issues into a CSV file.

This article shares how I exported to a CSV file then and the trial and error process I went through to get there.

To execute the steps described in this article, you must first install the GitHub CLI. Refer to the following article for instructions on installing the GitHub CLI.

目次

Issue is in the repository

Unlike a dedicated issue management system like JIRA, GitHub issues are repository-based. Therefore, when exporting, you work on a repository-by-repository basis.

Clone Repository

Clone the repository containing the issue you wish to export. No special options are needed, and the cloning process can be conducted as usual.

% gh repo clone ExampleUser/ExampleRepo

Once the cloning is complete, go into the repository directory.

% cd ExampleRepo

Export issues

To export an issue, utilize the GitHub CLI to retrieve the issue. The author had never exported an issue before, so it took a lot of trial and error. This article uses an issue from the repository in my book “基礎から学ぶARKit” as an example.

Retrieve issues in batches

The command gh issue list can be run to retrieve a batch of issues at once. I began by executing this command.

% gh issue list

Showing 1 of 1 open issue in akirark/LearnARKit

#34  読者質問への回答を行う    about 3 minutes ago

Specify status

I retrieved the issues, but the number of issues was small. So I checked the gh issue list options and found that the state option can be used to specify the state of the issue to be output.

The following three values are available.

  • open: Only open issues
  • closed: Only closed issues
  • all: All issues

When exporting to a CSV file, I want to export open and closed issues to separate files, so that I would use open and closed, but I used all because I want to display them in the shell first.

% gh issue list --state all

Showing 26 of 26 issues in akirark/LearnARKit that match your search

#34  読者質問への回答を行う                                 about 10 minutes ago
#32  CHAPTER01/00_Assets/Chairフォルダを...  bug            about 5 months ago
...

This repository has a small number of issues, but the output was generated regardless of the state.

Specify the number of items

This repository has a small number of issues, so there is no need to specify this. Still, a large repository will only output 30 issues unless the limit option is used to specify the maximum number of outputs. For example, the following will output up to 1000 issues.

% gh issue list --limit 1000 --state all

Output in JSON

Before exporting to a CSV file, gh will output the issue in JSON. Use the json option to output in JSON.

% gh issue list --limit 1000 --state all --json

When I run it, I get the following error message.

Specify one or more comma-separated fields for `--json`:
  assignees
  author
  body
  closed
  closedAt
  comments
  createdAt
  id
  labels
  milestone
  number
  projectCards
  projectItems
  reactionGroups
  state
  title
  updatedAt
  url

When outputting in JSON, it seems necessary to specify the fields to be output; it is sufficient to export the information you wish to include in the CSV, so the author decided to export the following fields.

  • number: The issue ID
  • title
  • body
  • state
  • createdAt: Created date
  • updatedAt: Updated date
  • milestone

Perform the following.

% gh issue list --limit 1000 --state all --json 'number,title,body,state,createdAt,updatedAt,milestone'
[
  {
    "body": "読者質問があったので回答する。\r\nOSのバージョンが上がった影響があった様子である。\r\n",
    "createdAt": "2023-05-12T13:23:49Z",
    "milestone": {
      "number": 1,
      "title": "support_revision_1",
      "description": "",
      "dueOn": null
    },
    "number": 34,
    "state": "OPEN",
    "title": "読者質問への回答を行う",
    "updatedAt": "2023-05-12T13:51:16Z"
  },
...

The issue was output in JSON.

Transforme to CSV

JQ is a JSON processing and formatting tool that allows you to specify the processing and formatting methods available for the jq option of gh, and gh outputs the processed and formatted results according to the specified methods.

We can use it to convert JSON to CSV. The code to transform to CSV is the following.

map([.number, .state, .createdAt, .updatedAt, .milestone.title, .title, .body] | @csv) | join("\n")

This is specified in gh with the jq option.

% gh issue list --limit 1000 --state all --json 'number,title,body,state,createdAt,updatedAt,milestone' --jq 'map([.number, .state, .createdAt, .updatedAt, .milestone.title, .title, .body] | @csv) | join("\n")'
34,"OPEN","2023-05-12T13:23:49Z","2023-05-12T13:51:16Z","support_revision_1","読者質問への回答を行う","読者質問があったので回答する。
OSのバージョンが上がった影響があった様子である。
"
...

The rest is redirected to a file instead of a shell, and the states open and closed are written to separate files for convenience when importing into JIRA.

Investigation of the jq command (added May 13, 2023)

I used ChatGPT to investigate the formatting and processing methods specified in the jq option. I have included the research process in this article.

Summary

Using the GitHub CLI, I exported GitHub issues to CSV by following the issue Get -> JSON -> CSV process. The repository I wanted to migrate this time had a small number of issues, so the method described in this article worked fine.

However, suppose the number of issues exceeds the number that can be written out at one time on the gh issue list. In that case, splitting the list into multiple issues may be necessary.

Also, since comments are multiple and nested, it is impossible to convert them to CSV. Therefore, if you want to export comments, it is better to export them in JSON.

著書紹介

Authored Books

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

この記事を書いた人

Akira Hayashi (林 晃)のアバター Akira Hayashi (林 晃) Representative(代表), Software Engineer(ソフトウェアエンジニア)

アールケー開発代表。Appleプラットフォーム向けの開発を専門としているソフトウェアエンジニア。ソフトウェアの受託開発、技術書執筆、技術指導・セミナー講師。note, Medium, LinkedIn
-
Representative of RK Kaihatsu. Software Engineer Specializing in Development for the Apple Platform. Specializing in contract software development, technical writing, and serving as a tech workshop lecturer. note, Medium, LinkedIn

目次