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 the CLI
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, and the instance slots annotation, which lets one schema write several files by declaring a destination for each.

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

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

The schema language declares the language that a schema is written in. This annotation applies to Opaque schemas only, and is required for them.JSON Schema and CUE schemas have no schema language annotation. Their language is inferred from the schema file itself, so a .cue file is read as CUE, and a .json or .yaml file is read as JSON Schema unless it declares itself opaque.

Opaque

language: "opaque"

Because an opaque schema is written as JSON or YAML — the same formats as a JSON Schema — this annotation is what distinguishes the two.

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.

This annotation is optional and defaults to /srv/miru/configs/{config-type-slug}.{instance-format}. To share the same schema amongst multiple config instances, declare instance slots instead.

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

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

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

Instance slots define one or more config instances that are valid for a given schema. Instead of maintaining a near-identical config type for each destination, declare several slots to allow multiple config instances to share a single schema.

A schema may declare an instance file path OR instance slots. Declaring both will error.

This annotation is optional. Omitting it will either use the instance file path annotation, or create a single slot with default values.

x-miru-instance-slots:
  - key: "left-arm"
    name: "Left Arm"
    filepath: "/srv/miru/configs/v1/left-arm.json"
    required: true
    description: "Config for the left arm controller"
  - key: "right-arm"
    name: "Right Arm"
    filepath: "/srv/miru/configs/v1/right-arm.json"
    required: false

@miru_instance_slot(
  key="left-arm", 
  name="Left Arm", 
  filepath="/srv/miru/configs/v1/left-arm.json", 
  required=true, 
  description="Config for the left arm controller",
)
@miru_instance_slot(
  key="right-arm", 
  name="Right Arm", 
  filepath="/srv/miru/configs/v1/right-arm.json", 
  required=false,
)

instance_slots:
  - key: "left-arm"
    name: "Left Arm"
    filepath: "/srv/miru/configs/v1/left-arm.json"
    required: true
    description: "Config for the left arm controller"
  - key: "right-arm"
    name: "Right Arm"
    filepath: "/srv/miru/configs/v1/right-arm.json"
    required: false

For more information about instance slots, visit the Instance slots section of the schemas documentation.

The instance format declares the format that config instances for this schema are deployed as on the device.Visit the File formats section of the schemas documentation to learn which formats are supported for each schema language.This annotation is optional and is inferred from the instance file path’s extension. Under the default instance file path of /srv/miru/configs/{config-type-slug}.json, the instance format therefore defaults to json.

x-miru-instance-format: "yaml"

@miru(instance_format="yaml")

instance_format: "xml"

Examples: json, yaml, xml, text

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:

Must be defined in a local Git repository
The Git repository must have a remote URL (e.g., GitHub, GitLab, Bitbucket).
The schemas’ 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
File 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 --file-rule flag to include file rule files in the release, or --file-rules for a directory of rule files. File rules ride along with the release’s config schemas.

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

Flags

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

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

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

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

string

A directory containing file 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: ./file-rules/

string

The path to a file rule YAML file to include in the release. May be specified multiple times to include multiple rules.Examples: ./file-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