Git Integration

👤 This documentation is intended for Site Administrators.

With Git Integration, Periscope provides data professionals with complete control over their analytics environment, offering file-level access to user generated content, and support for release management workflows. Unlike other analytics solutions, Periscope provides a complete bi-directional sync for all user generated content including Dashboards, Charts, Views, and Snippets and works with any remote Git repository, including an owned Git server.

For instructions on how to connect a Git repository to Periscope refer to the Connecting a Git repository page.
For more information on the structure of the repository and configuration files, refer to the Git Configuration page.

<UL>
<LI><a href="#GitUseCases">Git Use Cases</a></LI>
<LI><a href="#HowItWorks">How It Works</a></LI>
<LI><a href="#GitDisconnect">Disconnecting Git</a></LI>
<LI><a href="#GitCommits">Git Commits in the History Tab</a></LI>
<LI><a href="#Troubleshoot">Troubleshooting Git Errors</a></LI>
<UL>
<LI><a href="#Tags">Git Tags</a></LI>
<LI><a href="#Slack">Slack Integration</a></LI>
</UL>
</UL>

Note: Git Integration is available on select plans. Site administrators can contact their Account Manager for additional information.
With the 2018 release, Git Integration supports Snippets, Views, Charts, and Dashboards.

<HR>

<a name="GitUseCases"></a>

Git Use Cases

<OL>
<LI><b>Sophisticated, externalized version control with code review</b></LI>
<UL><LI>Git integration gives users all of the great features and functionality of Git as a version control system, in addition to providing full, external access to all user generated content.</a></LI></UL>
<LI><b>Automate content creation, search & replace, and clone across Spaces</b></LI>
<UL><LI>With user generated content represented externally as a set of files in a Git repository, users have the power and flexibility to perform any kind of batch processing and automation on their data. Some examples include programmatically creating, editing, and deprecating dashboards, finding and replacing across many files, cloning objects across Spaces, and much more.</b></LI></UL>
<LI><b>Release Management</b></LI>
<UL><LI>Ensure a reliable and stable production environment by previewing and collaborating on changes on a branch prior to pushing live to production.</LI></UL>
</OL>

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

<a name="HowItWorks"></a>

How It Works

<OL>
<LI>User creates an empty remote repository (GitHub, GitLab, Bitbucket, corporate Git Server, etc) and links it to a Space in Periscope (one repository per Space)</LI>
<LI>Once configured, a two way sync is established between the Space in Periscope and the user's remote repository (all supported objects will be synced automatically on initial sync and going forward)</LI>
<LI>Any changes made to the supported objects in Periscope are synced to the user's remote repository</LI>
<LI>Any changes merged into the periscope/master branch in the user's remote repository are synced to Periscope</LI>
</OL>

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

<a name="GitDisconnect"></a>

Disconnecting Git.

Site administrators can contact support@periscopedata.com if they would like to disconnect a repo.

Once a repository is disconnected a new repository can be connected to that space. An empty repository is necessary to connect to Periscope, if there are already directories named dashboards, snippets, and views, duplicates can be created. When making a new connection, all fields including the Webhooks will have to be re-entered.

<a href="#top">Back to top</a>
<a name="GitCommits"></a>
<a name="Troubleshoot"></a>

Git Commits in the History Tab

Changes made in-app will include the editor's name in the History tab of the chart editor. For changes made through Git, the user's name will not be specified in the in-app History tab but it will be specified in the Git repository's history tab as the Git user that pushed the change.

<a name="Tags"></a>
<a name="Slack"></a>

Troubleshooting Git Errors

Once a Git repository is connected to Periscope, dashboards, charts, views and snippets will all be in sync between the two. However, if there are invalid changes being pushed from the local repository to Periscope then the changes may be rejected or ignored. There are two ways to identify these invalid changes, one is using Git Tags and the other is through the Slack Integration. 

Git Tags

Git Tags are reference points in a repository’s history. When there is an invalid change pushed to the Periscope app the error will be logged as a tag. Tags can be useful for seeing the history of errors for a repository that is connected to Periscope. 

Accessing Git Tags: 

Slack

Administrators are able to set up a Slack channel that will receive a detailed log of all git imports. If the import was unsuccessful, then the Slack message will include the number or errors, the suspected commit, and the error message. 

Note: The Slack Integration is available on select plans. Site Administrators can contact their Account Managers for more information. 

Setting up a Slack Channel

<ol>
<li>Set up the Slack Integration. Details can be found <a href="https://doc.periscopedata.com/article/slack-integration">here</a>. If the Slack Integration is already set up for the site, skip this step.</li>
<li>Create a public or private Slack channel that will receive all of the import logs.</li>
<li>Add @periscope_data to the channel.</li>
<li>Go to the Version Control page in Periscope and enter the Slack channel name.
<ul>
<li>If the textbox to enter the channel name is disabled, then the Slack Integration was not properly configured. Return to step 1 and verify a successful integration. </li>
<li>Multiple channels can be added. </li>
</ul></li></ol>

Below is an example of what a successful and unsuccessful log may look like.


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

Our support team is ready to help