Integrated Version Control

Note

This is currently an experimental feature 🛠. To activate it, click on your user icon at the bottom of the side bar and select Experimental. Then select Integrated Version Control.

We would love to hear your feedback and suggestions in this thread on the Rasa forum.

The most successful product teams using Rasa follow many of the software engineering best practices routinely found in web and mobile app development. These workflows include:

  • 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

Running Rasa X locally? Any changes you make in Rasa X will be reflected in your file system. Since you have access to the cloned repository on your computer, you can commit and push your changes using your usual Git workflow. This also means you are responsible for pulling the latest changes from the Git server 💪🏽.

In case you are using Rasa X locally and want to deploy to a server, check out the docs on deploying to a server and Kubernetes / OpenShift guides.

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

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 to authenticate with your remote Git repository. 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.

GitHub

Add your the generated public SSH key as a Deploy key to your GitHub repository. Please see the GitHub docs on how to do so.

GitLab

Add your the generated public SSH key as a Deploy key to your GitLab repository. Please see the GitLab docs on how to do so.

Bitbucket

Add your the generated public SSH key as an Access key to your Bitbucket repository. Please see the Bitbucket docs 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. To authenticate with the Rasa X server you can use one of two methods:

    • Use your JWT access token. You can get it from the authentication endpoint and pass it within the Authorization header.
    • Use your API token. Get it by going to the model screen in Rasa X and using the api_token token from the Upload Model command. Similar to the upload command, you add it with the api_token query parameter.
  2. Save your repository credentials to a file repository.json. If your Rasa X server does not use HTTPS, we highly recommend doing this directly on your server to avoid compromising the key.

    {
        "repository_url": "<your repository's SSH clone url, e.g. git@github.com:RasaHQ/rasa-demo.git>",
        "ssh_key": "<your generated private SSH key>",
        "target_branch": "<the default branch Rasa X will use, e.g. master>"
    }
    

    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
  3. Create the repository by executing the following HTTP request:

    • JWT 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
      
    • 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
      

Using Rasa X Server with Git

Integrating your Rasa X server with Git enables you and your team to apply best practices from software engineering to the development of AI assistants.

After you have connected your assistant’s repository to your Rasa X server, Rasa X will automatically pull data from your remote repository and reflect those updates in Rasa X. At this initial stage, Rasa X will have the latest data from your remote repository on the Git server. Rasa X will indicate that you are up to date with the latest changes with a green state in the side bar.

Rasa X server in a clean Git state

When you make a change to your assistant in Rasa X, the side bar state will transition to an orange state. This means that you have changes that can be pushed to the remote repository when you are ready. During this time, Rasa X won’t fetch new changes from the remote repository to avoid overwriting your changes.

Rasa X server with changes which can be committed and pushed.

When you are finished making changes and ready to add them to your Git server you can commit and push them by clicking on the Git icon in the sidebar. If your remote branch has not changed while you were annotating, you can choose between

  • pushing changes directly to the remote branch
  • pushing them to a new branch

If new changes were added to the remote branch while you were annotating, you will only be able to push your changes to a new branch to avoid potential merge conflicts. Rasa X will notify you that there has been changes to the remote branch with a red state on the side bar.

Rasa X server with changes while remote is ahead.

When you are ready, click on the side bar icon and follow its instructions. Once your changes are pushed, Rasa X will return to be in sync with your remote branch and will pull in the latest changes from your remote as they become available.

Note

If you pushed your changes to a new branch, these changes won’t be reflected in Rasa X until you have merged them into the target branch.

You can of course also discard your changes. Rasa X will then be reset to the latest state of your remote branch.

Leverage the Git Ecosystem

Integrating Rasa X with Git enables your team to use the full power the Git ecosystem:

  • Apply a review process for any changes to your model
  • Automatically evaluate dialogues end-to-end, running through test conversations and making sure that both NLU and Core make correct predictions, as part of a CI pipeline (check out End-to-End Evaluation in the Rasa docs for more information)
  • Automatically generate reports, a confusion matrix, and a confidence histogram on your new model as part of a CI pipeline (check out Evaluating Models in the Rasa docs for more information)
  • Minimize the time from change to production with continuous deployment