Connecting Platform to Github/Bitbucket
First, add a repository to Platform through your user profile. You can add a repository from either Github or Bitbucket.
Click on the “Git Repos” tab at the top of the page. You’ll navigate to a page that shows a list of repositories that you have bookmarked to your profile. You can add new repositories by clicking the "Add Repository" button.
Next go to the Platform object that you would like to version control. This can be an existing or a new SQL, R, or Python Script, Workflow, HTML Report, or a stopped Notebook. For a running notebook, changes must be committed using the Notebook terminal. See our Notebooks documentation for instructions. The example below is for a Python script.
Start by filling out the three relevant fields in the settings.
Repository: The repository field is a drop-down of the list of repositories that you have bookmarked in your profile.
Branch: The specific branch you would like to use to version control this Script. The branch must already exist in your repository.
Path: The path to a file in your repository that you would like to use to version control your Script. If the file does not yet exist in your repository, Platform will create a new file for you in the repository. Please note that this path must be an individual file and not a directory.
Committing and Pushing Changes to Github/Bitbucket
After saving your repository's info, you can pull data from or push data to your repository through the “Manage Versions” side pane.
In this pane you will see the Git information you just linked, an area to commit + push changes from platform, and an area to view the commit log.
The Git information will match the settings you just provided in the Script details area.
Commit + Push
When you make changes to your Script, an icon will appear that indicates that there are “Uncommitted Changes.” Platform will not automatically commit and push these changes -- this must be done by pressing the “Commit + Push” button. Platform provides a text box to add a commit message as you push your changes from Platform to your Git repository.
In the event that a commit causes a merge conflict, Platform will show an error message and will neither commit and push the change nor resolve the merge conflict. Instead, the error message will prompt you to click the “update history” button. This will update the commit log with the latest commits from Git.
After refreshing the pane, the merge conflict will disappear. However, there is a possibility that committing and pushing changes at this point may overwrite code pushed from outside of platform, or from another user. We recommend you check the code in your Git repo and compare to your Platform code before proceeding.
Git Commit Log
Platform will automatically pull a log of commits for the file in the specific repository and branch you have selected. These commits will only reflect commits where the selected file has changed -- it is not the full commit history for the branch and/or repository.
The Git commit log will also indicate if the current Script contains code that was checked out from a specific Git commit, through the green dot on the left. In this example, this script builds on code from commit “Change date to 2018”, hash: “a5bc7c1”
Platform allows you to “checkout” old versions of code at a specific commit. Platform will warn you if checking out old code will overwrite uncommitted changes that you have. Checking out an old commit does not automatically commit and push back to Git. This can be done though through the Commit and Push button.
Credentials + Secrets
You should not store text such as passwords, API keys, or other sensitive information in Git. We offer a secure way to store your credentials in Civis Platform. For more information, visit our Credentials documentation.
Github and Bitbucket are an external services that are not managed by Civis. While we do securely connect to both, Civis security controls do not extend to third party services.
Autosaving vs Committing
Platform automatically saves progress and changes to your script. However, Platform does not automatically commit to or pull from the Git repository when your script or the repository changes. In other words, changes made to a Platform script that are autosaved in Platform will not be reflected in Git unless manually pushed through the “Manage Versions” pane.
Cannot see a repo in my organization's GitHub account in Civis Platform profile page
When a user allows an OAuth application (e.g. Platform) access to their Github, the allowed permissions do not necessarily extend to repositories in that user's organizations.
- Have GitHub organization account administrator approve the Platform app for the organization's account and/or remove restrictions within third party application access policy
- Reauthorize Github with platform for user account
- Go to your initials on the top right, click on "My Profile"
- click on the "Git Repos" tab
- click "Add Repository" on the top right
- click on "Connect to GitHub" and add your login information to GitHub in Platform
- Authorize the Account
You now should be able to go back into Platform and see the repos you have access to in the drop down.