build(lint): add surface linter (yamllint, shellcheck, actionlint)

.github/actionlint.yml

@@ -0,0 +1,7 @@
+# See: https://github.com/rhysd/actionlint/blob/main/docs/config.md
+# Register custom org-provided runner labels so actionlint does not flag them
+# as unknown. `ubuntu-latest-8c` is a larger GitHub-hosted runner used by the
+# release workflow.
+self-hosted-runner:
+  labels:
+    - ubuntu-latest-8c

.github/workflows/builder.yml

@@ -55,4 +55,3 @@ jobs:
           labels: ${{ steps.meta.outputs.labels }}
           cache-from: type=gha
           cache-to: type=gha,mode=max
-

.github/workflows/ci.yml

@@ -85,3 +85,9 @@ jobs:
 
       - name: Run Tests + Coverage Gate
         run: ./tools/lint/scripts/covgate.sh
+
+  surface-lint:
+    # yamllint disable rule:line-length
+    uses: mirurobotics/.github/.github/workflows/surface-lint.yml@main
+    with:
+      runs-on: ubuntu-latest

.shellcheckrc

@@ -0,0 +1,8 @@
+# Do not set a global `shell=` directive: the agent repo has mixed shebangs
+# (#!/bin/sh, #!/usr/bin/env bash, #!/bin/bash). Let shellcheck honor each
+# file's shebang so bash scripts (scripts/preflight.sh, api/regen.sh) are not
+# falsely flagged with SC3040 (pipefail undefined in POSIX sh).
+
+# SC1091: Not following sourced files. Several scripts source files shellcheck
+# cannot resolve (.venv/bin/activate, $HOME/.cargo/env, build/git-tags.sh).
+disable=SC1091

.yamllint.yml

@@ -0,0 +1,22 @@
+# See: https://yamllint.readthedocs.io/en/stable/
+
+extends: default
+
+rules:
+  document-start:
+    present: false
+  line-length:
+    level: warning
+    allow-non-breakable-inline-mappings: true
+  # GitHub Actions uses `on:` as a workflow trigger key; YAML 1.1 treats `on`
+  # as a truthy boolean alias. Disable key checking to avoid false positives.
+  truthy:
+    check-keys: false
+  # SHA-pinned action comments use a single space before `#`. Reduce the
+  # minimum from the default 2 to 1 to match the existing convention.
+  comments:
+    min-spaces-from-content: 1
+
+ignore: |
+  .agents/
+  api/specs/

build/.goreleaser.yaml

@@ -30,7 +30,7 @@ nfpms:
     description: |
       Miru Agent.
       Miru provides the infrastructure to version, manage, and deploy application configurations at scale. This debian package is the miru agent, which handles configuration deployment to your robots in production.
-    
+
     formats:
       - deb
 
@@ -126,12 +126,11 @@ release:
     ## Miru Agent {{.Tag}}
 
     **Full Changelog**: https://github.com/mirurobotics/agent/compare/{{ .PreviousTag }}...{{ .Tag }}
-    
+
 
     For documentation, visit: https://docs.mirurobotics.com
 
 source:
   enabled: false
 
 report_sizes: true
-

scripts/install/install.sh

@@ -3,11 +3,12 @@ set -e
 
 # Script: install.sh
 # Jinja Template: install.j2
-# Build Timestamp: 2026-05-09T19:53:58.827613
+# Build Timestamp: 2026-06-03T19:14:13.912548
 # Description: Install the Miru Agent
 
 # DISPLAY #
 # ======= #
+# shellcheck shell=sh
 RED='\033[0;31m'
 GREEN='\033[0;32m'
 YELLOW='\033[1;33m'
@@ -16,7 +17,9 @@ NO_COLOR='\033[0m'
 
 debug() { echo "${BLUE}==>${NO_COLOR} $1"; }
 log() { echo "${GREEN}==>${NO_COLOR} $1"; }
+# shellcheck disable=SC2317,SC2329 # part of the shared logging API; not every script calls every helper
 warn() { echo "${YELLOW}Warning:${NO_COLOR} $1"; }
+# shellcheck disable=SC2317,SC2329 # part of the shared logging API; not every script calls every helper
 error() { echo "${RED}Error:${NO_COLOR} $1"; }
 fatal() { echo "${RED}Error:${NO_COLOR} $1"; exit 1; }
 
@@ -102,6 +105,7 @@ for cmd in curl grep cut jq; do
 done
 
 
+# shellcheck shell=sh
 verify_checksum() {
     file=$1
     expected_checksum=$2
@@ -152,6 +156,7 @@ esac
 
 # USE PROVIDED PACKAGE #
 # -------------------- #
+# shellcheck shell=sh
 if [ -n "$FROM_PKG" ]; then
     log "Installing from package on local machine: '$FROM_PKG'"
     if [ ! -f "$FROM_PKG" ]; then
@@ -166,13 +171,16 @@ if [ -n "$FROM_PKG" ]; then
     if [ "$(dpkg -f "$FROM_PKG" Architecture)" != "$DEB_ARCH" ]; then
         fatal "The provided package architecture ($(dpkg -f "$FROM_PKG" Architecture)) does not match this machine's architecture ($DEB_ARCH)."
     fi
+    # shellcheck disable=SC2034 # consumed by a later partial in the rendered script
     AGENT_DEB_PKG=$FROM_PKG
 
+    # shellcheck disable=SC2034 # consumed by a later partial in the rendered script
     VERSION=$(dpkg -f "$FROM_PKG" Version)
 fi
 
 # DETERMINE THE VERSION #
 # --------------------- #
+# shellcheck shell=sh
 if [ -z "$VERSION" ]; then
     if [ "$PRERELEASE" = true ]; then
         log "Fetching latest pre-release version..."
@@ -208,9 +216,11 @@ fi
 
 # DOWNLOAD THE AGENT #
 # ------------------ #
+# shellcheck shell=sh
 INSTALLED_VERSION=$(dpkg-query -W -f='${Version}' "$AGENT_DEB_PKG_NAME" 2>/dev/null || echo "")
-# replace '~' with '-' 
+# replace '~' with '-'
 if [ -n "$INSTALLED_VERSION" ]; then
+    # shellcheck disable=SC2001 # POSIX sh lacks ${var//search/replace}; sed is required
     INSTALLED_VERSION=$(echo "$INSTALLED_VERSION" | sed 's/~/-/g')
 fi
 
@@ -254,14 +264,16 @@ fi
 
 # ACTIVATE THE AGENT #
 # ------------------ #
+# shellcheck shell=sh
+# shellcheck disable=SC2317,SC2329 # cleanup() is invoked indirectly via trap
 cleanup() {
     exit_code=$?
 
     # restart the agent
     log "Restarting the Miru Agent"
     sudo systemctl restart miru >/dev/null 2>&1
 
-    exit $exit_code
+    exit "$exit_code"
 }
 
 trap cleanup EXIT INT TERM QUIT HUP
@@ -288,5 +300,6 @@ fi
 sudo chown -R miru:miru /srv/miru
 
 # Execute the installer
+# shellcheck disable=SC2086 # word-splitting of the argument list is intentional
 sudo -u miru -E env MIRU_ACTIVATION_TOKEN="$MIRU_ACTIVATION_TOKEN" /usr/sbin/miru-agent --install $args
 exit 0

scripts/install/provision.sh

@@ -3,11 +3,12 @@ set -e
 
 # Script: provision.sh
 # Jinja Template: provision.j2
-# Build Timestamp: 2026-05-09T19:53:58.827613
+# Build Timestamp: 2026-06-03T19:14:13.912548
 # Description: Provision a device & install the Miru Agent
 
 # DISPLAY #
 # ======= #
+# shellcheck shell=sh
 RED='\033[0;31m'
 GREEN='\033[0;32m'
 YELLOW='\033[1;33m'
@@ -16,7 +17,9 @@ NO_COLOR='\033[0m'
 
 debug() { echo "${BLUE}==>${NO_COLOR} $1"; }
 log() { echo "${GREEN}==>${NO_COLOR} $1"; }
+# shellcheck disable=SC2317,SC2329 # part of the shared logging API; not every script calls every helper
 warn() { echo "${YELLOW}Warning:${NO_COLOR} $1"; }
+# shellcheck disable=SC2317,SC2329 # part of the shared logging API; not every script calls every helper
 error() { echo "${RED}Error:${NO_COLOR} $1"; }
 fatal() { echo "${RED}Error:${NO_COLOR} $1"; exit 1; }
 
@@ -116,6 +119,7 @@ for cmd in curl grep cut jq; do
 done
 
 
+# shellcheck shell=sh
 verify_checksum() {
     file=$1
     expected_checksum=$2
@@ -166,6 +170,7 @@ esac
 
 # USE PROVIDED PACKAGE #
 # -------------------- #
+# shellcheck shell=sh
 if [ -n "$FROM_PKG" ]; then
     log "Installing from package on local machine: '$FROM_PKG'"
     if [ ! -f "$FROM_PKG" ]; then
@@ -180,18 +185,22 @@ if [ -n "$FROM_PKG" ]; then
     if [ "$(dpkg -f "$FROM_PKG" Architecture)" != "$DEB_ARCH" ]; then
         fatal "The provided package architecture ($(dpkg -f "$FROM_PKG" Architecture)) does not match this machine's architecture ($DEB_ARCH)."
     fi
+    # shellcheck disable=SC2034 # consumed by a later partial in the rendered script
     AGENT_DEB_PKG=$FROM_PKG
 
+    # shellcheck disable=SC2034 # consumed by a later partial in the rendered script
     VERSION=$(dpkg -f "$FROM_PKG" Version)
 fi
 
 # PROVISION THE DEVICE #
 # --------------------- #
+# shellcheck shell=sh
 if [ -z "$MIRU_API_KEY" ]; then
     echo "MIRU_API_KEY is not set"
     exit 1
 fi
 
+# shellcheck disable=SC2153 # DEVICE_NAME is an external environment variable
 response_body=$(curl --request POST \
   --url "$BACKEND_HOST"/v1/devices \
   --header 'Content-Type: application/json' \
@@ -261,6 +270,7 @@ response_body=$(echo "$response_body" | head -n -1)
 # Check if the request succeeded
 if [ "$http_code" -eq 200 ] || [ "$http_code" -eq 201 ]; then
     log "Successfully created activation token"
+    # shellcheck disable=SC2034 # consumed by a later partial in the rendered script
     MIRU_ACTIVATION_TOKEN=$(echo "$response_body" | jq -r '.token')
 else
     error "Activation token request failed (HTTP status $http_code)"
@@ -270,6 +280,7 @@ fi
 
 # DETERMINE THE VERSION #
 # --------------------- #
+# shellcheck shell=sh
 if [ -z "$VERSION" ]; then
     if [ "$PRERELEASE" = true ]; then
         log "Fetching latest pre-release version..."
@@ -305,9 +316,11 @@ fi
 
 # DOWNLOAD THE AGENT #
 # ------------------ #
+# shellcheck shell=sh
 INSTALLED_VERSION=$(dpkg-query -W -f='${Version}' "$AGENT_DEB_PKG_NAME" 2>/dev/null || echo "")
-# replace '~' with '-' 
+# replace '~' with '-'
 if [ -n "$INSTALLED_VERSION" ]; then
+    # shellcheck disable=SC2001 # POSIX sh lacks ${var//search/replace}; sed is required
     INSTALLED_VERSION=$(echo "$INSTALLED_VERSION" | sed 's/~/-/g')
 fi
 
@@ -351,14 +364,16 @@ fi
 
 # ACTIVATE THE AGENT #
 # ------------------ #
+# shellcheck shell=sh
+# shellcheck disable=SC2317,SC2329 # cleanup() is invoked indirectly via trap
 cleanup() {
     exit_code=$?
 
     # restart the agent
     log "Restarting the Miru Agent"
     sudo systemctl restart miru >/dev/null 2>&1
 
-    exit $exit_code
+    exit "$exit_code"
 }
 
 trap cleanup EXIT INT TERM QUIT HUP
@@ -385,5 +400,6 @@ fi
 sudo chown -R miru:miru /srv/miru
 
 # Execute the installer
+# shellcheck disable=SC2086 # word-splitting of the argument list is intentional
 sudo -u miru -E env MIRU_ACTIVATION_TOKEN="$MIRU_ACTIVATION_TOKEN" /usr/sbin/miru-agent --install $args
 exit 0

scripts/install/staging-install.sh

@@ -3,11 +3,12 @@ set -e
 
 # Script: staging-install.sh
 # Jinja Template: install.j2
-# Build Timestamp: 2026-05-09T19:53:58.827613
+# Build Timestamp: 2026-06-03T19:14:13.912548
 # Description: Install the Miru Agent in the staging environment
 
 # DISPLAY #
 # ======= #
+# shellcheck shell=sh
 RED='\033[0;31m'
 GREEN='\033[0;32m'
 YELLOW='\033[1;33m'
@@ -16,7 +17,9 @@ NO_COLOR='\033[0m'
 
 debug() { echo "${BLUE}==>${NO_COLOR} $1"; }
 log() { echo "${GREEN}==>${NO_COLOR} $1"; }
+# shellcheck disable=SC2317,SC2329 # part of the shared logging API; not every script calls every helper
 warn() { echo "${YELLOW}Warning:${NO_COLOR} $1"; }
+# shellcheck disable=SC2317,SC2329 # part of the shared logging API; not every script calls every helper
 error() { echo "${RED}Error:${NO_COLOR} $1"; }
 fatal() { echo "${RED}Error:${NO_COLOR} $1"; exit 1; }
 
@@ -102,6 +105,7 @@ for cmd in curl grep cut jq; do
 done
 
 
+# shellcheck shell=sh
 verify_checksum() {
     file=$1
     expected_checksum=$2
@@ -152,6 +156,7 @@ esac
 
 # USE PROVIDED PACKAGE #
 # -------------------- #
+# shellcheck shell=sh
 if [ -n "$FROM_PKG" ]; then
     log "Installing from package on local machine: '$FROM_PKG'"
     if [ ! -f "$FROM_PKG" ]; then
@@ -166,13 +171,16 @@ if [ -n "$FROM_PKG" ]; then
     if [ "$(dpkg -f "$FROM_PKG" Architecture)" != "$DEB_ARCH" ]; then
         fatal "The provided package architecture ($(dpkg -f "$FROM_PKG" Architecture)) does not match this machine's architecture ($DEB_ARCH)."
     fi
+    # shellcheck disable=SC2034 # consumed by a later partial in the rendered script
     AGENT_DEB_PKG=$FROM_PKG
 
+    # shellcheck disable=SC2034 # consumed by a later partial in the rendered script
     VERSION=$(dpkg -f "$FROM_PKG" Version)
 fi
 
 # DETERMINE THE VERSION #
 # --------------------- #
+# shellcheck shell=sh
 if [ -z "$VERSION" ]; then
     if [ "$PRERELEASE" = true ]; then
         log "Fetching latest pre-release version..."
@@ -208,9 +216,11 @@ fi
 
 # DOWNLOAD THE AGENT #
 # ------------------ #
+# shellcheck shell=sh
 INSTALLED_VERSION=$(dpkg-query -W -f='${Version}' "$AGENT_DEB_PKG_NAME" 2>/dev/null || echo "")
-# replace '~' with '-' 
+# replace '~' with '-'
 if [ -n "$INSTALLED_VERSION" ]; then
+    # shellcheck disable=SC2001 # POSIX sh lacks ${var//search/replace}; sed is required
     INSTALLED_VERSION=$(echo "$INSTALLED_VERSION" | sed 's/~/-/g')
 fi
 
@@ -254,14 +264,16 @@ fi
 
 # ACTIVATE THE AGENT #
 # ------------------ #
+# shellcheck shell=sh
+# shellcheck disable=SC2317,SC2329 # cleanup() is invoked indirectly via trap
 cleanup() {
     exit_code=$?
 
     # restart the agent
     log "Restarting the Miru Agent"
     sudo systemctl restart miru >/dev/null 2>&1
 
-    exit $exit_code
+    exit "$exit_code"
 }
 
 trap cleanup EXIT INT TERM QUIT HUP
@@ -288,5 +300,6 @@ fi
 sudo chown -R miru:miru /srv/miru
 
 # Execute the installer
+# shellcheck disable=SC2086 # word-splitting of the argument list is intentional
 sudo -u miru -E env MIRU_ACTIVATION_TOKEN="$MIRU_ACTIVATION_TOKEN" /usr/sbin/miru-agent --install $args
 exit 0