====== GHIssues Plugin ======

---- plugin ----
description: Uses the GitHub API (v3) to access and display issues from the bug tracker
author     : zsmith12 
email      : zsmith12@umd.edu 
type       : syntax, helper, action
lastupdate : 2014-10-18
compatible : Ponder Stibbons, !Greebo
depends    : 
conflicts  : 
similar    : issuelinks
tags       : github, issue, bugtracker, tracker

downloadurl: https://github.com/ZJ/ghissues/zipball/master
bugtracker : https://github.com/ZJ/ghissues/issues
sourcerepo : https://github.com/ZJ/ghissues/
donationurl: 

screenshot_img : http://i.imgur.com/MxlyOc3.png
----

===== Description =====

Allows the insertion of a table showing issues from the bug tracker on a GitHub repository. Filtering by state (open/closed/all) and label are supported. The table shows issue number, title, any labels (with their assigned colors) as well as creation date/time and creator.

Each issue title is also a link to the appropriate issue page on GitHub, and there is a link to the table's equivalent issues search in the footer of the table.

GitHub API responses are cached locally and the table is only updated when upstream changes occur.

===== Installation =====

Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.

===== Examples/Usage =====

Below are code snippets and static screenshots of the plugin's output with data from the [[https://github.com/dokuwiki/dokuwiki|DokuWiki Repository]] on GitHub((Example data pulled on 2014-10-09 16:00 EST)).

==== Open Issues for a Label ====

<code>{{ghissues dokuwiki/dokuwiki label:Beginner's Project}}</code>
{{http://i.imgur.com/MxlyOc3.png}}

==== Open Issues with Both Labels ====

<code>{{ghissues dokuwiki/Dokuwiki label:feature,Beginner's Project}}</code>
{{http://i.imgur.com/x7kalRs.png}}

==== All (Open & Closed) Issues for a Label ====

<code>{{ghissues dokuwiki/Dokuwiki state:all label:feature}}</code>
{{http://i.imgur.com/WnYfbDT.png}} (Trimmed the bottom because the list is long)

==== Closed Issues for a Label ====

<code>{{ghissues dokuwiki/Dokuwiki state:closed label:feature}}</code>
{{http://i.imgur.com/1NMf63S.png}}

===== Syntax =====

Basic syntax:
<code>{{ghissues <repository> [state:<all|open|closed>] [label:<label1,label2,label3>]}}</code>

Specifically:

  * **''%%{{ghissues%%''** //(required)// marks the start
  * **''<repository>''** //(required)// gives the repository whose issues you'd like to list. Given in ''user/repo'' format, e.g. ''ZJ/ghissues''
  * **''state:<>''** //(optional)// Case sensitive. ''state:'' indicates you'd like to filter by state, and ''<>'' can be followed by one of (all lowercase):
    * **''all''**
    * **''open''**
    * **''closed''**
  * **''%%label:<>%%''** //(optional)// comma-separated list of labels to filter by. Labels are filtered using AND, i.e. on issues with both ''label1'' //AND// ''label2'' would be shown if you entered ''label:label1,label2''. **//There should be no space between the last label and the closing braces//**
  * **''%%}}%%''** //(required)// closes the pattern.

===== Configuration and Settings =====

Three user settings are available.

  * **"GitHub Cache Expiry Interval (seconds)"** sets how long DokuWiki waits before making another GitHub API request. The timer is applied on a per-request URL basis.
  * **"GitHub Account Username"** sets a user name that is sent along with GitHub API requests.
  * **"GitHub Personal OAuth Token"** To increase GitHub's rate limit from 60/hour to 5000/hour, you can provide a personal OAuth token here. More info below.

==== OAuth Token ====

GitHub allow authentication via [[https://github.com/blog/1509-personal-api-tokens|personal OAuth tokens]] which can be generated at https://github.com/settings/applications. This is nice because it avoids having to provide a username/password combination. You can also [[https://developer.github.com/v3/oauth/#scopes|control which parts of your account a token has access to]].

=== Do I need to use Oauth Tokens? ===

Short answer: probably not. There are two reasons to use one:

  - You want to look at issues from //private// repositories. To do this, you'll need an OAuth token for an account that has access to those repositories
  - You need >60 requests per hour.

This plugin does its best to minimize the number of requests it makes. It implements cacheing on DokuWiki's side together with conditional HTTP requests. The quick-and-dirty rule is that you'll generate 1 request per unique table per change to an issue on GitHub's side.

===== Development =====

=== Change Log ===

See https://github.com/ZJ/ghissues/commits/master

{{rss>https://github.com/ZJ/ghissues/commits/master.atom date}}

=== ToDo/Wish List ===

  * Empty for now