Create a release

The only way to create releases is via the command line. The dashboard only supports duplicating releases. Creating releases from the CLI is a deliberate design choice—we believe a release’s definition should be versioned in a Git repository. The CLI promotes this practice, simplifying the release process and encouraging better software development habits.

Continuous integration

The CLI can be used to programmatically create releases in a CI pipeline, ensuring releases are automatically created when code is pushed to a Git repository. Visit the CI/CD page for more information.

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 definitions must be committed to a local Git repository

Config schemas

Config schemas aren’t created separately from releases. Instead, the CLI creates the schemas in the same command as the release itself. Releases may contain any number of schemas, but they must contain at least one. Schemas may belong to multiple releases and are identified by hashing their content. Schemas with equivalent content are considered identical (even if 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}"

@miru(config_type="{your-config-type-slug}")

Miru supports CUE packages as a way to split a schema’s definition into multiple files. Read more in the CUE documentation.

Schema annotations

Schemas support annotations—Miru-specific extensions that define metadata about a schema. The config type annotation is the only required annotation—it’s how Miru knows which config type the schema belongs to. However, there are other useful annotations, such as the instance file path annotation, which defines where config instances for this schema are written to disk on your devices.

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}"

@miru(config_type="{config-type-slug}")

If the provided config type slug does not yet exist, it is automatically created. To edit a config type after creation, visit the config types documentation.Examples: mobility, communication, perception

instance file path

The instance file path is the absolute file system path where config instances for this schema are written on the device.

The Miru Agent ships with out-of-the-box access to /srv/miru. To deploy configs to a custom directory, please visit the File system access page.

Instance file paths control the type of file that config instances are deployed as. Currently, JSON (.json) and YAML (.yaml, .yml) are supported.This annotation is optional and defaults to /srv/miru/configs/{config-type-slug}.json.

x-miru-instance-filepath: "/srv/miru/configs/{config-type-slug}.json"

@miru(instance_filepath="/srv/miru/configs/{config-type-slug}.json")

Examples:

/srv/miru/configs/mobility.json
/home/myapp/configs/communication.yaml
/var/lib/myapp/configs/safety.yaml

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 and upload rules must meet the following requirements when creating a release via the CLI:

Must be defined in a local Git repository
The Git repository must have a remote URL (e.g., GitHub, GitLab, Bitbucket).
The schemas and upload rules’ 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 or upload rule 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
Upload Rules

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}

Use the --upload-rule flag to include upload rule files in the release, or --upload-rules for a directory of rule files. Upload rules ride along with the release’s config schemas.

miru release create \
  --version {version} \
  --schemas {/path/to/schemas/directory/} \
  --upload-rule {path/to/rule1.yaml} \
  --upload-rules {/path/to/upload/rules/directory/}

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

--upload-rules

string

A directory containing upload rule YAML files to include in the release. May be specified multiple times for multiple directories. Only YAML files in the directory are picked up.Examples: ./upload-rules/

--upload-rule

string

The path to an upload rule YAML file to include in the release. May be specified multiple times to include multiple rules.Examples: ./upload-rules/robot-logs.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 · mirurobotics/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 · mirurobotics/getting-started

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

✓ Created release v1.0.0

Welcome

Primitives

Config Management

Data Uploads

Developers

Administration

Create a release

Continuous integration

Prerequisites

Config schemas

Define the schemas

Schema annotations

Git commit

Supported Git providers

Requirements

CLI command

Usage

Flags

Examples

​Continuous integration

​Prerequisites

​Config schemas

​Define the schemas

​Schema annotations

​Git commit

​Supported Git providers

​Requirements

​CLI command

​Usage

​Flags

​Examples

Continuous integration

Prerequisites

Config schemas

Define the schemas

Schema annotations

Git commit

Supported Git providers

Requirements

CLI command

Usage

Flags

Examples