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.

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):

   Copy

   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.

   Copy

   {

   "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:

   Copy

   {

   "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:

   Copy

   # 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
   Copy

   # 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#

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:

   Copy

   # 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>"

   }'
   Copy

   # 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>"

   }'