Create releases

The primary method of creating releases is via the command line. The dashboard does not support creating new releases (although you can duplicate existing releases). Creating releases from the CLI is a deliberate design choice. We believe that config schemas should live in the same Git repository as the code which uses them. The CLI promotes such practices, simplifying the release process and encouraging better software development habits. Furthermore, the CLI can be used to programmatically create releases in a CI pipeline, ensuring releases contain the correct schemas and are always associated with the correct Git commit. If you’ve created a release via the CLI before and want a concise overview of the command and its flags, visit the CLI Reference. For a comprehensive guide, continue reading below.

Prerequisites

To create a release, the following prerequisites must be met:

CLI installed - install the Miru CLI on your development machine and authenticate using the login command
Local Git repository - the release’s schemas must be committed to a local Git repository
Config types annotations - each schema must be annotated with its config type

Config schemas

A release may be created with any number of config schemas, but it must contain at least one. Schemas don’t need to be created separately from releases. Instead, the CLI creates the schemas in the same command as the release itself. Since schemas may belong to multiple releases, specifying schemas which already exist in Miru is perfectly valid. The CLI simply attaches the schemas to the release. The CLI identifies schemas by hashing their content. Schemas with equivalent content are considered identical in Miru (even if the comments, spacing, or other formatting is different).

Define the schemas

Schemas must be defined in a supported schema language. You can find example schemas in our getting-started repository. If you’re not sure which language to use, we recommend starting with JSON Schema — it’s the most widely used and easiest to get started with. If you don’t currently use a schema, we recommend starting with an empty schema, one that regards all config instances as valid. Over time, you can gradually add constraints to make it more strict.

$schema: "https://json-schema.org/draft/2020-12/schema"
x-miru-config-type: "{your-config-type-slug}"

Schema annotations

Annotations are a convenient way to store metadata with your schemas. Most annotations are optional, but some are required for Miru to process the schemas correctly.

config type

required

The config type is a required annotation that identifies the config type to which a schema belongs. Below is the syntax for annotating a schema with a config type slug.

x-miru-config-type: "{config-type-slug}"

Examples: mobility, safety-features, perception

instance file path

The instance file path is the file system location that config instances for this schema are deployed to relative to the /srv/miru/config_instances directory.This annotation is optional and defaults to {config-type-slug}.json, which deploys config instances to /srv/miru/config_instances/{config-type-slug}.json on a given device.

x-miru-instance-filepath: "{instance-file-path}"

Examples: /v1/mobility.json, /safety.json, configs/perception.json

CUE packages

CUE supports the concept of a package—a way to spread a schema’s definition across multiple files. For example, say we have a communication schema which contains the following files:

communication

peripherals.cue

network.cue

sensors.cue

main.cue

Each file defines a portion of the schema, which is then aggregated by the main.cue file to define the schema. Miru fully supports CUE packages, treating the communication directory as a single schema. Identifying packages The Miru CLI automatically identifies CUE packages for you when creating a release using the package clause at the top of each schema file (as described in the CUE documentation). You don’t need to explicitly specify the package in the CLI command—just provide the path to the package directory or to the individual schema files within the package. Annotations To annotate a CUE package, annotate exactly one file in the package. Annotating multiple files or no files will result in an error.

Git commit

When creating a release, the CLI captures the following Git metadata from the local Git repository where the CLI is run:

Metadata	Description
Commit SHA	The SHA of the current commit
Origin URL	The remote URL of the Git repository
File paths	The file paths of the schemas relative to the repository root

This metadata is then made available in the dashboard for the release, allowing you to easily trace the release’s origin.

Supported Git providers

The following Git providers are currently supported:

GitHub
GitLab
Bitbucket

If your Git repository is hosted on a different provider, please reach out to support@mirurobotics.com.

Requirements

To be able to capture Git metadata, the provided config schemas must meet the following requirements when creating a release via the CLI:

Schemas must be defined in a local Git repository
The Git repository must have a remote URL (e.g., GitHub, GitLab, Bitbucket).
The schema’s latest changes must be committed to the Git repository before pushing to Miru (cannot be dirty or unstaged)

Git metadata is not optional. If a schema does not meet these requirements, the CLI will return an error and fail to create the release.

CLI command

Once you’ve defined the schemas and committed them to Git, you’re ready to create a release.

Usage

You must specify two flags when creating a release: the version and the schemas. Schemas can be specified as a directory or as individual files.

Schema Directory
Schema Files

Use the --schemas flag to specify a directory containing the schemas to include in the release.

miru release create \
  --version {version} \
  --schemas {/path/to/schemas/directory/}

Use the --schema flag to specify schema files to include in the release.

miru release create \
  --version {version} \
  --schema {path/to/schema1.yaml} \
  --schema {path/to/schema2.yaml}

Flags

Below are the CLI flags which can be specified when creating a release.

--version, -v

string

required

A semantic version, unique for a given release.Versions must be dot-separated integers. You may optionally use a v prefix, a prerelease suffix (e.g. -alpha.X, -beta.X, -rc.X), or a build suffix (e.g. +build-metadata).Examples: v1, 1, v2.1, 2.1, v3.2.1, 3.2.1, v4.3.2-beta.1, 4.3.2-rc.1, v5.4.3+metadata, 6.5.4-beta.2+metadata

--schemas

string

A directory containing the config schemas to include in the release. May be specified multiple times for multiple directories.Must be specified if no schema files are provided.Examples: ./schemas

--schema

string

The path to a config schema to include in the release. May be specified multiple times to include multiple schemas.Must be specified if no schema directory is provided.Examples: ./schemas/schema1.yaml, ./schemas/schema2.yaml

Examples

Below are some examples of what the CLI command might look like when creating a release.

New schemas
Existing schemas

If the provided git commit and schemas do not exist in Miru, they are created and attached to the new release. This is indicated by the (new) suffix in the output.

command

$ miru release create \
  --version v1.0.0 \
  --schemas ./cue/strict-schemas/

◐ Creating release v1.0.0

  ✓ Pushed git commit (new)
    1c7f7a8 · miruml/getting-started

  ◐ Pushing schemas
    ✓ Mobility · SCH-D5nFP (new)
    ✓ Planning · SCH-37QAr (new)
    ✓ Communication · SCH-9WfCx (new)

✓ Created release v1.0.0

If the provided git commit and schemas already exist in Miru, they are attached to the new release. This is indicated by the (existed) suffix in the output.

command

$ miru release create \
  --version v1.0.0 \
  --schemas ./cue/strict-schemas/

◐ Creating release v1.0.0

  ✓ Pushed git commit (existed)
    1c7f7a8 · miruml/getting-started

  ◐ Pushing schemas
    ✓ Mobility · SCH-D5nFP (existed)
    ✓ Planning · SCH-37QAr (existed)
    ✓ Communication · SCH-9WfCx (existed)

✓ Created release v1.0.0

Getting started

Learn

Developers

Administration

Create releases

Prerequisites

Config schemas

Define the schemas

Schema annotations

CUE packages

Git commit

Supported Git providers

Requirements

CLI command

Usage

Flags

Examples

Getting started

Learn

Developers

Administration

​Prerequisites

​Config schemas

​Define the schemas

​Schema annotations

​CUE packages

​Git commit

​Supported Git providers

​Requirements

​CLI command

​Usage

​Flags

​Examples

Prerequisites

Config schemas

Define the schemas

Schema annotations

CUE packages

Git commit

Supported Git providers

Requirements

CLI command

Usage

Flags

Examples