Pulling API specs from Git

It’s common to store your core taxonomy, existing API specs (such as OpenApi or Protobuf), or database definitions in a git repository, so they’re version controlled.

Orbital can read directly from your Git repository, pulling in updates as they’re merged.

A typical Git configuration consists of:

• The address of your git repository
• A branch to monitor
• A path within your repository to read

Additionally, if you’re connecting an OpenApi or Protobuf source, you’ll need to provide a little additional metadata.

The list of Git repositories that Orbital uses can be modified either through the Orbital UI or by editing a configuratoin file. This configuration file can be version-controlled and automatically deployed (for self-hosted deployments only).

​

Adding a Git repository using the UI

To add a new Git repository via the UI either navigate to /project-import, or from within the UI click on Projects on the left navigation bar, then “Add project” in the top bar.

​

Completing the new Git Repository form

Click on the “Git Repository” tab, and provide the details of how to connect to your git repo

​

Adding a Git repository through config

The schema repositories that Orbital is connected to can be configured through a HOCON file, which by default is called workspace.conf

git {
   # The root directory where all git repositories are cloned to
   checkoutRoot="/opt/service/orbital/git-root"
   # How frequently Orbital should poll git repositories for changes
   pollFrequency=PT30S
   
   # A collection of Git Repository configurations
   repositories=[
      {
         # Give this repo a name.  
         name=hamilton-taxonomy
         
         # The url (including personal access token) to clone the repo from
         uri="https://alexhamilton:glpat-dundadadadundundun@github.com/orbital/reynolds-pamphlet"
         
         # The branch to monitor
         branch=master

         # The path within the git repo (Optional, by default uses the root) 
         path="/a/path/to/a/folder"
      }
   ]
}

The full documentation for config-driven git repositories is available here.

​

Reading OpenApi specs from Git

If Orbital is reading an OpenApi spec from git, a few more parameters are needed.

git {
   # The root directory where all git repositories are cloned to
   checkoutRoot="/opt/service/orbital/git-root"
   # How frequently Orbital should poll git repositories for changes
   pollFrequency=PT30S
   
   # A collection of Git Repository configurations
   repositories=[
      {
         # Give this repo a name.  
         name=hamilton-taxonomy
         
         # The url (including personal access token) to clone the repo from
         uri="https://alexhamilton:glpat-dundadadadundundun@github.com/orbital/reynolds-pamphlet"
         
         # The branch to monitor
         branch=master

         # The path within the git repo (Optional, by default uses the root) 
         path="/a/path/to/a/folder"

         loader: {
            # Must be OpenApi
            packageType: 'OpenApi'
            
            # Orbital will automatically create services and models
            # from the OpenApi spec, and place them under this namespace.
            # Mandatory.
            defaultNamespace: 'com.hamilton'

            # If the paths specified in the OpenApi spec are relative,
            # and no base path is specified, then specify one here.
            serviceBasePath: https://hamilton.com/

            # Provides a project identifier for this api spec.
            # Mandatory
            identifier: {
              organisation: acme
              name: hamilton
              # Must be a Semver version
              version: '1.1.0'
            }
         }
      }
   ]
}

​

Git Urls and Authentication

Currently, https:// connections are supported only.

To provide authentication credentials, use a Username + Personal Authentication Token (supported in Github and Gitlab).

For example:

https://alexhamilton:glpat-dundadadadundundun@github.com/orbital/reynolds-pamphlet

Support for ssh:// connections with public/private keypairs is available in a private beta. If you’d like to try it out, please get in touch.

​

Supporting edits to Git repositories

When changes are made to services or taxonomy definitions within Orbital’s UI, these need to be written somewhere.

It’s common that these are persisted to a git repository.

Orbital supports two different flows for edits:

• Committing and pushing directly to the configured branch (default)
• Committing and pushing to a branch, and raising a Pull Request (Github only)