Configure a source control repository for your playbooks

You can save your playbooks in Git repositories. By default, playbooks are managed in a Git repository called local. You can create additional Git repositories as needed, so you can perform the following tasks:

Import and export playbooks and share facilities among instances. For example, you can use Git to publish playbooks from a development environment to a separate production environment.
Edit playbooks using a tool of your choice instead of the web interface.

If you edit a playbook outside of the Visual Playbook Editor (VPE), you can no longer use drag and drop blocks in the VPE to edit that playbook. After that, you can only perform subsequent edits in the VPE by editing the full playbook. This is not recommended.

also uses a Git repository to publish company-authored playbooks for you to download. This repository is called the community repository and is configured on by default. You can restore this repository if you accidentally remove it. See Restore the community playbook repository.

You can transfer playbooks to Git using HTTP, HTTPS, or Git. Other protocols can be authenticated or anonymous if supported by the server.

Access the source control settings in

To access the source control settings, perform the following steps:

From the Home menu, select Administration.
Select Administration Settings, then Source Control.

You can also access the source control settings from any Playbooks page by selecting Manage source control.

Set up a playbook repository using HTTP, HTTPS, or Git

To set up a Git repository using HTTP, HTTPS, or Git protocols, perform the following steps:

From the Home menu, select Administration.
Select Administration Settings, then Source Control.
Select Configure a new repository from the Repositories drop-down list.
Provide a repository URL, repository name, and branch name. The repository name can be any name that describes your repository. If you are using a subdirectory, its path must already exist. This configuration panel does not create new subdirectories.
For details on creating a new subdirectory, see the next section, Move playbooks to a different or new subdirectory.
Provide the path to the playbooks directory within the repository. The path must end with a slash (/). To store playbooks at the root level, leave this field blank.
For HTTP and HTTPS, specify a username and password. attempts to connect anonymously if no username or password is provided. When crafting the URI, converts https://server... to https://username:password@server.... The Git protocol is not authenticated and does not require a username or password.
Select Save Changes.

Note the following important points:

You cannot edit a repository after it is added to . If you need to make a change, for example, if you change the subdirectory where the playbooks are stored, you must create a new source control repository in using the process described above. Delete unused repositories, as described later in this article.
The repository must contain at least one commit in order to be added to .

The username and password strings are separated so that the password can be encrypted and stored and not displayed to other administrators. However, passwords are stored as clear text in the Git configuration file for that repository.

Move playbooks to a different or new subdirectory

You might choose to move your organization's playbooks to their own subdirectory, separating them from other files in a repository. This involves updating the Git repository, using any Git client. The steps below are similar to the process described in the GitHub documentation for moving a file to a new location.

If you use multiple branches of the repository, repeat these steps for each branch.

To update the Git repository for your playbook storage path, follow these steps:

Create the new directory where you want to store playbooks, if it does not already exist in the Git repository. For example mkdir playbooks.
Move all existing playbook files to the directory where you want to store them. For example, mv *.py playbooks/ followed by mv *.json playbooks/.
Run git add --all.
Run git commit -m "Moving playbooks to new folder".
Run git push origin <branch-name>.
Return to the Administration page.
Complete the steps described in the previous section to configure a new source control repository, using the new path to the playbooks.
Delete the original, now unused, source control repository, as described in the next section of this article, Delete a source control repository in .

Delete a source control repository in

Delete unused source control repositories to avoid confusion and clutter.

To delete a source control repository in , follow these steps:

From the Home menu, select Administration.
Select Administration Settings, then Source Control.
In the Repositories list, select the repository you want to delete.
Select Delete.

Git hooks and the Splunk SOAR Playbook Editor

does not directly support Git hooks. If you choose to use Git hooks in your system, be aware of the following:

There is a risk that the playbook editor will not be able to save or push changes because the Git configuration rejects a commit.
To avoid this issue, direct to push to a staging repository or branch that will not reject pushes. This prevents the playbook editor from being blocked from saving and pushing changes. Handle merge conflicts or other issues manually when pushing from the staging repository to the original repository.

If your playbook editor is blocked from pushing to the remote repository, follow these steps:

Delete the repository in Git and recreate it in , using the steps described in the Set up a playbook repository using HTTP, HTTPS, or Git section of this article. The playbook reverts to the last successful push and removes all changes made after the last successful push.
Recreate your changes and try to push again.

Use repositories from the Playbooks page

You can make use of configured repositories on the Playbooks page. See View the list of configured playbooks for more information.

Restore the community playbook repository

The community playbook repository is a collection of playbooks vetted by the community. This repository is configured by default when is installed. Follow the procedure to restore the community repository if it is accidentally altered or deleted.

From the Home menu, select Administration.
Select Source Control.
In the Repositories drop-down list, select Configure a new repository.
In the Repo URL field, enter the URL: https://github.com/phantomcyber/playbooks.git
In the Repo Name field, enter community.
In the Branch Name field, enter the version of you are running, up to the second set of digits. For example, if you are running version 6.1.1 enter 6.1 in this field.
Select the Read Only check box.
Select Save Changes.