Orbital

Your workspace

Pulling API specs from Git

Orbital can read schema and taxonomy definitions direct 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
   # Optional.    # Configures how changes are detected on disk by Orbital once pulls have been   # made from the git repo (or if changes are made locally).   # WATCH (default) or POLL      diskChangeDetectionMethod=WATCH
   # Optional.    # If the diskChangeDetectionMethod is set to POLL, defines how frequently the disk is polled   # Defaults to 30s   diskPollFrequency=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.