Setting up Private Packagist & BitBucket or GitHub

Hi all

This is a really quick tutorial, because frustratingly I couldn’t find one that offered me this quick guide that had an integrated approach to doing this.

I’m going to mostly cover the bits that I had to learn myself through Googling etc. in the hope that you won’t have to waste hours on Stack Overflow and so on trying to figure out how to get it working.

I’ve used composer a million times, but always as a consumer, not as a publisher. Least of all as a publisher on private packages.

This tutorial makes a couple of assumptions:

1. You understand what Composer is and how it works
2. You manage some private repositories and you’re dealing with private packagist for closed source code
3. You have a basic understanding of what an SSH key is and how to generate one

Step #1 – Get signed up for a packagist.com account

The first thing you will need to do, if you’re using private packagist for your packages, is sign up for an account on packagist.com this will allow you to privately package your code using the usual composer method.

Don’t get confused between packagist.org (which is free and for open source stuff) and packagist.com which is private, and is paid for. Though you do get a free trial which is handy.

Step #2 – Allow access to your organisation/repository

Okay, this is the bit that annoyed me the most I think. BitBucket allow you to do stuff with organisation and app access and stuff.

Both BitBucket and GitHub allow you to grant access to private repositories via an SSH key. Private Packagist provide you with their SSH key, give this key access so that Packagist can access the repository to get the information from your composer.json file.

Step #3 – Generate an SSH key for your machine or server

I’m not going to explain how to do this. A quick google will reveal this, it’s well documented.

Step #4 – The gotcha, what to do with your SSH key

This is the bit that caused me some errors and got quite annoying. I usually use my various accounts to do my pulls, checkouts, etc. so I’ve not used my SSH key with my repositories.

Your SSH key must be allowed on both Packagist and your chosen repository provider (BitBucket or GitHub, usually).

What happens is, you fire off your Composer command. This goes to Packagist.com using your SSH key and will get the information it needs about the package, then it goes off to your repository to get the appropriate code. If you enable on Packagist and not your repository the require/install will fail. If you enable it on your repository and not on Packagist, it’ll tell you that your package wasn’t found.

Step #5 – Minimum Stability

This one is well documented, but still frustratingly buried within a pile of other documentation. There are a whole heap of tags and stuff that you can use, but ultimately the stability of a package is determined from the repository itself.

Learn about how Composer works with your repository here.

Let’s assume you couldn’t be bothered to read that, you just want a quick way to test that this is set up properly. Add a tag of v1.0.0 or whatever version number you’re using. It will assume this is a release and is consequently stable.

Summary

It’s actually remarkably easy getting this running. It’s just frustrating if, at the time like myself, you don’t know what you’re doing when it comes to creating packages, let alone managing closed source stuff through it.

Once it is running, however, it becomes beautiful. It’s a very elegant of managing dependencies, and keeping multiple sets of source code up to date. And for a very small price tag of about €14 per seat, per month; it’s definitely a cost saver. (Plus whatever you spend on repository hosting as well, of course).

I realise there are plenty of ways of hosting your repositories yourself, and of hosting your packages yourself too. This approach is more suited to companies whose development teams are too busy to want to manage this infrastructure; it’s, obviously, up to you to determine whether there’s enough value in managing this in-house, or whether it makes more sense, commercially, to pay a really small fee and not have to worry about it.