Create Github issues by URL

Create Github issues by URL

As simple as a click on a link!
Try it out: Create a "comment" issue on the Khatastroffik Community board.

Objective

This Dojo demonstrates the usage of a link (encoded URL) to initiate the creation of an issue on Github. A small JavaScript module demonstrates a possible integration in web applications.

At the end, it is a matter of improving the user experience of a project, application ... offering users a smart interface to submit issues on GitHub.

Context

In order to create an issue on Github, the user needs to be registered i.e. a (free) Github account is required.

Creating an issue is usually an operation involving multiple steps like:

  1. login
  2. select the Github project/repository
  3. display the issue board
  4. create and describe a new issue - eventually including copy&paste of information related to the issue context

The proposed solution is intended to automate steps 2-3 and partially step 4.

Solution

Bare issue

A URL is used to create the issue. In its simplest form:

https://github.com/<profile>/<repository>/issues/new

Adapt the placeholders <profile> and <repository> to your needs.

Such an URL can be bound to a link on any web (application) page:

<a href="https://github.com/<profile>/<repository>/issues/new">create an issue</a>

Prefilled issue

To prefill the issue with adequate values, the link (URL encoded) may be enriched with additional key-value pairs. Among others:

key description example (value)
title the header/title of the issue create issue directly from the application UI
body the content (description) of the issue a link in the app menu should allow to create an issue directly from any app view
labels useful to categorize the issue suggestion

A resulting link URL would look like:

https://github.com/<profile>/<repository>/issues/new?title=create%20issue%20directly%20from%20the%20application%20UI&body=a%20link%20in%20the%20app%20menu%20should%20allow%20to%20create%20an%20issue%20directly%20from%20any%20app%20view&labels=suggestion

Note: All values should be encoded. To manually encode the values (e.g. for testing purpose), a free online service like https://www.urlencoder.org may be used.

Scripted issue creation

To enhance the user experience, the link may be combined with a JavaScript - as a matter of example.

This script could be used to prefill the issue with values gained from a user input form or from the actual context of the application.

The Khatastroffik blog makes use of such a script to manage eventual comments by its visitors:

<script>
  const titlePrefix = "Khatastroffik - ";
  const ghIssueURL = "https://github.com/khatastroffik/community/issues";
  const ghIssueLabels = ["khatastroffik", "comment"];
  const ghIssueTitle = `${document.title.substring(document.title.indexOf(titlePrefix)==0?titlePrefix.length:0)}`;
  const ghIssueBody = `\n\n<!-- Please write your comment above this line. Thank you. -->\nReference: ${document.URL}`;

  const builIssueURL = function (issueURL, issueLabels=["khatastroffik"], issueTitle="Khatastroffik Post Comment", issueBody="Hello!") {
    return `${issueURL}/new?labels=${issueLabels.map(encodeURIComponent)}&title=${encodeURIComponent(issueTitle)}&body=${encodeURIComponent(issueBody)}`;
  };

  window.addEventListener('DOMContentLoaded', (event) => {      
    document.querySelector('section.post-comments').innerHTML = `
<div class="post-info-label">
  This blog doesn't implement any "commenting service".<br>
  Comments are managed externally by the <b>"Khatastroffik Community"</b> on <b>GitHub</b>.<br>
</div>
<div class="post-content">
<section>
  <a title="View existing comments"
     href="${ghIssueURL}"
     onclick="window.open(this.href, 'Khatastroffik Community', 'width=930,height=720');return false;">
     View existing comments
  </a>
  &nbsp;-&nbsp;
  <a title="Add a Comment" 
     href="${ builIssueURL(ghIssueURL, ghIssueLabels, ghIssueTitle, ghIssueBody )}"
     onclick="window.open(this.href, 'Khatastroffik Community', 'width=930,height=720');return false;">
     Add a comment
  </a>
</section>
</div>
`;
    document.querySelector('section.post-comments').classList.add("ghComment");
  });
</script>

The script is integrated in the footer of each blog post, as visible below. An explanation of its usage within the blog theme can be found in the Ghostination documentation.

Conclusion

  • A github issue can be created using a URL
  • The URL can be integrated in web applications by means of a link
  • The user experience can be improved by prefilling the issue with initial contextual information, for example using a script.

Addendum

Any application (beside a standard web app/browser app) may use an (internal) service to trigger the URL i.e. to open a web browser targeting the issue creation link.

As for example, the Windows command line can be used like this:

start "" "https://github.com/khatastroffik/community/issues/new"

Note the usage of the double quotes, including an empty "".

Show Comments