Integrated Version Control

The most successful product teams using Rasa apply software engineering best practices to developing their assistants, including:

  • Versioning training data and action code in Git
  • Reviewing changes before they go into production
  • Running automated tests on proposed changes

Rasa X encourages best practices by integrating itself into your existing development workflows, letting you:

  • Automate data synchronization with your Git repository
  • Automatically stay up to date with the latest state of the remote repository on your Git server
  • Annotate new data and push those changes to Git

Set yourself up for success by connecting your Rasa X server with Git to monitor, version, and test your training data using GitHub, GitLab, Bitbucket, Travis CI, CircleCI, Jenkins, etc.

Note

This is currently an experimental feature 🛠. We would love to hear your feedback and suggestions in this thread on the Rasa forum.

Connect your Rasa X Server to a Git Repository

In order to connect Rasa X with your assistant’s Git repository, you will need two things:

  • A Git repository containing a project in the default Rasa project layout
  • SSH keys to authenticate Rasa X with your Git repository

Project Layout

For Rasa X to correctly visualize and modify your AI assistant’s data, your project needs to follow the default Rasa project layout created by rasa init:

.
├── config.yml
├── ...
├── data
│   ├── nlu.md
│   ├── ...
│   └── stories.md
└── domain.yml

If you have just installed Rasa for the first time, you can run rasa init in a new Git repository to achieve this structure. If you have an existing assistant that you’re connecting to Rasa X, make sure to add it to a Gir repository and reorganize the project if it does not match the above layout.

Generate New SSH Keys

To authenticate your Rasa X server with the remote repository, 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.

Add Your SSH Key to Your Git Server

You have to add the public key of the generated key pair to your Git server. Please make sure to only give the key access to one specific repository instead of giving it global access to all of your Git repositories. For instructions specific to your Git platform, see below.

GitHub

Add the generated public SSH key as a Deploy key to your GitHub repository. See the GitHub docs for more information on how to do so.

GitLab

Add the generated public SSH key as a Deploy key to your GitLab repository. See the GitLab docs for more information on how to do so.

Bitbucket

Add the generated public SSH key as an Access key to your Bitbucket repository. See the Bitbucket docs for more information on how to do so.

Add Your Repository to Rasa X

To connect your Rasa X server to your repository, you must use the Rasa X API.

  1. Activate the Integrated Version Control feature. To do so, click on your user icon at the bottom of the side bar and select Experimental. Then select Integrated Version Control. Note that activating the feature will activate it for all users.

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

    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

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

    Warning

    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.

  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 model screen in Rasa X and copying the api_token token from the Upload Model command. Similar to the upload command, you add it with the api_token query parameter shown in the curl command below.
    • 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 https://<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 https://<Rasa X server host>/api/projects/default/git_repositories \
         --header 'Authorization: Bearer <your access token>' \
         --header 'content-type: application/json' \
         --data-binary @repository.json
    

Once you’re set up with Git and your assistant is automatically imported, you can Enable Workflows to begin learning from real users. For more information about how data synchronization works, see Using Integrated Version Control.