GitFocus

Automate entering GitHub & GitLab issues into OmniFocus

If you needn’t read more, download GitFocus from GitHub.

I recently started a new job where all of our documentation is managed through git and a lot of my work comes from issues and merge requests filed on GitLab. To keep track of them, I turn to OmniFocus, no surprise.

It was clear by the second day that I didn’t fancy making all the actions by hand, though. Because of security concerns, I couldn’t turn to a web-based service like Zapier to help, so I decided to write an AppleScript. That’s more my pace anyhow.

How the scripts work

I had two goals: make the action title attractive and save it to an OmniFocus project corresponding to the GitLab project.

Fortunately for me, GitLab and GitHub alike have page titles that are information-rich, and it’s trivial to use AppleScript to fetch those titles from Safari. On the other hand, I had no desire to deal with processing that text in AppleScript. For that, I wrote two small Perl scripts, which feed their results back in to the AppleScript.

Together, they perform four primary tasks:

  1. Collect information about the web page from Safari.
  2. Transform the page title into an action title.
  3. Based on your specifications, determine which OmniFocus project the action is saved to.
  4. Make the action in OmniFocus.

Titling

The first Perl script called is the titler, which transforms a web page title like this:

Update 'this thing' to 'that thing' and link to them from each (#8155) · Issues · content / web / support / en · GitLab

…into an action titled:

resolve ❮#8155❯ – ‘Update 'this thing' to 'that thing' and link to them from each’

I put the ticket number at the front so that both it and the titles would start in roughly the same position for each action, improving readability. The heavy angle brackets are there to help the issue numbers stand out to make them scannable.

If you want to change the verb, capitalisation or anything else about the action title, instructions can be found in the gitfocus-titler.pl file.

Sorting

The resulting action gets sorted into a corresponding OmniFocus project based on the sorter. Beware, for it to work, it must be configured.

Full instructions for how to set up the sorter are in the gitfocus-sorter.pl file. In short, the script checks if a search string is in the page title. If found, the project name is passed back to the AppleScript. For the current example, I’d use the following to save the action to the Support Pages project in OmniFocus:

print "Support Pages" if $page_title =~ m`content / web / support`;

Action Creation

All being well, once the script has all the information it needs, it will make the action and save it to the project as specified. If the script is called on a page that’s not GitHub or GitLab, or if it fails to recognise the site correctly, the new action is dropped in the quick entry window.

Into the wild

I was content leaving this in a rough state for myself, but hearing about my work, Rose’s ears perked up. I shared the scripts with her and she decided she wanted a little more information in her actions. With a quick bit of JavaScript wizardry, she had the script saving the issue content and author in the notes field. Then, with thanks to Ken Case, she added a button to reveal the created action in OmniFocus.

After all the work, she thought we should write it up to share with others. I agreed, but if it were to be presented to a general audience, I wanted sharp edges padded where possible, and where not, explained. Thus, I wrote up some documentation and added a little error handling, particularly because the issue content and author are prone to failure, should GitLab change their page markup.

Get GitFocus

Perhaps unsurprisingly, GitFocus lives on GitHub. You can always download the latest version there.

Issues, Bugs, Feature requests

Should you encounter any problems with the scripts, file an issue on GitHub or email me. I will review pull requests and accept those that fix bugs or add features that seem fitting.

To use GitFocus

  1. Copy all three script files to the Safari scripts folder at: ~/Library/Scripts/Applications/Safari/
  2. Edit gitfocus-sorter.pl to add your GitLab or GitHub, and OmniFocus projects.
  3. Run the AppleScript. You can invoke it from the system Scripts menu, but I recommend using a keyboard shortcut assigned with FastScripts.