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 configuration file. This configuration file can be version-controlled and automatically deployed (for self-hosted deployments only).

Adding a Git repository using the UI

Open Projects in the sidebar and click Add project (or go straight to /projects/project-import). Choose Connect a Git repository, then Connect a repository.

Add project - pick how to add a project

Add project - pick how to add a project

Add project - pick how to add a project

Completing the Git repository form

Provide the details of how to connect to your git repo:

The Git repository form

The Git repository form

The Git repository form
  • Authentication - leave as None for a public, read-only repository. Otherwise pick the credentials to use: sensitive values are stored as references to entries in your secrets manager, so you can pick an existing secret or create one inline.
  • Project type - a git repository can hold a full Taxi project, or an individual API spec (such as an OpenAPI document). For a Taxi project, provide the path (from the root of the repository) to the directory containing the taxi.conf file.

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 in workspace.conf, use a Username + Personal Authentication Token (supported in Github and Gitlab) in the url. (In the UI, choose the credentials in the Authentication field instead - the token is kept in your secrets manager rather than in the url.)

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.