Docs: Installation: Cloud Linter

Skeema Cloud Linter is a SaaS tool, meaning there’s nothing to install locally; the software runs entirely in the cloud and interfaces with GitHub’s API. It does not connect to your actual databases.

On every git push, Cloud Linter executes logic similar to skeema diff --lint, comparing the new commit’s CREATE statements to either the merge-base (if part of a pull request) or the previous commit (non-PR). Linter annotations are displayed inline on pull request pages, making code review easy. Diff output DDL and linter annotation summaries are rendered into a pull request comment. All of this happens automatically, typically within 20 seconds of your git push, without any need to configure YAML in a CI system or GitHub Action.

IMPORTANT:

  • Cloud Linter is not a stand-alone product! In order for Skeema Cloud Linter to operate, you must already be using Skeema CLI.
  • Cloud Linter cannot be used with arbitrary non-Skeema-related repositories, such as mysqldump output or Ruby on Rails structure.sql files.
  • Do NOT add Skeema Cloud Linter to all repositories in your GitHub account. Doing so causes our servers to be flooded with webhook requests on every commit your company makes to any repo. Your Cloud Linter account will be permanently suspended if this occurs.

Signing up

Skeema Cloud Linter is designed to be used on repos managed by the Skeema CLI. If you’re new to Skeema, download the CLI and then explore the Getting Started doc prior to enabling Cloud Linter.

To enable Skeema Cloud Linter, contact us to inquire about a free trial. Your company must already be using the Skeema CLI before using Cloud Linter.

Repo selection

When installing Cloud Linter on a GitHub account, you will be prompted for which repositories to enable the application on. By default, GitHub’s UI will select all of your repos; do not leave this default enabled. You will need to select just your Skeema-related repo(s) instead.

Cloud Linter can be enabled on public or private repos. There are no restrictions on repo privacy, regardless of account type. We generally recommend use of private repos for most schema management use-cases.

You can choose to have a single repo dedicated to Skeema files, or multiple dedicated repos (e.g. one per database cluster or company org), or a “mono-repo” which places Skeema files in a subdirectory alongside application code. However, you should not enable Cloud Linter on repos that are completely unrelated to Skeema.

One consideration for mono-repos: if the repo is excessively large or takes too long to clone, Cloud Linter will reject it with an error. In this case, please use a separate repo for storing your schema definitions.

Dashboard

Skeema Cloud Linter’s dashboard shows recent commits and lint result summaries for your repos. For organizations, admin users may also manage billing settings. Authentication is based on GitHub OAuth login.

Cloud Linter dashboard example

Configuration

Cloud Linter is intended to operate on repos managed by the skeema CLI. Within a repo, all configuration is managed by .skeema files in the same way as the CLI. A few notes specific to Cloud Linter:

  • In terms of environments, Cloud Linter will use the values configured for the production environment, since this tends to be the strictest configuration regarding linter options.

  • Some options have no effect on Cloud Linter. For example, since Cloud Linter does not connect to your actual database servers, connectivity options such as host, port, socket, user, and password are all ignored. Similarly, all options relating to workspaces, Docker, and temp-schema are ignored.

  • The flavor option is particularly important in Cloud Linter, as it determines which database version and vendor’s dialect to use when examining your schema repo.

  • Anything set in connect-options will be respected. This can be useful for overriding database settings at the session level.

For more information on Skeema configuration in general, see the configuration guide and options reference.