Using the Discourse helper
Github is the default client. To use Github, you can optionally create a personal access token for submission using the API, or skip to have HelpMe generate and open a URL for you.
You can call it whatever you like (
helpme-client in the example below) and
check the box for the scope “repo.” You should export the token to your environment.
If provided, the token will be found the first time you run the client, and cached in your
file. If you are interested in how this works, see the developer documentation.
The main command will be to ask for help from Github. This means we will do the following:
Let’s show the most common use case, we can either ask for help for general Github, and then be prompted for the repository. You will be asked to enter a Github repository if you don’t provide one on the command line, and then if you want to record an asciinema.
$ helpme github [helpme|github] Hello Friend! I'll help you post a Github issue today. What is the Github repository to post to? (e.g., username/reponame):
or you can give the name of the repository off the bat, and skip this prompt. In the example below, I’m asking to post an issue to this repo, vsoch/helpme.
$ helpme github vsoch/helpme [helpme|github] Hello Friend! I'll help you post a Github issue today. Please describe the issue you are having: I want to post a test issue for HelpMe Github! Would you like to send a terminal recording? Please enter your choice [Y/N/y/n] : Y asciinema: recording asciicast to /tmp/helpme.5hcz3w6v.json asciinema: press <ctrl-d> or type "exit" when you're done Now using node v8.10.0 (npm v5.6.0) vanessa@vanessa-ThinkPad-T460s:~/Documents/Dropbox/Code/researchapps/helpme/helpme-cli$ echo "Look at my awesome terminal! So many issues..." Look at my awesome terminal! So many issues... vanessa@vanessa-ThinkPad-T460s:~/Documents/Dropbox/Code/researchapps/helpme/helpme-cli$ exit exit asciinema: recording finished asciinema: asciicast saved to /tmp/helpme.5hcz3w6v.json Asciinema If you need to run helpme again you can give the path to this file with --asciinema /tmp/helpme.5hcz3w6v.json Environment USER|TERM|SHELL|PATH|LD_LIBRARY_PATH|PWD|JAVA_HOME|LANG|HOME|DISPLAY Is this list ok to share? Please enter your choice [Y/N/y/n] : Y https://www.github.com/vsoch/helpme/issues [submit=>github]
If I need to do it again, I can supply the asciinema on the command line.
$ helpme github --asciinema /tmp/helpme.5hcz3w6v.json vsoch/helpme
And here is the issue created! Awesome!
If you have a python library and want to headlessly submit an issue, you can easily do that from within Python.
Here is the simplest use case - just providing a repository.
from helpme.main import get_helper helper = get_helper(name="github")
By default, the helper will not require a GitHub token (HELPME_GITHUB_TOKEN exported to the environment) and will interactively open the browser for the user. However, if you need to ensure that the token is provided, just add the argument:
helper = get_helper(name="github", require_token=True)
The client will exit with an error message if the token is not found. Now, for the simplest use case (either with or without the token) you can just provide a repository.
The above will return the user’s system information, along with environment.
However, you likely want to provide a little more context about the error.
The function also accepts an argument for title or body, and an identifier
string that can be used to generate a hash that would uniquely identify
the issue for further action once on GitHub. In the example below,
we use datalad
to generate a dictionary of output, and we will submit it to the repository
from datalad.api import wtf repo = "datalad/datalad-helpme" body = "<details>\n\n%s</details>" % wtf()
Notice that we are putting the body in a details div - this html element will hide most of the data (which is dumped json) in the actual issue, and make it easier to parse further (if desired). Next, let’s run the helper headlessly. Note that this will currently still confirm the environment variables being sent from the user.
helper.run_headless(repo=repo, body=body, title=title)
The above will still require confirmation to send the user environment,
and then will post the issue to
The user is prompted to confirm the whitelisted set of environment variables:
Environment USER|TERM|SHELL|PATH|LD_LIBRARY_PATH|PWD|JAVA_HOME|LANG|HOME|DISPLAY Is this list ok to share? Please enter your choice [Y/N/y/n] :
For a totally headless and automated route, just set
confirm to False.
helper = get_helper(name="github", confirm=False)
A string can be provided that will (by default) be converted to an md5 hash and written at the bottom of the issue. It’s useful to derive this from some string that could uniquely be used to identify the error (such as a message or metadata from an error traceback).
try: import thisdoesnotexist except Exception as exc: helper.run_headless(repo=repo, body=body, title=title, identifier=exc.msg)
If you want to generate your own identifier or hash (and not have helpme do it for
generate_md5 to False:
try: import thisdoesnotexist except Exception as exc: helper.run_headless(repo=repo, body=body, title=title, identifier="custom-id", generate_md5=False)
Given an identifier, you can use a GitHub workflow (responding to new issues) to parse and then categorize the issue, and update some flat file database (perhaps stored in a support repository?) and post an update on the issue, for example:
This issue is a duplicate of #4, closing This issue has been assigned to @vsoch
The action that you choose to take is up to you! You can take a look at the example github-support repository for an example script and GitHub action to do this.