fossabot / github-resource-converter

Export GitHub Issues to CSV, JSON, and YAML: the connective tissue for data exchange

github-resource-converter

Convert GitHub resources (Issues) into CSV, etc.

[] ()

• Getting started
  • Prerequisites
  • Installation
• Usage
  • Required command-line flags
    • Example: generate a CSV of issues from a GitHub SaaS (github.com) repository
    • Example: generate a CSV of issues from a GitHub Enterprise repository
  • Optional command-line flags
  • Errors
  • Info
• License

Getting started

Prerequisites

1. github-resource-converter requires Node.js, and npm, which installs with Node.js.

2. To avoid rate-limiting, you should create a personal access token and save your personal access token:

• MacOS and Unix:

  $ mkdir -p /usr/local/etc/github-resource-center/envvars/
  $ touch /usr/local/etc/github-resource-center/envvars/.env
  $ echo "GITHUB_ACCESS_TOKEN="{your-personal-access-token-value}" > \
     /usr/local/etc/github-resource-center/envvars/.env

• Windows:

  > md -p C:\usr\local\etc\github-resource-center\envvars\
  > touch C:\usr\local\etc\github-resource-center\envvars\.env
  > echo "GITHUB_ACCESS_TOKEN="{your-personal-access-token-value}" >>
     C:\usr\local\etc\github-resource-center\envvars\.env

Installation

# Install globally to execute from a Terminal/command-line
$ npm i -g github-resource-converter

# Install as a dependency within a Node.js app
$ npm i --save github-resource-converter

Usage

The following examples assume that github-resource-converter is:

1. Installed globally, and
2. Invoked from a Terminal (command-line interface)

Open a terminal and run:

$ github-resource-converter \
  --owner gregswindle \
  --repo eslint-plugin-crc \
  --dest './docs/gregswindle-eslint-plugin-crc-issues.csv'

# Or use the grc alias:
$ grc --owner gregswindle --repo eslint-plugin-crc --dest './docs/gregswindle-eslint-plugin-crc-issues.csv'

Required command-line flags

--owner

The GitHub account name or organization name.

--repo

The name of the GitHub (or GitHub Enterprise) repository.

---

Example: generate a CSV of issues from a GitHub SaaS (github.com) repository

Given the URL for github-resource-converter (this project):

https://github.com/gregswindle/github-resource-converter.git
#                  ⬆️          ⬆️
#                  owner      repo

The minium amount of CLI flags for all issues at https://github.com/gregswindle/github-resource-converter.git would therefore be:

# Invoke https://api.github.com/repos/gregswindle/eslint-plugin-crc/issues
$ grc --owner gregswindle --repo eslint-plugin-crc

---

Example: generate a CSV of issues from a GitHub Enterprise repository

Export all issues from a private, on-premise GitHub Enterprise repoository to CSV:

# Invoke https://api.github.com/repos/gregswindle/eslint-plugin-crc/issues
$ grc --host api.ecorp.com \
  --owner evilcorp \
  --path-prefix 'api/v3'
  --repo ecoin \

---

Optional command-line flags

--dest

The destination path and file name of the CSV.

Default value: ./issues.csv.

--host

The name of the GitHub (or GitHub Enterprise) repository.

Default value: api.github.com.

--path-prefix

For GitHub Enterprise instances, the value that must occur to fulfill a REST API v3 request, e.g., api/v3/.

Default value: "" (an empty string).

--protocol

The access mechanism for the requested repository.

Default value: https:.

Errors

Errors are written to the console (stdout) as JSON:

# Attempt to fetch issues from a repository that doesn't exist
$ grc --owner repo --repo foobar
[github-resource-converter] 2018-03-12T07:44:36.727Z ERROR HttpError: {
  "name": "github-resource-converter",
  "hostname": "localhost",
  "pid": 32036,
  "level": 50,
  "err": {
    "message": {
      "message": "Not Found",
      "documentation_url": "https://developer.github.com/v3"
    },
    "name": "HttpError",
    "stack": "HttpError: {\"message\":\"Not Found\",\"documentation_url\":\"https://developer.github.com/v3\"}\n    at response.text.then.message (/Users/swindle/Projects/github/gregswindle/github-resource-converter/node_modules/@octokit/rest/lib/request/request.js:56:19)\n    at <anonymous>\n    at process._tickCallback (internal/process/next_tick.js:188:7)",
    "code": 404
  },
  "msg": {
    "message": "Not Found",
    "documentation_url": "https://developer.github.com/v3"
  },
  "time": "2018-03-12T07:44:36.727Z",
  "v": 0
}

Info

The --help flag displays all options:

$ grc --help
Convert GitHub resources (Issues) into CSV, etc.

  Usage
    $ grc [options] [info]
    $ github-resource-converter [options] [info]
  Options
    --dest, -o       The CSV's destination path and file name.
                      [Default: './issues.csv']
    --host, -h        The domain name of the server. Set this value
                      for GitHub Enterprise instances.
                      [Default: 'api.github.com']
    --owner, -o       The GitHub account name or organization name.
    --path-prefix, -p For GitHub Enterprise instances, the value that
                      must occur to fulfill a REST API v3 request, e.g.,
                      'api/v3/'.
                      [Default: '']
    --protocol, -s    The access mechanism for the requested repository.
                      [Default: 'https:']
    --repo, -r        The name of the GitHub (or GitHub enterprise)
                      repository.
  Info
    --help            Show this dialog.
    --version         Display the installed semantic version.
  Examples
    $ grc --owner github --repo hub
    // => Exported CSV to /path/of/cwd/issues.csv.

    $ grc --owner github --repo hub -dest './reports/issues/YYYY-MM-DD.csv'
    // => Exported CSV to /path/to/reports/issues/2018-05-10.csv.

    $ grc --owner repo --repo foobar
      [github-resource-converter] 2018-03-12T07:36:31.681Z ERROR HttpError: {
      'name': 'github-resource-converter',
      'hostname': 'localhost',
      'pid': 30937,
      'level': 50,
      'err': {
        'message': {
          'message': 'Not Found',
          'documentation_url': 'https://developer.github.com/v3'
        },
        'name': 'HttpError',
        'stack': 'HttpError: {"message":"Not Found","documentation_url":"https://developer.github.com/v3"}
      at response.text.then.message (/Users/swindle/Projects/github/gregswindle/github-resource-converter/node_modules/@octokit/rest/lib/request/request.js:56:19)
      at <anonymous>
      at process._tickCallback (internal/process/next_tick.js:188:7)',
        'code': 404
      },
      'msg': {
        'message': 'Not Found',
        'documentation_url': 'https://developer.github.com/v3'
      },
      'time': '2018-03-12T07:36:31.681Z',
      'v': 0
    }

Use the --version flag to see which version you have installed:

$ github-resource-converter --version
# => 1.0.0-alpha

License

MIT © Greg Swindle