Using a private repo with composer and bitbucket

Setting up composer to use a private repo is pretty easy... after you've done it once. There are a few things that can trip you up, such as the naming of the package and the version to include. The docs for getting the configuration set up got me about 95% of the way there.

This guide assumes you already have a composer.json file created, and you're looking to add a new private repository to that.

Part 1: Bitbucket configuration

Composer is going to need access to your Bitbucket account in order to fetch the private git repo. An OAuth consumer can be used to give composer access.

  1. In Bitbucket, go to your "Bitbucket Settings" page<username>/

  2. Click "OAuth"

Click OAuth

  1. Click the "Add consumer" button

Click the "Add consumer" button

  1. Fill in the name, description, callback URL (this can be anything - composer won't use it but it is required by Bitbucket), select <i>This is a private consumer</i>, and select <i>Repositories: Read</i> for the permissions.

Consumer config part 1

Consumer config part 2

Part 2: Composer configuration

Using the Key and Secret from the OAuth consumer you created in part 1, you will need to add an auth.json file in composer's home directory.

vi ~/.composer/auth.json
    "bitbucket-oauth": {
        "": {
            "consumer-key": "myKey",
            "consumer-secret": "mySecret"

Part 3: Configure composer.json

  1. Add your private repository to the configuration so composer can look there for packages. The URL for the repo can be found in Bitbucket by clicking the "Clone" button in the top right of the repository view.

Package URL

"repositories": [
    "type": "git",
    "url": ""
  1. Require the package in composer.json. With either of these methods.
  • CLI: composer require aerosox/dataconverter
  • Edit composer.json
"require": {
    "aerosox/dataconverter": "master@dev"


  1. the package name in the require matches the name from the composer.json configuration for the package you are including.
// composer.json from aerosox/dataconvert

    // even though the git repo is configured as aerosox/dataconverter.git, this name *could* be anything. This is what composer is going to be looking for when it searches for the package to install.
    "name": "aerosox/dataconverter",
    "description": "Convert data formats",
    "type": "library",
    "authors": [
            "name": "Levi Jackson",
            "email": ""
    "autoload": {
        "psr-4": {
            "DataConverter\\": "src/"
    "require-dev": {
        "phpunit/phpunit": "^6.5"
  1. I saw a lot of guides say to load the package as "aerosox/dataconverter": "master-dev". I initially thought that master-dev was a composer standard, but it's not. If you want to use that, you'd want to set up an alias in the package so it can be found.
"extra": {
  "branch-alias": {
    "master-dev": "actual-branch-name"
If you have any feedback for me, I'd love to hear it - corrections, alternative paths, you name it! Send me an email