Using Composer With Github Private Repositories

# Intro

If you are reading this article, Means you are already familiar with composer and want to know how you can pull your re-usable code into its own package and import it into your project using composer.

If your package is a private package hosted on github, This article will guide you to how to successfully import private packages using composer.

If you are already familiar with how to create composer package, You can directly jump to Importing private package

# Creating Composer Package

For this article, I am going to create a hello world package which exposes a method which will just print the text "Hello Word".

So lets begin by creating our very first composer package.

Create a directory called hello-world-package.

mkdir hello-world-package && cd hello-world-package

# 1. Create Hello World Class

Let's create a class which exposes a method to print the hello world message.

  • Create a new directory called src
mkdir src && cd src
  • Create a file called HelloWorld.php inside the src directory.
sudo nano HelloWorld.php
  • Copy and paste the below code and save the file.
<?php

namespace HelloWorldPackage;

class HelloWorld
{
    public static function sayHello()
    {
        echo "Hello World";
    }
}
  • Finally go back to package root directory by typing
cd ..

# 2. Add composer.json file

Now that we have a class, We can finish our package by defining a composer.json file.

  • Create a new file called composer.json by typing
sudo nano composer.json
  • Copy and paste the following code.
{
    "name": "your-github-username/hello-world-package",
    "description": "A hello world composer private package.",
    "autoload": {
        "psr-4": {
            "HelloWorldPackage": "src/"
        }
    },
    "minimum-stability": "dev",
    "prefer-stable": true
}
  • Replace your-github-username with your github profile name.
  • Save the file.

# 3. Setup Github Repository

  • create an empty repository called hello-world-package in your github account.
  • Mark the repository as private.
  • Run git init to initialize your package as a github repository.
  • If you are using https for git, Run the following command
git remote add origin https://github.com/your-github-username/hello-world-package.git
  • If you are using ssh for git, Run the following command
git remote add origin git@github.com:your-github-username/hello-world-package.git
  • Replace your-github-username with your github username before running the above command.
  • Commit and push the package code to your github repository by running the following commands
git add .
git commit -m "my first github private package"
git push --set-upstream origin master

# 4. Release package

  • go to https://github.com/your-github-username/hello-world-package
  • click on releases tab.
  • click on create a new release button.
  • Give a version number, Title, and short info about the release as shown below Github Release For version number, It is recommend to follow semantic versioning
  • Click on publish release button to release the package.

# Importing private package

Since our package is hosted on a private repository, We need to authorize composer to connect and download the package from our github repository.

There are two ways of authorizing composer to download our private package from github.

# Option 1: Authorizing composer using auth.json file

This method is Recommended only for local development and not for production usage.

  • go to https://github.com/settings/tokens
  • click on generate a new token button
  • select read:packages checkbox
  • click on generate token button
  • copy the generate github token
  • create a new file called auth.json in your project root directory and add the following to it.
{
    "github-oauth": {
        "github.com": "your-github-token"
    }
}
  • replace your-github-token with your newly created github token.

You should never commit this file to github. Doing so will give unauthorized users access to your github repositories if the token in compromised.

Now that we added our auth.json which allows composer to access our github repository, We need to instruct composer to look for the package inside our private github reposity.

  • Open composer.json file in your project and add the following code to it.
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/your-github-username/your-repository-name"
        }
    ]

By adding the above code, We are instructing composer to look for the package in our private repository.

# Option 2: Authorizing composer using SSH key

Before authorizing composer using SSH key, We need to create an ssh key on the machine where we are going to run composer.

  • Run the following command to create an SSH key
cd ~/.ssh/ && ssh-keygen -t rsa -b 4096 -C "your-email@example.com"
  • Replace your-email@example.com with the email address associated with your github account.
  • When you are prompted to enter a custom file name, Enter a file name(example : github_ssh).
  • When you are prompted to enter a passphrase, Hit enter to ignore passphrase.
  • create a new file named config in your .ssh directory by typing the below command.
sudo nano ~/.ssh/config
  • Add the following contents to the file and save it
Host *
    Hostname github.com
    User git
    IdentityFile ~/.ssh/github_ssh

Make sure to replace github_ssh with the file name you gave while creating the ssh key.

  • Run cat ~/.ssh/github_ssh.pub(replace github_ssh with your ssh key file name).
  • You will see the contents similar to below.
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQC+HvRnxwPJyUiUO/UCPKrW6mFPgJF8LxsC2l
bBePtn+UDv4Xy+eMJRgG5fbaqy2i0tvP+7T7bjVWCXJGIYunPbH978H4jrebF6Ts+dsgel4+ALf3
z0nb9oaxCQF6V+T75hPgYp+JMOl8yZZMGLN3GPadE2ye2/lskJXzYjlHyjAE6a0g+vrHmMjOULP
UrO+aHEA84f   your-email@example.com
  • Copy the contents shown.
  • Go to https://github.com/settings/keys
  • Click on New SSH Key button beside ssh keys
  • Give a title for your ssh key
  • In the key text box, Enter the SSH key contents you previously copied
  • Click on Add SSH Key button.

Now that we added the SSH key to our github account, This allows composer to access our github private repository.

Now we need to instruct composer to look for the package inside our private github repository.

  • Open composer.json file in your project and add the following code to it.
    "repositories": [
        {
            "type": "vcs",
            "url": "git@github.com:your-github-username/your-repository-name.git"
        }
    ]

By adding the above code, We are instructing composer to look for the package in our private repository.

# Final Step

Now that we have successfully authorized composer to access our github private repository, and also instructed it to where to look for our private package, We can import the package by running

composer require vendor/package-name

vendor/package name is the name you added to your composer.json file inside your package.

Example:

composer require srinathdudi/hello-world-package

# Troubleshooting

If you are having issues importing your github private packages using composer, Try the following.

  • Run composer clearcache to clear composer cache.
  • Verify you added correct github access token inside auth.json file.
  • Verify you added correct SSH key to your github account.
  • Verify if there is atleast one active release in your package repository which is not marked as pre-release.
  • Verify you have a valid composer.json file inside your package root directory.
  • Verify the package name inside composer.json file of your package matches with the package name you are trying to import.

Now that you know how to use composer with github private packages, There is nothing getting in your way from re-using your private packages with in your projects. Start building amazing things.

For more interesting posts like this, Follow me on twitter.