Accessing private repositories

There are 2 methods to access private git repositories. You can either use the SSH or HTTPS protocol to authenticate to the repository. Both ways are explained in the following sections.

Using SSH to access your repository

Using SSH to access a private git repository is our recommended approach. If you already have a ready SSH key pair to use, you can skip this section.

To create a new SSH key pair you can use the ssh-keygen command. For example, on Mac OS or Linux based systems the following instruction creates a new key pair:

ssh-keygen -t ed25519 -f ~/deploio.key -N ''

This will create a private SSH key in ed25519 format and place its content into the file ~/deploio.key. The corresponding public part will be written to ~/deploio.key.pub. The private key will not be password protected, which is important as otherwise Deploio couldn't read the content of it.

In a future release, nctl will automatically create the SSH key pair for you and output the public part ready for registering at your git provider (see below).

Registering the public key

The public part of the just created key pair needs to be registered at your git provider so that Deploio can read the content of the repository. You will need to create a so called "deploy key" to accomplish this. You can find documentation links for various git providers in the table below.

Provider	Documentation
GitHub	managing deploy keys
Bitbucket	ssh keys for system use
GitLab	deploy keys

In the corresponding dialog for creating a new deploy key you can use any 'Title' or 'Name' when being asked for. Use something which indicates the client using this deploy key (e.g. "deploio"). You will then need to paste the content of the file which holds your public key (~/deploio.key.pub in aboves example) into the "Key" field.

You don't need to grant write access for the deploy key as Deploio will just need to have read access.

Configuring the Deploio application

Once the key is registered, we can use nctl to create the Deploio application. Here we are using GitHub as an example provider for your git repository, but you can replace the git@github.com part with the URL identifiying your provider (e.g. git@gitlab.com).

nctl create app <app name> \
   --git-ssh-private-key-from-file=~/deploio.key \
   --git-url=git@github.com:<path-to-your-repository>.git

You can also pass the content of the private key in a env variable called $GIT_SSH_PRIVATE_KEY or reference the file which contains the private key by using $GIT_SSH_PRIVATE_KEY_FROM_FILE.

If the application already exists, you can use nctl update app to set SSH authentification.

Using HTTPS to access your repository

You can also use a username/password combination to let Deploio access your git repository via HTTPS. For this, it is best to create a repository scoped deploy token which can only be used to access a specific repo. We do not recommend to use a personalized deploy/access token as it will be directly associated with your user account and might have too broad permissions which are not needed by Deploio in the end. Please also do not set an expiration date on the deploy token. Currently, not all git providers have support for repository scoped deploy tokens. This is one of the reasons why we recommend to use deploy keys as they are generally better supported.

Here are a few documentation links to set up repository scoped deploy tokens at various git providers:

Provider	Documentation	Notes
Bitbucket	Repository Access Tokens	Use x-auth-token as the username
GitLab	deploy tokens

Configuring the Deploio application

Once you created a repository scoped deploy token, you can use nctl to create an application:

nctl create app <app name> \
   --git-username=<token username> \
   --git-password=<token password> \
   https://<path-to-your-repository>.git

You can also pass the username and password by using the environment variables $GIT_USERNAME and $GIT_PASSWORD.

If the application already exists, you can use nctl update app to set HTTPS authentification.