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.

Connect your Rasa X Server to a Git Repository

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

  • A Rasa X instance running in server mode (local mode does not support Integrated Version Control)

  • A Git repository containing a project in the default Rasa Open Source project layout

Note

When you connect your remote Git repository to Rasa X it will overwrite the training data, which is currently stored in Rasa X. Please use a fresh Rasa X instance or export your training data if you want to keep the old training data.

Project Layout

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

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

If you have just installed Rasa Open Source 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 Git repository and reorganize the project if it does not match the above layout.

Connect a Git Repository

  1. To connect your Git repository click on the branch icon and click Connect to a repository.

Rasa X when no Git repository is currently connected
  1. Configure the repository connection:

    • SSH URL: Rasa X will clone the repository using the given SSH URL. Cloning via HTTP is currently not supported.

    • target branch: 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

    • By default users can choose if they want to push their changes directly to the target branch or to a new branch. If want to disable pushing changes directly to the target branch, select Require users to add changes to a new branch.

Rasa X when no Git repository is currently connected
  1. Add the provided public SSH key to your Git server. This allows Rasa X to authenticate with the Git server using its private SSH key. Please see the documentation of your Git server how to do so. We have linked the instructions for some common providers in Add the Public SSH Key to Your Git Server

    Note

    If you prefer to provide your own keys, please see Connecting a Repository via the API.

  2. Once you added the public SSH key to your Git server, hit the Verify Connection button. Rasa X will now show that it is connected to your repository.

    Rasa X server with a connected Git repository
  3. What to do next: Check out Using Integrated Version Control to understand how to use Integrated Version Control as part of your process for improving your assistant.

Add the Public 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.

Connecting a Repository via the API

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

  1. 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.

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

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

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.