Git

Entire Git repos that represent a package can be installed via the Git endpoint. This can be a public Git server like GitHub or Bitbucket, or a private Git repo behind your firewall.

Make sure the root of your Git repo has a box.json inside of it so CommandBox can tell the version and name of the package. If there is no box.json, the name of the repo will be used as the package name.

Installation

To install a package from a Git repo, use the URL like so:

install git://github.com/username/repoName.git
install git+https://github.com/username/repoName.git
install git+ssh://[e-mail]:username/repoName.git

You can target a specific branch, tag, or commit by adding a "commit-ish" to the end of the URL.

install git://site.com/user/repo.git#development
install git://site.com/user/repo.git#v1.2.3
install git://site.com/user/repo.git#09d302b4fffa0b988d1edd8ea747dc0c0f2883ea

If you don't specify a commit-ish, the Girt endpoint will assume you want the master branch. If there is no master branch, we will attempt to checkout the main branch.

GitHub shortcut

If the repo you wish to install is located on Github.com, you can use this shortcut to specifying the package.

install username/repoName

In box.json

You can specify packages from folder endpoints as dependencies in your box.json in this format. Remember, JSON requires that backslashes be escaped.

{
    "dependencies" : {
        "myPackage" : "git://github.com/username/repoName.git"
    }
}

Authentication

Git repos that allow anonymous pulls do not require any additional configuration for authentication. CommandBox's Git endpoint supports SSH authentication via public/private keys by using the git+ssh:// protocol.

install git+ssh://site.com:user/repo.git#v1.2.3

Some Git endpoints (like private Github repos) need a user before the site name in the url string like below:

install git+ssh://[e-mail]:user/repo.git

Info Note the git+ssh URL is a little different than a HTTP(S) URL. There is a colon (:) after the host instead of a forward slash (/).

The git+ssh endpoint will look for a private SSH key in your ~/.ssh directory named id_rsa, id_dsa, or identity. If you are using a multi-key setup with a ~/.ssh/config file, it will be read, and the appropriate key will be used for the host. The matching public key needs to be registered in the Git server.

Info If you are deploying to a server and you have not previously logged into the Git server from the new machine you will need to make sure the Git server is added to your known_hosts file. The quickest way to do this is to use git clone [e-mail]/user/repo.git from the terminal OR add the line from your local machine to the server.

Note:

If you receive an invalid private key exception (Error cloning git+ssh repository and com.jcraft.jsch.JSchException: Auth fail), check your version of SSH. OpenSSH (7.8 and newer) generates keys in the new OpenSSH format, which starts with -----BEGIN OPENSSH PRIVATE KEY-----. JGit does not support this key format. Generate your key in the classic format using the following:

ssh-keygen -t rsa -m PEM

Password authentication

You can authenticate to a Git repo over HTTP using a username/password combination or a personal access token. The format looks like this:

install git+https://[e-mail]/user/repo.git
or
install git+https://username:[e-mail]/user/repo.git

Github

Github personal access tokens can be specified as either

install git+https://username:[e-mail]/user/repo.git

or just the personal access token like

install git+https://[e-mail]/user/repo.git

and they both appear to work the same. It appears that a private Github repo requires the “repo” scope selected for the personal access token.

GitLab

GitLab seems to want a username, but it doesn’t seem to matter what the username is.

install git+https://whateverYouWantHere:[e-mail]/group/repo.git

Env Vars

You can use environment variables from the CLI or in your box.json to protect sensitive information like passwords and keys.

set token=myToken
install git+https://user:${token}@gitlab.com/group/repo.git

NetRC

We also support the NetRC file format. Just create a files in your user's home directory called ~/.netrc or ~/_netrc with the following format:

machine github.com
login myUser
password mypass

CommandBox will find this file, match the hostname to the Git repo being cloned, and use the username and password as specified.

Note:

We do not support any of these username/password options over HTTP as it just seems unwise. Please use HTTPS.

Known Behaviors

Some users of Circle-CI have reported the following error when trying to clone a Git repo over HTTPS.

Error cloning github repositoryorg.eclipse.jgit.api.errors.TransportException: ssh://[e-mail]/ColdBox/coldbox-platform.git: Auth fail 
org.eclipse.jgit.errors.TransportException: ssh://[e-mail]/ColdBox/coldbox-platform.git: Auth fail 
com.jcraft.jsch.JSchException: Auth fail 

It is changing the https github url to ssh in the call. You can remove the config setting like so:

git config --global --unset "url.ssh://[e-mail]"