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. Doing so enables you to 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.

Once 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. Any subsequent edits in the VPE are only possible by editing the full playbook. This is not recommended.

also uses a Git repository to publish company-authored playbooks for customers 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 > Source Control.

You can also access the source control settings from any Playbooks page by clicking 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 > 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.
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.
Click Save Changes.

The repository needs to have at least one commit in it in order to be added to . Additionally, a repository that is added to can't be edited. If you need to make a change, delete the repository and then add it again.

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.

Git hooks and the 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 Git remote rejects your commits, causing the push to fail, you have two options:

Delete and recreate

Delete the repository and recreate it in Splunk SOAR (On-premises). 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.

Remediate the issue from the command line. Continue reading the next section.

To remediate the issue from the command line, follow the set of the instructions that matches your scenario.

You must have some expertise with Git or refer to Git documentation to perform some of the steps described in this section.

Problem commit is your most recent commit
If your most recent local commit is causing the problem, and you have not made subsequent commits, choose one of the following options:
Option 1:

Delete the most recent commit by running git reset --hard HEAD~1.
Recreate your changes and try to push again.

Option 2:

Make the necessary changes in your repository so it will pass the hook.
Replace your previous commit with this current state of the repository by running git commit --amend
Try to push again.

Problem commit is not your most recent commit
Choose the option that best matches your scenario:
Option 1:
If your playbook editor is blocked from pushing to the remote repository, follow these steps:

Delete the repository and recreate it in . 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.

Option 2:
Otherwise, perform an interactive rebase in Git by following these steps:

Start the interactive rebase by running git rebase -i <identifier>~1

The identifier refers to the working version of the branch, such as origin/master or the commit hash for the last working commit.
Append ~1 to start the rebase on the commit before the last working version.

Git displays a file that lists all of the commits in order. Choose an option:

To delete the problematic commit entirely, delete the line with the commit, while keeping the subsequent commits.
To amend the problematic commit, modify line for that commit, replacing pick <hash> with edit <hash>. After you write and close this file, git starts rebasing. Git pauses when it reaches that line. Then you can use git commit --amend to repair the commit.

After the rebase completes successfully, push to the repository. If performing the rebase caused the commit history to diverge, you must perform a force push.

Set up a playbook repository using SSH

To set up a playbook repository using SSH, perform the following steps:

From the main menu, select Administration.
Select Administration Settings > Source Control.
Select Configure a new repository from the Repositories drop-down list.
Provide a repository URL starting with ssh:// and including the username. For example: ssh://<username>@10.4.5.6/opt/repos
Add the SSH public key from to your Git server's authorized keys file.
1. Copy the contents in the SSH Public Key field.
2. Log in to your Git server as a user with permissions to edit the Git server's authorized_keys file.
3. Add the SSH public key to the authorized key file, such as ~/.ssh/authorized_keys.
Provide a repository name and branch name. The repository name can be any name that describes your repository.

If you get the following error when setting up an external repo with SSH Auth:
Cmd('git') failed due to: exit code(128) cmdline: git fetch -v origin stderr: 'fatal: Could not read from remote repository. Please make sure you have the correct access rights and the repository exists.'
This indicates that the /home/<phantom_user>/.ssh/known_hosts file is not being updated with the external repo and ssh key info.

You can manually correct this through the CLI by running the following command as the user:

ssh-keyscan -t rsa <external_repo> >> /home/<phantom_user>/.ssh/known_hosts

Establish trust with the git repository from your deployment

You must inform git that it can trust the remote hosts of your Splunk Phantom deployment before you can use the source repository.

On your instance, or in the case of a cluster, on each cluster node:

SSH to the instance or cluster node. Log in as the user account that runs .
```
ssh phantom@<phantom instance or cluster node>
```
Run the command to establish trust with the git repository.
```
git ls-remote git@<address of the git repository>
```
Verify that the information returned is correct. Example:
```
git ls-remote git@your-git-repository:phantom/phantom.git
```
If the returned values are correct, type yes.

Set up a playbook repository using HTTPS with a self-signed certificate

If your HTTPS server is using a self-signed certificate, you need to import your certificate authority (CA) file to the Splunk SOAR (On-premises) certificate store and then configure Git to use it. If you don't do this, trying to add a new playbook repository results in an error mentioning an untrusted certificate. To set up a playbook repository using HTTPS with a self-signed certificate, follow these steps:

Import the CA file to the certificate store. See Add, remove, or replace certificates from the Splunk SOAR (On-premises) certificate store.
Configure the environment variable. See Set global environment variables. Enter GIT_SSL_CAINFO as the variable name and the value as <phantom home>/etc/cacerts.pem.
Configure the repository. See Set up a playbook repository using HTTP, HTTPS, or Git on this page. Git is now able to connect.

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, type the URL: https://github.com/phantomcyber/playbooks.git
In the Repo Name field, type 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 4.10.3 enter 4.10 in this field.
Check the Read Only check box.
Click Save Changes.

Administer Splunk SOAR (On-premises)