Linking Github and Lighthouse

Github is a hosted source code repository for projects managed with the git SCM system.

Lighthouse is a hosted bug/issue tracking system.

You can link the two so that you can embed Lighthouse ticket numbers in your Git commit messages and automatically change the status of Lighthouse tickets when you commit.

The steps involved in linking the two applications are listed on the site but they are a little difficult to find. Here are the steps that I used to link the sites.

I'm using private repositories on github, but that shouldn't matter.

1: On Lighthouse, generate a token to use from github.

1.1: Go to 'My Profile' in the top right corner of each page. In the right hand side bar you will see 'Create a Token' and a 'choose an account' pulldown. Select the Account you want to send messages to - I just have one account.

1.2: A panel will appear asking you to enter a label - this will identify the token in a list on Lighthouse. I call mine something like myproject_github. Select 'full access' for github linkage as it has to update your Lighthouse database. And then select the Project that you want to link to. This can be a single project or all of them. You can have multiple tokens so I would recommend one token per project.

1.3: Create the token and a record will appear in the right hand panel with the project name, your label and a grayed out hexadecimal string.

2: On Github go to the linked repository in your account

2.1: In the light yellow panel, click on the 'edit' Button next to the repository name (not the other edit links)

2.2: Above the light yellow panel is a gray bar with 'General', 'Collaborators' and 'Services' on it. Click on Services.

2.3: The returned page will have multiple panels for Twitter, Lighthouse, etc. Scroll down to the Lighthouse one.

2.4: This panel has entry boxes for 'Subdomain', 'Project id' and 'Token'. This is confusing as these names don't match up with Lighthouse!

Subdomain is the same as your Lighthouse Account name. So if your Lighthouse URL is something like http://acme.lightouseapp.com then 'acme' is what you put in subdomain.

Project Id is NOT your Lighthouse project Name - it's the NUMERIC Project Id - when you go to your Project page on Lighthouse the URL will look something like:

http://acme.lighthouseapp.com/projects/12345-myproject/overview

Your Project Id is that number - in this case 12345

Token is that hexadecimal string you just created on Lighthouse. Cut and paste that into this entry box.

Check the 'active' box and click update settings.

3: Test it out...

3.1: For the purposes of testing, create a dummy ticket in your project on Lighthouse and make a note of the ticket number - let's say ours is #21

3.2: Make some change in your local clone of your github repository and commit that to your local repository, giving it a message that includes an embedded message for Lighthouse, and then push that up to github. For example:
$ git commit -m 'Made a trivial change [#21 state:resolved]'
$ git push

The text in the square brackets is the message for Lighthouse. The project is implicit in the token you created, #21 identifies the ticket and 'status:resolved' tells Lighthouse that this code change fixes that issue. The Lighthouse docs list out the full range of messages that can be passed.

3.3: Now go back to your Lighthouse project and refresh and you should see that ticket #21 is now marked as 'Resolved' - brilliant! Click on the Ticket message and you'll see a link back to your Github repository that details the fix.

3.4: Github does not seem to retain a link to the matching Lighthouse records - but I bet that will come in due course.

That's it...

Github and Lighthouse are both pretty nice sites. I think Lighthouse still has a few wrinkles but I'm sure those will get sorted out. Both sites need better documentation/help. New features are getting reported in their blogs before any documentation appears and the laudable goal of keeping the user interface simple has led to a few things being 'implicit' when they should be 'explicit' - but overall I think the services are great and they have already made a big impact in the way I interact with some of my clients.