Your workspace
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

Tip...
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.