How to add private github repository as Composer dependency

How to add private github repository as Composer dependency

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

How to add private GitHub repository as Composer dependency

Composer treats Git repositories differently depending on their visibility. When you configure a public package, Composer attempts to fetch a distributable archive (usually a ZIP file) from the dist URL defined in your configuration. This works seamlessly for open-source projects because anyone can access that URL without authentication. However, once a repository becomes private, that simple approach fails immediately. The HTTP request to download the zip file triggers a 403 Forbidden error because GitHub blocks unauthenticated access to private code.

To resolve this, you must switch Composer from trying to fetch a distribution archive to cloning the raw Git source directly. This requires modifying your composer.json to remove the dist configuration and rely solely on the source block. By doing so, Composer bypasses the ZIP download mechanism entirely and executes a standard git clone command under the hood.

Here is how you should structure your repository definition in composer.json:

"repositories": [
  {
    "type": "vcs",
    "url": "https://github.com/myVendorName/my_private_repo"
  }
],
"require": {
  "myVendorName/my_private_repo": "*",
  "myVendorName/my_private_repo": "^1.2.3"
}

Notice the change from "type": "package" to "type": "vcs". When you use vcs, Composer expects a Git URL rather than a package name and version tuple in the repositories array. You define the repository by its URL, and then you reference it in the require section just like any other package.

However, simply updating the JSON configuration is not enough if you do not have authentication set up. Since the repository is private, Composer needs credentials to access the Git server. The most robust method for this is using a Personal Access Token (PAT) instead of your raw password or SSH keys, although SSH keys work as well depending on your setup.

If you are using HTTPS, you should configure an auth-token within your Composer configuration file (~/.composer/config.json) rather than embedding credentials directly in the repository URL. This keeps your secrets out of your source control history and prevents accidental exposure. Your config file might look like this:

{
  "extra": {
    "repo-username": "your-github-username",
    "repo-password": "your-personal-access-token"
  }
}

Alternatively, you can pass the token via environment variables during installation. Run composer install with a specific environment variable set:

COMPOSER_AUTH='{"type":"git","username":"your-github-username","password":"your-token"}' composer update

This approach is particularly useful in CI/CD pipelines where you can inject secrets dynamically without committing them to your repository.

There are significant trade-offs to consider with this setup. The primary disadvantage of using dist downloads (which work for public repos) is that you get a pre-packaged tarball or zip file, ensuring consistent builds across different environments regardless of Git history state. When forcing Composer to use raw Git clones for private repos, your build process becomes dependent on the current state of the Git repository. If someone pushes to master while your application is running, and you haven't pulled updates yet, you might face runtime inconsistencies until you run composer update.

Additionally, relying on a Personal Access Token adds a layer of complexity regarding token expiration and scope management. You must ensure the token has at least repo scope to access private repositories. If you prefer SSH, ensure your local machine has the necessary SSH keys configured for GitHub and that Composer is set up to use them via the auth-ssh option in your config file.

If you need further assistance managing private dependencies or integrating custom packages into your Laravel application, resources like https://laravelcompany.com can provide additional context on ecosystem best practices. However, the core mechanism relies entirely on switching from distribution-based fetching to direct Git cloning and ensuring proper authentication headers are present during the request.

Our network