Upload images/documents to GitHub as issue attachments
ghuc (derived from
githubusercontent and pronounced gee·huck) is a command line tool for uploading images/documents to GitHub as issue attachments. Images are then available at
https://user-images.githubusercontent.com, and documents are available as
https://github.com/<user>/<repo>/files/.... It automates the traditional flow of navigating to a repo -> opening an issue -> uploading an image -> copying the URL, which is very cumbersome. With the constant deterioration of Imgur, one-stop upload to user-images.githubusercontent.com is the next best thing for the occasional image embeds in docs or comment section/forum posts.
ghuc is partially powered by Selenium WebDriver. Tested and supported on macOS, Linux, and Windows.
Please respect GitHub's ToS and do NOT abuse this tool.
- How it works
pip install ghuc
Isolated installation through pipx is recommended.
ghuc uses Selenium WebDriver, one of the following browser and driver combos is required:
libmagicis needed for accurate MIME type detection; otherwise, MIME types are guessed based on file extensions.
$ ghuc -h usage: ghuc [-h] [-r REPOSITORY_ID] [-x PROXY] [-q] [--debug] [--gui] [--container] [--version] PATH [PATH ...] Uploads images/documents to GitHub as issue attachments. See https://github.com/zmwangx/ghuc for detailed documentation. positional arguments: PATH optional arguments: -h, --help show this help message and exit -r REPOSITORY_ID, --repository-id REPOSITORY_ID id of repository to upload from (defaults to 1) -x PROXY, --proxy PROXY HTTP or SOCKS proxy -q, --quiet set logging level to ERROR --debug set logging level to DEBUG --gui disable headless mode when running browser sessions through Selenium WebDriver --container add extra browser options to work around problems in containers --version show program's version number and exit
Not all file types are supported by GitHub. At the moment of writing the following, I quote, are supported:
GIF, JPEG, JPG, PNG, DOCX (seriously?), GZ, LOG, PDF, PPTX, TXT, XLSX, and ZIP.
The first time you use
ghuc, you'll be prompted for your GitHub credentials to log in (see How it works; you may use environment variables documented below to bypass interactive prompts). Your cookies will be cached but your credentials are never stored. Subsequent runs may phone GitHub for a new token once in a while, but ideally you should not need to log in again.
--repository-id: determines what repo shows up the URL of uploaded documents. E.g., with the default
1, the URL may be https://github.com/mojombo/grit/files/3027504/random.pdf; when set to
36502, one may get https://github.com/git/git/files/3027505/random.pdf instead. This option is cosmetic as long as a repository exists by the id. This option has no effect on image uploads as far as I can tell.
--proxy: HTTP and SOCKS (4/4a/5/5h) proxies are supported, i.e., the following protocol prefixes are recognized:
socks5h://. If no protocol is specified,
http://is assumed. The
https_proxyenvironment variable is also honored.
--container: these are mostly development/testing options; end users don't need to touch them.
--containerin particular may not be secure for end user systems.
GITHUB_TOTP_SECRET: interactive prompts for credentials are suppressed when these are provided.
GITHUB_TOTP_SECRETis needed only if you use TOTP for two-factor authentication. If you only use text messages for 2FA (highly discouraged), the login flow might work but there's no guarantee (since I don't have a setup like this; contribution welcome). If you only use FIDO U2F for 2FA, you're out of luck.
How it works
Uploading files as issue attachments requires two levels of authentication: GitHub session cookies and an
uploadPolicyAuthenticityToken (CSRF token of sort).
uploadPolicyAuthenticityToken can be found on any GitHub page with a comment box while logged in, and each one is valid for quite a while (without dedicated testing it's hard to say how long, but the validity period is at least more than a day).
ghuc logs into GitHub through Selenium WebDriver and caches session cookies as well as the token. It then performs all uploads with the cached values and doesn't touch the browser anymore (so normal uploads should be pretty fast) until the token is stale, at which point it attempts to restore the previous browser session and fetch a new token.
Why not Puppeteer?
Puppeteer is way more flexible than Selenium WebDriver from a developer's point of view, but having to download a bundled, ~100MB, non-auto-updating copy of Chromium for every install that's already outdated the next time you use it is really user-hostile. I'm also not a fan of the Node/npm ecosystem. Finally, synchronous is good for this project.
- Respect proxy option in selenium invocations (currently browsers use system proxy settings);
- Page loads: wait for
load(selenium default, wastes a lot time on slow connections);
- Handle authentication failures and allow retries (currently we assume all credentials are correct).
Copyright © 2019 Zhiming Wang email@example.com. The MIT License.
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
|Filename, size||File type||Python version||Upload date||Hashes|
|Filename, size ghuc-0.1-py3-none-any.whl (10.0 kB)||File type Wheel||Python version py3||Upload date||Hashes View hashes|
|Filename, size ghuc-0.1.tar.gz (9.1 kB)||File type Source||Python version None||Upload date||Hashes View hashes|