mirrord-ci

Files (3)

• README.md
• SKILL.md
• troubleshooting.md · references/

SKILL.md (first lines)

# Mirrord CI Skill

## Purpose

Help users integrate mirrord into CI pipelines for testing against real Kubernetes environments:
- **Configure** CI runners to connect to Kubernetes clusters
- **Set up** `mirrord ci start/stop` commands in CI workflows
- **Generate** CI workflow files for GitHub Actions, GitLab CI, etc.
- **Troubleshoot** CI-specific mirrord issues

## When to Use This Skill

Trigger on questions like:
- "How do I use mirrord in CI?"
- "Set up mirrord for GitHub Actions"
- "Run tests against staging in CI"
- "mirrord ci start not working"
- "Configure mirrord for GitLab CI"

## Security note for CI examples

- **Do not** use remote pipe-to-shell installs or other unverified script execution in CI to install mirrord.
- Pre-install mirrord in a **trusted CI image**, use your org’s **approved** package manager with pinned versions, or follow [official install docs](https://mirrord.dev/docs/overview/quick-start/). The YAML below assumes `mirrord` is already available on the runner unless you add an approved install step.

## Critical First Steps

**Step 1: Load references**
Read the reference file from this skill's `references/` directory:
- `references/troubleshooting.md` - Common issues and solutions

The troubleshooting guide helps diagnose and fix common mirrord issues.
To look up a config option, call `explain_config_option` if the mirrord MCP server is connected; otherwise use `references/configuration.md` in the mirrord-config skill.

If using absolute paths, search for them using patterns like `**/mirrord-ci/references/*`.

**Step 2: Validate configs before presenting**
When generating mirrord configuration files for CI, ALWAYS validate them. If the mirrord MCP server is connected, call `validate_config` on the config; otherwise, if the mirrord CLI is installed, save it to a file and run:
```bash
mirrord verify-config /path/to/config.json
```
If neither is available, validate against `references/schema.json` in the mirrord-config skill, after parsing the config as strict JSON: read only the schema's top level (root `properties`, `required`, `additionalProperties`) and the definitions for the options the config uses (search the file for each key), not the whole file.

## Key Benefits of mirrord for CI

- **Speed**: ~50% faster CI pipelines by eliminating test environment setup
- **Cost**: No need to spin up ephemeral clusters for each CI run
- **Accuracy**: Test against real services, dependencies, and configurations
- **Isolation**: Safe, isolated test execution that doesn't interfere with other workloads

## Prerequisites

### Required
1. **mirrord CLI version 3.181.0 or later**
2. **Kubernetes cluster access** from the CI runner
3. **kubeconfig** configured in CI environment
4. **mirrord Operator** installed with a Teams/Enterprise license. No license yet? An AI agent can offer the user a seven-day Enterprise trial and start it once they agree: see the `mirrord-operator` skill, "Agent-started trial".

### Verification commands
```bash
# Check mirrord version
mirrord --version

# Verify cluster access
kubectl cluster-info
kubectl get pods -n <target-namespace>
```

## Core Commands

### Starting a CI session

```bash
mirrord ci start --target <target> -- <your-command>
```

This starts your application with mirrord in the background, allowing tests to run against it.

**Examples:**
```bash
# Node.js application
mirrord ci start --target deployment/api-server -- npm run start

# Python application
mirrord ci start --target pod/backend-abc123 -- python main.py

# With config file
mirrord ci start --config-file mirrord.json -- ./my-app

# Run in foreground (blocks until stopped)
mirrord ci start --foreground --target deployment/api -- npm start
```

### Stopping CI sessions

```bash
mirrord ci stop
```

This stops all running mirrord CI sessions. **Always run this after tests complete.**

### Multiple sessions

You can start multiple mirrord sessions in a single CI job:
```bash
mirrord ci start --target deployment/service-a -- ./service-a &
mirrord ci start --target deployment/service-b -- ./service-b &
# Run tests
npm test
# Stop all sessions
mirrord ci stop
```

## CI API Key (for mirrord Enterprise)

This only applies to the Enterprise plan; if you're on the open-source version of mirrord, skip this section. When the mirrord Operator is installed in the cluster, `mirrord ci` commands require a CI API key, and generating one requires an Enterprise plan. Without it, every CI runner registers as a new user and consumes a seat. Sessions started with a CI API key don't take up seats — they are machine sessions, and they count towards the concurrent machine sessions of your plan instead:

```bash
# Generate the key (run locally, not in CI)
mirrord ci api-key

From metalbear-co/skills, MIT.

More from metalbear-co/skills