Version: 0.32.x

Integrated Version Control: Connecting a Repository via the API

If you want to use self-generated SSH keys or prefer to use the Rasa X API for any other reason, you can also use the Rasa X HTTP API to connect Rasa X to your Git repository.

caution

When connecting the Rasa X instance to a git repository, any training data or configuration files stored in Rasa X will be overwritten by those in the Git repository. If you were using Rasa X to manage your assistant before setting up Integrated Version Control, be sure to download the data before continuing, so that the data is not lost. You can push the downloaded data from your machine to your Git repo before or after connecting it to Rasa X.

Using SSH to Authenticate

  1. To authenticate your Rasa X server with the remote repository via SSH, you need to set up an SSH key that Rasa X can use for authentication. Please create a new, single-use SSH key for this (see instructions below). Also, make sure to restrict the SSH keys to only apply to your assistant’s repository.

    To generate a new SSH key pair follow these steps:

    1. Open the Terminal

    2. Execute the following command (make sure to not overwrite your own SSH keys):

    ssh-keygen -t rsa -b 4096 -f git-deploy-key

    This provides you a private (git-deploy-key) and a public (git-deploy-key.pub) key in your current directory.

    note

    Please note that Rasa X currently does not support password protected private keys.

  2. Save your repository information and private key to a file repository.json, in the format shown below. If your Rasa X server does not use HTTPS, we highly recommend doing this directly on your server to avoid compromising the key. As the contents of this file will uploaded via a curl request, the directory where it is stored does not matter, but it is recommended to store the file somewhere secure.

    {
    "repository_url": "<your repository's SSH clone url>",
    "target_branch": "<the default branch Rasa X will use>",
    "ssh_key": "<your generated private SSH key>",
    "is_target_branch_protected": false
    }
    note

    The target branch is the branch that Rasa X will

    • use to show the initial data

    • branch off from when you make new changes

    • return to after you discard or push changes

    If you want to disable adding changes directly to the target branch, please specify is_target_branch_protected": true/false in the repository.json file.

    For example, your repository.json might look like:

    {
    "repository_url": "git@github.com:RasaHQ/rasa-demo.git",
    "target_branch": "master",
    "ssh_key": "-----BEGIN OPENSSH PRIVATE KEY-----
    b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAACFwAAAAdzc2gtcn
    NhAAAAAwEAAQAAAgEAu/Giin7t8DFMxsaTbyy1To2EQpLIAhpAIgpyC/e45NYVTwKRGCB1
    mxHzt5IWoh7GSWry3pKFBM74UpXxrRPBdCmFeUIiJoslAukNkRSckAUj0VEfOIZLf2SSPg
    ...
    CDHniFksE1SjkAAAEBANJacZeM2Qdk/vditmBQV97Ac2VJL/Btt8Rks2Vb3CORyXQn3Bpb
    +5ZONhmPEoCg4FcZbAm02gYw3dSoBBWz2i8mmAv71mVsNoddWKpDngRFv4PUaITnYYxrZ4
    -----END OPENSSH PRIVATE KEY-----"
    }
  3. To authenticate with the Rasa X server you can use one of two methods:

    • API token authentication: Get your API token by going to the Models screen in Rasa X and clicking the Upload Model button in the upper right-hand corner. Copy the api_token token from the upload command. Similar to in this command, you will add it to the curl command shown below with the api_token query parameter.

    • JWT token authentication: Use your JWT access token. You can get it from the authentication endpoint and pass it within the Authorization header.

    Once you have prepared your chosen form of authentication, create the repository by executing the following HTTP request from the directory that contains your repository.json:

    # with API token authentication
    curl --request POST \
    --url http://<Rasa X server host>/api/projects/default/git_repositories?api_token=<your api token> \
    --header 'Content-Type: application/json' \
    --data-binary @repository.json
    # with JWT token authentication
    curl --request POST \
    --url http://<Rasa X server host>/api/projects/default/git_repositories \
    --header 'Authorization: Bearer <your access token>' \
    --header 'Content-Type: application/json' \
    --data-binary @repository.json
    note

    If your Rasa X server runs on HTTPS, make sure to use https:// in the --url parameter.

Using HTTPS to Authenticate

note

Connecting to remote repositories via HTTPS is only possible with Rasa Enterprise.

  1. To authenticate your Rasa X server with the remote repository via HTTPS, you need the necessary credentials to access the repository: username and password. If your account has 2FA (Two-Factor Authentication) enabled, you will need to create a personal access token that allows you to access the repository, and use that as a password.

  2. Use the Rasa X API to create the repository, using either API token authentication or JWT token authentication:

    # with API token authentication
    curl --request POST \
    --url http://<Rasa X server host>/api/projects/default/git_repositories?api_token=<your api token> \
    --header 'Content-Type: application/json' \
    --data-raw '{
    "repository_url": "<your repository HTTPS clone URL>",
    "target_branch": "<the default branch Rasa X will use>",
    "is_target_branch_protected": false,
    "username": "<your username>",
    "password": "<your password or personal access token>"
    }'
    # with JWT token authentication
    curl --request POST \
    --url http://<Rasa X server host>/api/projects/default/git_repositories \
    --header 'Authorization: Bearer <your access token>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
    "repository_url": "<your repository HTTPS clone URL>",
    "target_branch": "<the default branch Rasa X will use>",
    "is_target_branch_protected": false,
    "username": "<your username>",
    "password": "<your password or personal access token>"
    }'