Using Git Provider Integration
This section will show how to use GitHub integration in a Capsule, but the functionality is identical for Pipelines and for the other Git providers.
Create a Capsule by Cloning a Git Repository
Click New Capsule and select Clone from Git.
Enter the HTTPS link of the Git repo to clone.
If the third option under New Capsule is Clone from <GitHub Organization>, you will only be able to create Capsules by cloning repos from that GitHub organization.
If the repo had a metadata, environment, code, or data folder, files in those folders will be stored under the corresponding directory in the Capsule. Otherwise all files will be stored in the "Other Files" section of the Capsule and can subsequently be reorganized.
Committing and Syncing Changes
New changes in the Capsule can be committed in the Capsule Timeline. After changes are committed, Sync with GitHub can be used to push changes to the GitHub repo.
Pulling Changes from GitHub
If changes to the repo have been made outside of the Capsule, Check for updates can be used to identify unsynced commits. Sync with GitHub can subsequently be used to pull any new commits from GitHub.
Concurrent Collaboration
When developing a Capsule with a collaborator, only one person can edit the Capsule at once. Git Provider Integration provides the ability for collaborators to develop a project concurrently by working in multiple Capsules that are all linked to the same GitHub repo. This can be achieved by creating multiple Capsules by cloning the same GitHub repo, or by duplicating a GitHub integrated Capsule and choosing to "Link to Git Repository".
Duplicating a GitHub Integrated Capsule
There are two options when duplicating a Capsule linked to a GitHub repo:
Link to Git Repository: the new Capsule will be linked to the same GitHub repo.
Create a new repository in Code Ocean: the new Capsule will be independent of the source Capsule as it will have its own Git repo in Code Ocean's internal Git server.
Creating Branches
When developing a new feature or collaboratively developing a repo, it's a good practice to work on a new branch. If the GitHub repo has multiple branches, they will be available in the Capsule upon creation or after syncing with GitHub.
A new branch can be created in the Capsule by opening a Cloud Workstation with access to the terminal and running git branch <new_branch_name> to create the branch or git checkout -b <new_branch_name> to create the branch and immediately switch to it.
Switching Branches
Switching between branches in a Capsule's Git repo can be done from the Capsule IDE.
Once changes on a branch have been pushed, a pull request can be opened in GitHub and changes can be merged into the main branch.
Merge conflicts can be resolved in GitHub.
Releasing a GitHub Integrated Capsule
When you release your Capsule, the release version will be created from the main branch. A new Git repo is created for the release version within Code Ocean’s internal Git server. As new versions are released, commits are squashed so that there is one tagged commit per release version.
Using Git Credentials
After adding Git credentials to the Account Page, they will automatically be available during runtime and during the environment build stage as the GIT_ACCESS_TOKEN environment variable.
The existence of this variable enables the use of Git commands without providing credentials. This can be used to clone private Git repos for installation as part of the environment, as well as for convenient use of Git commands during a Cloud Workstation Session.
Connect an existing Capsule to a Git Provider
If a Capsule wasn’t initially cloned from a GitHub repo, it’s possible to push the Capsule to GitHub and then create a new Capsule from the repo.
Create an empty GitHub repo, don't initialize it with a README.md or any files.
In Code Ocean, make sure you've configured a GitHub Personal Access Token.
In your Capsule, commit your changes, launch a terminal Cloud Workstation and execute the following commands:
git remote rename origin private_origingit remote add origin <SOME-URL>/<YOUR-GITHUB-REPOSITORY-NAME>.gitgit push -u origin masterAll files tracked by Git have now been pushed to the GitHub repo, refresh the GitHub repo's page to see the changes.
Create a new Capsule by cloning the GitHub repo.
The original Capsule can now be archived and/or deleted.
