https://github.com/iensu/org-github-issues
A tool for creating org TODOs out of open github issues
https://github.com/iensu/org-github-issues
emacs github-issues org-mode todo
Last synced: 7 months ago
JSON representation
A tool for creating org TODOs out of open github issues
- Host: GitHub
- URL: https://github.com/iensu/org-github-issues
- Owner: iensu
- License: gpl-3.0
- Created: 2018-03-18T07:59:33.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2022-10-28T09:58:29.000Z (almost 3 years ago)
- Last Synced: 2025-03-18T17:06:10.093Z (7 months ago)
- Topics: emacs, github-issues, org-mode, todo
- Language: Emacs Lisp
- Homepage:
- Size: 94.7 KB
- Stars: 20
- Watchers: 2
- Forks: 4
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# org-github-issues
[](http://spiceprogram.org/oss-sponsorship)
A helper function to create org-mode TODOs out of open issues and review requests in a github repository.
## Installation
### Using straight.el
An example of how you can install this package using [straight.el](https://github.com/raxod502/straight.el):
```org
(use-package org-github-issues :straight (org-github-issues :host github :repo "iensu/org-github-issues")
:defer t
:config
(setq org-github-issues-user "iensu" ;; Specify Github user
github-repositories '("dekorateio/dekorate" "quarkusio/quarkus") ;; My repositories
org-github-issues-org-file "~/Documents/org/github.org" ;; My org file
org-github-issues-tags '("github" "triage") ;; Always add these labels
org-github-issues-issue-tags '("issue") ;; Add these only on issues
org-github-issues-pull-tags '("pull") ;; Add these only on pull requests
org-github-issues-auto-schedule "+0d" ;; Enable automatic scheduling
org-github-issues-filter-by-assignee t ;; Enable filter by assignee
org-github-issues-headline-prefix t) ;; Prefix all headlines with repository name
(mapcar (lambda (r) (run-with-idle-timer 3600 t (lambda () (org-github-issues-sync-issues r)))) github-repositories)) ;; When idle for an hour loop over my projects and sync
```
## Usage
Before use you need to set the variable `org-github-issues-org-file` to point to an existing file in which to write the fetched issues.
In the specified file, create a header for each of your github projects, .e.g `iensu/org-github-issues`.
Each header must match the repository name (OWNER/REPO) **exactly**.
Each header can be a top level header or nested and may optionally contain tags:
```org
* Emacs
** iensu/org-github-issues
** sigma/gh
** magit/forge :magit:
** magit/magit :magit:
* Other projects
** foo/bar
```
Any header that doesn't match the (OWNER/REPO) pattern will be ignored.
After setup you can run one of the following commands:
- `M-x org-github-issues-sync-issues` Will prompt you for the repository you want to fetch issues for.
- `M-x org-github-issues-sync-pulls` Will prompt you for the repository you want to fetch issues for.
- `M-x org-github-issues-sync-all` Will directly fetch all issues and pull requests for all repositories found in the `org-github-issues-org-file`.
## Authentication
If you are experiencing authentication issues you need to set `org-github-issues-user` to the user you want to authenticate with and then [create a Personal Access Token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token).
If you want to track private repositories you will need to select the **repo** scope and **org:read** if you want to also read repositories belonging to your organizations. See [this issue](https://github.com/octokit/octokit.net/issues/1775) for more info.
You can provide the token by using `auth-sources` and add an entry to your `~/.authinfo.gpg` file ([this article](https://www.masteringemacs.org/article/keeping-secrets-in-emacs-gnupg-auth-sources) gives a good introduction to working with `auth-sources`):
```
machine org-github-issues login password
```
The less secure way is to set `org-github-issues-token`, but please go with the `auth-sources` option if your token has access to private repositories.
## Customization
The following custom options are available:
| Option | Type | Description | Default Value |
|--------------------------------------|----------------------------------|--------------------------------------------------------------------------------------|------------------------------|
| org-github-issues-user | string | **REQUIRED** Github user name to use for authentication | nil |
| org-github-issues-org-file | string | Path to an existing `org-mode` file in which to write issues | "~/Dropbox/org/projects.org" |
| org-github-issues-filter-by-assignee | boolean | Flag to enable filtering issues by assignee. | nil |
| org-github-issues-assignee | string | The assignee to use for filtering | `user-login-name` |
| org-github-issues-headline-prefix | boolean | Flag to enable prefixing headlines with the repository name | nil |
| org-github-issues-auto-schedule | string | Threshold for automatically scheduling new issues | "+0d" |
| org-github-tag-transformations | alist :value-type (group-string) | An alist with trasnformations to apply to github labels when converting them to tags | '(("[\s/-]+" "_") |