Conversational Agents (Dialogflow CX) integrates with GitHub. This integration makes it easy to export your agent to JSON for a push to GitHub, and to pull from GitHub for an agent restore. The JSON exported format pushed to GitHub is the expanded zip file contents of the exported agent.
Using this feature allows you to take advantage of GitHub source control features like:
- Agent change reviews using code review tools
- Examine agent diffs using diff tools
- Merges
- And so on
Limitations
The following limitations apply:
- GitHub has a rate limit for the number of requests per hour (5000 for non-enterprise accounts, 15,000 for enterprise accounts). If your agent push exceeds this limit, the Dialogflow CX console will report the rate limit error. You can retry the push after an hour.
- GitHub APIs have a limitation on the number of files that can be updated in a single commit. If the number of files exceeds 500, you may not be able to push to GitHub from Conversational Agents (Dialogflow CX). In such cases, you can export
the agent as a zip and use the Git CLI on your machine to push the agent files to GitHub. This limitation will be addressed in a later Conversational Agents (Dialogflow CX) release. - Private access self-hosted repos are not supported, because Conversational Agents (Dialogflow CX) cannot access these repos.
- The GitHub repository cannot contain any files other than the agent files exported by agent export. Any other files in the repository will be removed on every push.
Configuration
To configure this integration:
- Open the Dialogflow CX console.
- Choose your Google Cloud project.
- Select your agent.
- Click the Manage tab.
- Click Git in the Testing & Deployment section.
- Click Add Git integration, and a configuration dialog opens.
- Enter the following:
- Display name for the GitHub connection.
- GitHub repository URL (for example:
https://api.github.com/repos/<repository_owner>/<repository_name>). - Add GitHub branches your agent will be interacting with. You can designate a branch as the default branch by clicking the star icon next to it.
- GitHub personal token cannot be viewed once set, only updates are supported.
If you use a fine-grained personal access token,
you need the following
permissions
access:
- Repository Permissions > Contents: Read and write
- Repository Permissions > Metadata: Read-only (should be auto-selected after selecting Contents permission)
- Click Connect.
This configuration can be changed at any time by clicking on the edit icon.
Push and restore
Once configured, you can push/pull your agent to/from GitHub.
The Push button is used to export your agent and make a commit to the GitHub branch selected in the Git branch dropdown. This commit will consist of the entire agent and not specific changes, and will delete any existing files in the repository.
For new repositories, make sure that there is at least one commit from GitHub before using the push option in the Dialogflow CX console.
Users with Dialogflow Reader roles have the ability to push to GitHub repositories. To prevent unwanted pushes, configure these agents with read-only personal access tokens.
The Restore button is used to pull your agent data from the GitHub branch selected in the Git branch drop-down and restore your Conversational Agents (Dialogflow CX) agent from this data. This will overwrite your agent in the same way that any agent restore behaves.
Example use case
The following example illustrates how this feature can be used by multiple people to propose different agent changes to a production agent.
Consider that your agent uses the following GitHub branches:
- Prod: branch for your production agent
- Dev1: branch for agent development
- Dev2: another branch for agent development
User 1 wants to propose agent changes and takes the following steps:
- Export the production agent to a new agent.
- Make the desired changes to this agent copy.
- Test the changes.
- Push the altered agent to the Dev1 branch.
- Create a merge request to the Prod branch.
User 2 wants to propose agent changes and takes the following steps:
- Export the production agent to a new agent.
- Make the desired changes to this agent copy.
- Test the changes.
- Push the altered agent to the Dev2 branch.
- Create a merge request to the Prod branch.
User 3 reviews merge requests from both users and takes the following steps:
- Resolve conflicts.
- Commits approved changes.
- Restores the production GitHub branch to the production Conversational Agents (Dialogflow CX) agent.