GitLake Manifest Specification

CircleCI Requirements Status Maintainability Test Coverage Documentation Status PyPI version

gms stands for GitLake Manifest Specification. It is a CLI tool for GitLake users to create and manage personalized manifest specifications.

If you just started using GitLake, we highly recommend you to use gitlake-basic-manifest-specification. We recommend you to directly contribute to the basic specification if you see any missing feature. This CLI tool is right for you only if you have special security requirement that cannot be satisfied by the basic specification, or you would like to build a vendor lock-in of your own manifest format.

  • Documentation: https://gms.readthedocs.io
  • Website: https://www.gitlake.com

Getting Started

Installation

Install gms from PyPi:

pip install gms

Basic Setup

To create a new manifest specification, first set up your git repository as usual:

mkdir my-manifest-specification
cd my-manifest-specification
git init
git remote add origin https://github.com/myaccount/my-manifest-specification

Then use gms to create the skeleton of a specification:

gms init

A specification repository typically looks like:

├── LICENSE
├── README.md
├── drafts
│   └── main.v7.json
├── sdks
│   └── python.json
└── spec.json
  • LICENSE: the license of the manifest specification
  • README.md: a description of the maniest specification
  • drafts: a directory that stores different Json schema drafts of the specification
  • sdks: a directory that stores different SDKs which processes a manifest of the specification
  • spec.json: the metadata of the specification, including name, version, etc.

New Manifest Specification Draft

A manifest specification is defined by a Json Schema. A manifest specification draft must comply to a Json Schema draft version. Because the Json schema draft version evolves constantly, this ensures that one specification can support multiple schema drafts. To create a new draft skeleton, run:

# create a new manifest specification draft of version 7 (default)
# read more: https://json-schema.org/draft-07/json-schema-release-notes.html
gms new draft --version 7

This will create a new file main.v7.json that user can then further define the actual schema.

New SDK Registration

The specification itself does not have any way to enforce user compliance. Therefore, each specification must come with its set of SDKs.

To register a new SDK, run:

gms new sdk --name python

This creates a new SDK named python.json that user can then further fill in the details of the SDK. Each SDK must describe a set of basic operations, with the schema given here.

Release Manifest Specification

In the end, the specification itself cannot be used without SDK support. Releasing a specification only means that other people can reference the specification in their own GitLakes. The release process is not managed by gms. Instead, it only provides a verification functionality to make sure that the specification repository has the expected structure.

To run verification, simply execute:

gms verify

To actually release the specification, it is the same as pushing the code to a remote git repository:

git add .
git commit -m "created new GitLake manifest specification through gms"
git push -u origin master