Connecting a Git Repository

👤 This documentation is intended for Site Administrators.

With the Git Integration, users have a copy of their Periscope objects in one repo per Space. The periscope/master branch is the production branch that is in-sync with the Periscope Space.
Below are directions for connecting a Git repository using GitHub, GitLab, or BitBucket. For more information on the structure of the Git repository refer to the Git Configuration page.

Table of Contents:

<UL>
<LI><a href="#Connecting">Connecting Git</a></LI>
<LI><a href="#Github">GitHub</a></LI>
<LI><a href="#Gitlab">GitLab</a></LI>
<LI><a href="#Bitbucket">BitBucket</a></LI>
</UL>

<HR>

<a name="Connecting"></a>

Connecting Git

<OL>
<LI>Create an empty Git repository (without a README) hosted at GitHub, GitLab, BitBucket or on an owned Git server.</LI>
<UL>
<LI>If starting with a repository that is not empty and there is a desire to merge from <code>origin/master</code> to <code>periscope/master</code>, issue the following command to allow unrelated histories: <code>git merge --allow-unrelated-histories periscope/master.</code></LI>
<LI>Make sure that the repository is set to Private so that access can be controlled (this is a setting that can be changed in the repository).</LI>
</UL>
<LI>Navigate to the Version Control settings page in Periscope</LI>
<UL>
<LI style="list-style: none;"><figure class="w-richtext-figure-type-image w-richtext-align-center" data-rt-type="image" data-rt-align="center"><div><img src="https://uploads-ssl.webflow.com/58fe8f93dc9e750ca84ebb16/5b92af4725711df2824da43f_GitVersionControlSetting.png"></div></figure></LI>
</UL>
<LI>Get the SSH URL for the remote Git repository. Formats for common Git providers:</LI>
<UL>
<LI>To see screenshots of how to configure GitHub, please see the <a href="#Github">GitHub</a> section</LI>
<UL><LI>GitHub: git@github.com:&lt;organization-name&gt;/&lt;repository-name&gt;.git</LI>
<LI>GitHub Enterprise: git@example.com:&lt;organization-name&gt;/&lt;repository-name&gt;.git</LI>
</UL>
<LI>To see screenshots of how to configure GitLab, please see the <a href="#Gitlab">GitLab</a> section</LI>
<UL><LI>GitLab: git@gitlab.com:&lt;organization-name>/&lt;repository-name&gt;.git</LI></UL>
<LI>To see screenshots of how to configure BitBucket, please see the <a href="#Bitbucket">BitBucket</a> section.</LI>
<UL><LI>Bitbucket: git@bitbucket.org:&lt;organization-name&gt;/&lt;repository-name&gt;.git</LI></UL>
</UL>
<LI>Paste the SSH URL into the “SSH URL” field on the Version Control settings page:</LI>
<UL>
<LI style="list-style: none;"><figure class="w-richtext-figure-type-image w-richtext-align-center" data-rt-type="image" data-rt-align="center"><div><img src="https://uploads-ssl.webflow.com/58fe8f93dc9e750ca84ebb16/5b92b0ff25711d53654dac91_GitVersionSSH.png"></div></figure></div></LI>
</UL>
<LI>Copy the “Deploy Key” which Periscope provides on the Version Control settings page and paste it into the Settings for the repository:</LI>
<UL>
<LI>Be sure to select the <b><u>Allow write access</b></u> option because Periscope requires this setting in order to make and deploy changes. </LI>
<LI style="list-style: none;"><figure class="w-richtext-figure-type-image w-richtext-align-center" data-rt-type="image" data-rt-align="center"><div><img src="https://uploads-ssl.webflow.com/58fe8f93dc9e750ca84ebb16/5b92b0f836e87ed20ae800ea_GitVersionDeploy.png"></div></figure></LI>
</UL>
<LI>Navigate back to the Version Control settings page in Periscope, Copy the “Webhook URL” and “Webhook Secret Token” and paste them into the Settings for the repository:</LI>
<UL>
<LI style="list-style: none;"><figure class="w-richtext-figure-type-image w-richtext-align-center" data-rt-type="image" data-rt-align="center"><div><img src="https://uploads-ssl.webflow.com/58fe8f93dc9e750ca84ebb16/5b92b0ef2e799bfa4134fcb4_GitVersionWebhooksectoken.png"></div></figure></LI>
</UL>
<LI>Navigate back to the Version Control settings page and click “Connect”.</LI>
<LI>Once the connection is successfully established, a new <code>periscope/master</code> branch appears in the repository, along with a set of folders, one for each object type that is synced. The Periscope application will sync with the <code>periscope/master</code> branch in the repository as the Production branch. Any changes made in the application will be synced to the <code>periscope/master</code> branch and any changes merged into the <code>periscope/master</code> branch in Git will be reflected in the Periscope application.</LI>
</OL>

Note: To use a Git server behind a firewall, please whitelist all three IP addresses (18.204.27.101 and 34.232.21.202 and 18.208.88.222) on Port 22 (SSH)

<a href="#top">Back to top</a>

<a name="Github"></a>

<HR>

GitHub

<OL>
<LI>Create an empty Git repository (without a README) hosted at GitHub.</LI>
<UL>
<LI>If starting with a repository that is not empty and there is a desire to merge from origin/master to periscope/master, issue the following command to allow unrelated histories: <code>git merge --allow-unrelated-histories periscope/master.</code></LI>
<LI>It is required that the repository is set to Private so that access can be controlled (this is a setting that can be changed in the repository). Note: A premium GitHub account is required in order to create Private repositories.</LI>
</UL>
<LI>Get the SSH URL for your remote Git repository. Formats for GitHub:</LI>
<UL>
<LI>GitHub: git@github.com:&lt;organization-name&gt;/&lt;repository-name&gt;.git</LI>
<LI>GitHub Enterprise: git@example.com:&lt;organization-name&gt;/&lt;repository-name&gt;.git</LI><br>
<LI>For new GitHub repositories (repos that don't yet contain any new files), GitHub will show the SSH URL as part of the initial setup. On the Code tab, click the SSH button to get the SSH URL, then click the copy button to copy it to your clipboard </LI>
<UL><LI style="list-style: none;"><figure class="w-richtext-figure-type-image w-richtext-align-center" data-rt-type="image" data-rt-align="center"><div><img src="https://uploads-ssl.webflow.com/58fe8f93dc9e750ca84ebb16/5b92eec039ac89dcc39cf8cc_GitHubNewSSH.png"></div></figure>
</LI></UL>
<LI>For existing GitHub repositories (repos that already contain files), the SSH URL can be found by clicking on the Code tab, and click the 'Clone or download button'. Make sure to click the 'Use SSH' link, then click the copy button to copy it to your clipboard.</LI>
<UL><LI style="list-style: none;"><figure class="w-richtext-figure-type-image w-richtext-align-center" data-rt-type="image" data-rt-align="center"><div><img src="https://uploads-ssl.webflow.com/58fe8f93dc9e750ca84ebb16/5b92eeb704c9740158351ad7_GitHubExistingSSH.png"></div></figure></LI></UL>
</UL>
<LI>Paste the SSH URL from GitHub into the “SSH URL” field on the Version Control settings page:</LI>
<UL>
<LI style="list-style: none;"><figure class="w-richtext-figure-type-image w-richtext-align-center" data-rt-type="image" data-rt-align="center"><div><img src="https://uploads-ssl.webflow.com/58fe8f93dc9e750ca84ebb16/5b92b0ff25711d53654dac91_GitVersionSSH.png"></div></figure></div></LI>
</UL>
<LI>Copy the “Deploy Key” which Periscope provides on the Version Control settings page and paste it into the Settings for the repository:</LI>
<UL>
<LI>Be sure to select the <b><u>Allow write access</b></u> option because Periscope requires this setting in order to make and deploy changes. </LI>
<LI style="list-style: none;"><figure class="w-richtext-figure-type-image w-richtext-align-center" data-rt-type="image" data-rt-align="center"><div><img src="https://uploads-ssl.webflow.com/58fe8f93dc9e750ca84ebb16/5b92eeca7794ec6b8a74e1b2_GitHubDeployKey.png"></div></figure></LI>
</UL>
<LI>Navigate back to the Version Control settings page in Periscope, Copy the “Webhook URL” into Payload URL and “Webhook Secret Token” into Secret in the GitHub repository settings, either option for Content type will work:</LI>
<UL>
<LI style="list-style: none;"><figure class="w-richtext-figure-type-image w-richtext-align-center" data-rt-type="image" data-rt-align="center"><div><img src="https://uploads-ssl.webflow.com/58fe8f93dc9e750ca84ebb16/5b92eed26708aa78e7e0f1cc_GitHubWebhookSettings.png"></div></figure></LI>
</UL>
<LI>Navigate back to the Version Control settings page and click “Connect”.</LI>
<LI>Once the connection is successfully established, a new <code>periscope/master</code> branch appears in the repository, along with a set of folders, one for each object type that is synced. The Periscope application will sync with the <code>periscope/master</code> branch in the repository as the Production branch. Any changes made in the application will be synced to the <code>periscope/master</code> branch and any changes merged into the <code>periscope/master</code> branch in Git will be reflected in the Periscope application.</LI>
</OL>

<a href="#top">Back to top</a>

<HR>

<a name="Gitlab"></a>

GitLab

<OL>
<LI>Create an empty Git repository (without a README) hosted at GitLab.</LI>
<UL>
<LI>If starting with a repository that is not empty and there is a desire to merge from origin/master to periscope/master, issue the following command to allow unrelated histories: <code>git merge --allow-unrelated-histories periscope/master.</code></LI>
</UL>
<LI>Get the SSH URL for your remote Git repository:</LI>
<UL>
<LI>GitLab: git@gitlab.com:&lt;organization-name>/&lt;repository-name&gt;.git</LI>
<UL><LI style="list-style: none;"><figure class="w-richtext-figure-type-image w-richtext-align-center" data-rt-type="image" data-rt-align="center"><div><img src="https://uploads-ssl.webflow.com/58fe8f93dc9e750ca84ebb16/5b931b3c109adb570e889c53_GitLabSSH.png"></div></figure></LI></UL>
</UL>
<LI>Paste the SSH URL from GitLab into the “SSH URL” field on the Version Control settings page:</LI>
<UL>
<LI style="list-style: none;"><figure class="w-richtext-figure-type-image w-richtext-align-center" data-rt-type="image" data-rt-align="center"><div><img src="https://uploads-ssl.webflow.com/58fe8f93dc9e750ca84ebb16/5b92b0ff25711d53654dac91_GitVersionSSH.png"></div></figure></div></LI>
</UL>
<LI>Copy the “Deploy Key” which Periscope provides on the Version Control settings page and paste it into the Settings for the repository:</LI>
<UL>
<LI>Be sure to select the <b><u>Write access allowed</b></u> checkbox because Periscope requires this setting in order to make and deploy changes. </LI>
<LI style="list-style: none;"><figure class="w-richtext-figure-type-image w-richtext-align-center" data-rt-type="image" data-rt-align="center"><div><img src="https://uploads-ssl.webflow.com/58fe8f93dc9e750ca84ebb16/5b931b446708aadb74e129d0_GitLabDeployKey.png"></div></figure></LI>
</UL>
<LI>Navigate back to the Version Control settings page in Periscope, Copy the “Webhook URL” into URL and “Webhook Secret Token” into Secret Token in the GitLab repository settings:</LI>
<UL>
<LI style="list-style: none;"><figure class="w-richtext-figure-type-image w-richtext-align-center" data-rt-type="image" data-rt-align="center"><div><img src="https://uploads-ssl.webflow.com/58fe8f93dc9e750ca84ebb16/5b931b4d7794ecd61a750c89_GitLabWebHook.png"></div></figure></LI>
</UL>
<LI>Navigate back to the Version Control settings page and click “Connect”.</LI>
<LI>Once the connection is successfully established, a new <code>periscope/master</code> branch appears in the repository, along with a set of folders, one for each object type that is synced. The Periscope application will sync with the <code>periscope/master</code> branch in the repository as the Production branch. Any changes made in the application will be synced to the <code>periscope/master</code> branch and any changes merged into the <code>periscope/master</code> branch in Git will be reflected in the Periscope application.</LI>
</OL>

<a href="#top">Back to top</a>

<HR>

<a name="Bitbucket"></a>

BitBucket

Note: For BitBucket, the Webhook Secret Token that Periscope provides is not needed. Additionally, the setup is a little different as the Bitbucket user must be commissioned with the Periscope Deploy Key and the Repository needs to be set to access the Webhook URL.

<OL>
<LI>Create an empty Git repository (without a README) hosted at BitBucket.</LI>
<UL>
<LI>If starting with a repository that is not empty and there is a desire to merge from origin/master to periscope/master, issue the following command to allow unrelated histories: <code>git merge --allow-unrelated-histories periscope/master.</code></LI>
</UL>
<LI>Get the SSH URL for your remote Git repository:</LI>
<UL>
<LI>Bitbucket: git@bitbucket.org:&lt;organization-name&gt;/&lt;repository-name&gt;.gi</LI>
<UL><LI style="list-style: none;"><figure class="w-richtext-figure-type-image w-richtext-align-center" data-rt-type="image" data-rt-align="center"><div><img src="https://uploads-ssl.webflow.com/58fe8f93dc9e750ca84ebb16/5b98305753114f2fa48c0e72_BitBucketRepoCopySSHURL1.png"></div></figure></LI>
<LI style="list-style: none;"><figure class="w-richtext-figure-type-image w-richtext-align-center" data-rt-type="image" data-rt-align="center"><div><img src="https://uploads-ssl.webflow.com/58fe8f93dc9e750ca84ebb16/5b983061607a093d98d1e322_BitBucketRepoCopySSHURL2.png"></div></figure></LI>
</UL>
</UL>
<LI>Paste the SSH URL from BitBucket into the “SSH URL” field on the Version Control settings page. (BitBucket will copy over the ‘git clone’ command if you click the “Copy” button, so please ensure to delete the 'git clone' command from the URL when copying into Periscope):</LI>
<UL>
<LI style="list-style: none;"><figure class="w-richtext-figure-type-image w-richtext-align-center" data-rt-type="image" data-rt-align="center"><div><img src="https://uploads-ssl.webflow.com/58fe8f93dc9e750ca84ebb16/5b98304253114fb5938c0e63_PeriscopeBBsettings.png"></div></figure></LI>
</UL>
<LI>Copy the “Deploy Key” which Periscope provides on the Version Control settings page and paste it into the Settings for the BitBucket User:</LI>
<UL>
<LI>Go to the BitBucket <b><u>User</u></b> settings by navigating to the User in the lower left-hand corner, then to SSH keys under the Security section. Add a new key here:</LI>
<LI style="list-style: none;"><figure class="w-richtext-figure-type-image w-richtext-align-center" data-rt-type="image" data-rt-align="center"><div><img src="https://uploads-ssl.webflow.com/58fe8f93dc9e750ca84ebb16/5b98307853114f50128c0f94_BitBucketUserSettings.png"></div></figure></LI>
<LI style="list-style: none;"><figure class="w-richtext-figure-type-image w-richtext-align-center" data-rt-type="image" data-rt-align="center"><div><img src="https://uploads-ssl.webflow.com/58fe8f93dc9e750ca84ebb16/5b983081ad24e275fff13558_BitBucketAddSSHkey-User1.png"></div></figure></LI>
<LI style="list-style: none;"><figure class="w-richtext-figure-type-image w-richtext-align-center" data-rt-type="image" data-rt-align="center"><div><img src="https://uploads-ssl.webflow.com/58fe8f93dc9e750ca84ebb16/5b98308c518beaf4175ab847_BitBucketAddSSHkey-User2.png"></div></figure></LI>
</UL>
<LI>Navigate back to the Version Control settings page in Periscope, Copy the “Webhook URL” into the BitBucket Repository Settings by going to Settings, then Webhooks under the Workflow Section, then Add webhook:</LI>
<UL>
<LI style="list-style: none;"><figure class="w-richtext-figure-type-image w-richtext-align-center" data-rt-type="image" data-rt-align="center"><div><img src="https://uploads-ssl.webflow.com/58fe8f93dc9e750ca84ebb16/5b98306dd05a700bb5ab4ddf_BitBucketAddWebhookRepoSettings.png"></div></figure></LI>
</UL>
<LI>Navigate back to the Version Control settings page and click “Connect”.</LI>
<LI>Once the connection is successfully established, a new <code>periscope/master</code> branch appears in the repository, along with a set of folders, one for each object type that is synced. The Periscope application will sync with the <code>periscope/master</code> branch in the repository as the Production branch. Any changes made in the application will be synced to the <code>periscope/master</code> branch and any changes merged into the <code>periscope/master</code> branch in Git will be reflected in the Periscope application.</LI>
</OL>

<a href="#top">Back to top</a>

Our support team is ready to help