Connect xltrail with a Git repository
Add a repository via http with username and token/password
- Login to xltrail as admin user (this is the user you signed up with).
Go to
Settings
>Integrations
>Git
. Then click onAdd Repository
:If you are using a system like GitHub, GitLab, Bitbucket etc.: Paste the Git url of your repository as shown in the screenshot.
Make sure to paste the http(s) (and not the ssh) version of your git url. Also, if your Git provider (e.g. Bitbucket) starts the url with your username, make sure to remove it including the @.Enterprise only: If you are using a git remote directly on the file system, you need to:
- Mount the directory as subdirectory of the following directory on the xltrail server:
/var/lib/xltrail/integrations/git
. Make sure to replace/var/lib/xltrail
with the value of yourDATA_DIR
if you have changed that in your config file. - Specify
Repository URL
as follows:file:///xltrail/integrations/git/<my-repo>
, leaving user and password empty.
Please restart xltrail after mounting the directory by running `xltrail restart` as root.- Mount the directory as subdirectory of the following directory on the xltrail server:
Set the username and password/token to access your repository. Note, you should generate a read-only token to use as password. Follow the instructions below for the most popular Git providers.
Git Tokens
Github Cloud & Enterprise
Under Personal settings
> Developer settings
> Personal access tokens
, you can Generate new token
. Tick the
repo
checkbox so you get access to all the subitems in that box.
GitLab Cloud & CE/EE
You can either use a token that is bound to a specific repository or to your user:
Repository Deploy Token
- This requires at least GitLab 10.7
- The token will give you read-only access to a single repository.
- In your repository, go to
Settings
>Repository
, thenDeploy Tokens
(notDeploy Keys
!). Give it aName
, checkread_repository
underScopes
and click onCreate deploy token
. It will give you both an automatically generatedusername
andtoken
that you'll need to use with xltrail.
Personal Access Token
- You will be able to access every repository that you have access to with a personal access token:
- Create a personal access token under
User Settings
>Access Tokens
. Tick theread_repository
checkbox underScopes
. Use your GitLab username with that token as password in xltrail. If you are on an older version of GitLab, you might not haveread_repository
available. In that case use theapi
checkbox.
Bitbucket Cloud
Personal Accounts: You can create an app password under
Bitbucket Settings
>Access Management
>App password
. Tick the checkboxesRepository (read)
andPull Requests (read)
.Team Accounts: You can create an API key to use with your team name under
Bitbucket Settings
>Access Management
>API key
.
Bitbucket Server
Bitbucket Server (the on-premise version of Bitbucket) introduced personal access tokens with version 5.5, see Bitbucket Cloud above for the details.
On lower versions, you can either use an existing user or create a dedicated xltrail user:
- Log in as Bitbucket administrator
- Under "Administration" click on
Users
, thenCreate user
- Pick something like
xltrail
as the username
To finalize, you need to give this user read access either on Project or Repository level.
Add a repository via ssh with deploy keys
Step 1: Create your SSH keys
It's easiest to create the ssh keys on the Linux server where you have xltrail installed as Linux comes with
OpenSSH preinstalled. Run the following command (you can replace xltrail deploy key
with anything that
helps you remember the purpose of this key:
ssh-keygen -C "xltrail deploy key"
This will first prompt you for the location of the key. It's usually ok to go with the default by hitting Enter
.
In case there is already a file exisiting at this location, you will be warned.
Next, it will ask for a passphrase. Leave this empty (important!) and hit the Enter
key. Finally, it will ask to
Enter the same passphrase again
- hit Enter
again without filling in anything.
Next, you fill find two files (id_rsa
and id_rsa.pub
) in the directory that was indicated in the first step,
usually under ~/.ssh
.
Step 2: Add the public key to your Git provider
Different providers offer different options to add a deploy key. Some providers only allow a key to be used with a user while other providers allow to add a proper "deploy key" to specific repositories or groups of repositories.
Azure DevOps
Click on the user icon on the top right, then select Security
. On the left side bar, click on SSH public keys
towards the bottom. Click on + New Key
on the top right and copy paste the content of rsa_id.pub
into
Public Key Data
. Give it a Name
like "xltrail deploy key". Make sure that the user you are doing this for has
access to the repositories that you want to sync with xltrail.
Step 3: Add the private key to xltrail
Add a new Project with type Git
. For Repository URL
, make sure to paste the ssh version of the URL (not the http version).
Leave User
empty. For Token or Password
, paste the content of id_rsa
(make sure to not have any spaces before and after your key):
Then, click on Create Git Integration
.