A Go application that allows viewing assigned Github issues, PR reviews and notifications as tasks within Omnifocus, to allow for a more unified task management system.

To do this, the application connects to Github, then creates and manages Omnifocus tasks associated with:

• GitHub Issues and PRs assigned to you.
• GitHub PRs where your review has been requested.
• Notifications you have received.

Typically, it's run regularly using a tool like cron or launchd.

Notifications and Review Requests are given a due date of today when created.

If an issue or PR is closed or not assigned to you any more, or a notification is viewed, it will be marked complete within Omnifocus.

The application will not close issues in GitHub which are marked as complete in Omnifocus -- to close an issue or PR, it must be closed/merged within Github itself. The GitHub server is considered source-of-truth for issue and PR state; this feels safer.

github-to-omnifocus supports both GitHub and GitHub Enterprise.

• Uses tags, so needs Omnifocus 3.x
• Uses Javascript automation, so needs the Professional edition.
• Tested with Omnifocus 3.6.3.

github-to-omnifocus tries its best to live alongside your existing workflow. To this end, while it defaults to using separate projects for Issues and PRs, it supports using the same project for both, and it will avoid affecting tasks that it didn't create itself, meaning it can share a project with other tasks.

To avoid affecting tasks that it doesn't "own", when github-to-omnifocus creates tasks they are given the tag github (can be changed via configuration). Further, they are given a "type tag" to differentiate whether they are issues, PRs or whatever. Using tags in this manner allows github-to-omnifocus to live alongside other tasks within the projects it is using. github-to-omnifocus will only ever mark tasks complete that are in the configured projects and have the appropriate tags.

Within the tasks it owns, github-to-omnifocus associates a task with its corresponding GitHub issue or PR using a prefix on each task:

myorg/myrepo#123 My issue title
---------------- --------------
  |                |
  `- Prefix        `- Issue or PR title

Hopefully it is clear how myorg/myrepo#123 links tasks to their issues/PRs.

Now you know how github-to-omnifocus works and have figured whether it'll work with your workflow, it's time to get started:

1. Set up Omnifocus projects.
2. Create a personal developer token on GitHub for github-to-omnifocus to use when making requests to GitHub's API.
3. Set up application configuration.
4. Build github2omnifocus using make build.
5. Run github2omnifocus.

I run the application every five minutes using cron.

By default, the application uses the following projects, which must be created manually:

• "GitHub Assigned"
• "GitHub Reviews"
• "GitHub Notifications"

These projects can be nested within folders. The names can be customised in the configuration file.

• Open https://github.com/settings/tokens (or the equivalent on your GitHub Enterprise instance).
• Generate a new token with the following scopes:
  • repo
  • user
  • notifications

Create ~/.config/github2omnifocus/config.json. This must contain a value for the AccessToken field, which is used for API calls to GitHub. See below for how to configure github2omnifocus to use a GitHub Enterprise server.

{
    "AccessToken": "my_personal_access_token"
}

Add an APIURL field to your configuration to get the application to connect to GitHub Enterprise:

{
    "APIURL": "https://github.mycompany.com/api/v3",
    "AccessToken": "my_personal_access_token"
}

Ensure Omnifocus is open. Then run using:

make run

This will build a github2omnifocus binary and run it. It's a good way to check your setup and build the binary to run via cron (if you want to run automatically).

There are several other options that can be set in ~/.config/github2omnifocus/config.json. The following values are the defaults; you can leave out these values if they are correct for your use-case. As mentioned, the only value that must be specified is AccessToken.

{
    "APIURL": "https://api.github.com",
    "AccessToken": "",
    "AppTag": "github",
    "AssignedProject": "GitHub Assigned",
    "ReviewProject": "GitHub Reviews",
    "NotificationsProject": "GitHub Notifications",
}

• Change APIURL when using GitHub Enterprise, https://github.mycompany.com/api/v3.
• AppTag is used by the application to identify tasks that it owns, and so can update, complete and so on. It should not be used otherwise.
• The *Project configurations are used to alter the project used for tasks for each type of task that the application creates. The project need not be unique for each type of task, and it isn't necessary to give the app its "own" projects as it uses tags to identify its own tasks.

See the Issues in this repository.