Skip to main content

Protect agents with Source Control

Learn how to make changes to agents protected with Source Control.

Source Control Availability
Cloud Generally Available
Self-hosted Edge 3.33 or laterGenerally Available
Self-hosted Stable 3.33 or laterGenerally Available

Source Control for agents operates similarly to how it does for apps, but with some key differences.

  • Agents cannot be moved or renamed. Protected agents and the folders in which they're located cannot be renamed or moved. You must unprotect agents before making name or location changes. Protected agents must have a unique name.
  • Agent triggers cannot be protected. You can edit the trigger of a protected agent without creating a commit.
  • Evals and Datasets are incompatible. You cannot access evals and datasets from a protected agent.

This guide outlines how to make changes to a protected Retool agent and merge these changes into the main branch.

Requirements​

Before you begin, ensure Source Control is configured for your Retool instance. This guide uses GitHub, but Retool supports multiple remote SCM providers.

Source Control is available on the Enterprise plan. You must be an admin to configure Source Control.

1. Protect the agent​

In Retool, protected agents are checked into remote source control repositories. You can protect an agent with Source Control from the dropdown next to the agent name, or from the dropdown on the All agents page.

After reviewing the confirmation modal, click Protect agent and create a pull request. Once merged, your agent is protected.

Your agent shows a badge to the right of the name indicating that it is protected. The protected badge will also show next to the agent name on the All agents page.

An agent's name serves as a unique identifier when you use Source Control, so you can't rename a protected agent. To change the name of a protected agent, you must unprotect the agent, rename it, and re-protect it.

2. Create a branch and commit your changes​

You can still chat with and view the logs of a protected agent, but to edit an agent's configuration, you'll need to create a new branch.

  1. Click Edit.
  2. Select Create new branch.
  3. Give the branch a descriptive name for your changes. You can also select Allow collaborators to allow other users to push changes to your branch.
  4. Click Create. The branch on which you're editing appears in the top right, along with the commit log for the branch. Changes made on branches are local to the branch.
  5. Make any necessary changes to your agent.
  6. Click the Commit button in the top right corner.
  7. Add a commit message to describe the changes you made to the agent.
  8. Optionally, select Review changes to preview the changes in your commit.
  9. Push your changes to GitHub by clicking Commit to <your-branch-name>.

3. Open a pull request and merge​

After you commit all the changes you want to make, incorporate your changes back into the main branch.

  1. Click branch name in the top right corner, and select Create pull request.
  2. Notice that the description is already populated with a link to preview your changes on your branch. Make any necessary changes, and create the pull request.
  3. Merge the changes into the main branch of your repository. The merge button label may differ depending on your repository's configuration for merging (e.g., Rebase and merge or Squash and merge). Confirm the merge if required by your organization.
  4. After a few seconds, your changes are merged into the main branch of the agent.

4. Remove agent protection​

You can remove protection for an agent at any time from the main branch.

  1. Ensure you are on the main branch.
  2. Click the dropdown next to the agent name to open the contextual menu.
  3. Select Remove protection and confirm that you want to remove protection again.
  4. Click Open a pull request in GitHub.
  5. Create and merge the pull request into main to unprotect your agent.