miko-setup-linear

Files (1)

• SKILL.md

SKILL.md (first lines)

**CRITICAL: Never use `Read`, `Edit`, or `Write` tools on `~/.miko/.env` or any file inside `~/.miko/`. Use only `Bash` commands (`grep`, `printf >>`, etc.) to interact with env files — secrets must never be read into the conversation context. Never scrape, extract, or read secret values from web pages — guide the user to copy them manually.**

# Setup Linear

Creates a Linear OAuth application and configures credentials so Miko can receive webhooks and respond to issues.

Use the `MIKO_ENTRY` path supplied by prerequisites for the OAuth command. If invoked independently, verify the fork launcher with `node "<launcher>" --installation`, or run prerequisites first if it is missing.

## Step 1: Check Existing Configuration

When the user asks to add **another workspace with its own private app**, do not
skip setup because an existing workspace is authorized, and do not replace the
normal `~/.miko/.env`. One instance supports multiple private apps:

- Create the new app in the requested workspace using the manifest below, with
  the existing base URL, callback URL, and webhook URL.
- Use a separate credential file, e.g. `~/.miko/linear-nexmoe.env`. Include the
  existing `MIKO_BASE_URL`, `MIKO_SERVER_PORT`, `MIKO_HOST_EXTERNAL=true`, and
  `LINEAR_DIRECT_WEBHOOKS=true`, then have the user paste the new app's three
  `LINEAR_*` values into this file. Apply mode `600`; never print its contents.
- At Step 5, wait for the worker to be idle, stop it to free the callback port,
  keep the tunnel running, and run:
  `node "<MIKO_ENTRY>" --env-file "<new-credential-file>" self-auth-linear`.
- The command stores the new app credentials in that workspace's `linearOAuth`
  entry in `config.json`, preserving other workspaces. Restart the existing
  service with its normal environment, not the new credential file.
- Check workspace names and credential presence only; never print config tokens
  or app secrets. Do not claim the new workspace is connected until OAuth saves
  the requested workspace.

```bash
grep -E '^LINEAR_CLIENT_ID=' ~/.miko/.env 2>/dev/null
```

If `LINEAR_CLIENT_ID` is already set, check if OAuth is also complete:

```bash
grep -q '"workspaces"' ~/.miko/config.json 2>/dev/null && echo "configured" || echo "not configured"
```

If both are set, inform the user:

> Linear is already configured. Skipping this step.
> To reconfigure, remove `LINEAR_CLIENT_ID`, `LINEAR_CLIENT_SECRET`, and `LINEAR_WEBHOOK_SECRET` from `~/.miko/.env` and re-run.

Skip to completion.

## Step 2: Get MIKO_BASE_URL

Read the base URL from the env file (set by `setup-endpoint`):

```bash
grep '^MIKO_BASE_URL=' ~/.miko/.env | cut -d= -f2-
```

This is needed for the callback and webhook URLs.

## Step 3: Create Linear OAuth App From Manifest

Linear OAuth apps must be created from a manifest-backed setup URL. Do not create the app from scratch or fill each field manually. The manifest flow keeps the app configuration reproducible and avoids drift in callback, webhook, and event type settings.

### 3a. Build the manifest URL

Generate a JSON OAuth app manifest and encode it into Linear's `manifest` query parameter:

```bash
MIKO_BASE_URL="<MIKO_BASE_URL>" \
AGENT_NAME="<AGENT_NAME>" \
AGENT_DESCRIPTION="<AGENT_DESCRIPTION>" \
node <<'NODE'
const fs = require("node:fs");

const baseUrl = process.env.MIKO_BASE_URL.replace(/\/+$/, "");
const agentName = process.env.AGENT_NAME || "Miko";
const agentDescription =
	process.env.AGENT_DESCRIPTION || "AI coding agent for automated development";

const manifest = {
	$schema: "https://linear.app/.well-known/oauth-app-manifest.schema.json",
	schemaVersion: "1.0.0",
	distribution: "private",
	display: {
		description: agentDescription,
	},
	developer: {
		name: "Self-hosted",
	},
	oauth: {
		client_name: agentName,
		client_uri: "https://github.com/mikoagents/miko",
		redirect_uris: [`${baseUrl}/callback`],
		grant_types: ["authorization_code"],
	},
	webhook: {
		enabled: true,
		url: `${baseUrl}/linear-webhook`,
		resourceTypes: [
			"AgentSessionEvent",
			"AppUserNotification",
			"PermissionChange",
			"Issue",
		],
	},
};

const manifestJson = JSON.stringify(manifest, null, 2);
const manifestUrl = `https://linear.app/settings/api/applications/new?manifest=${encodeURIComponent(JSON.stringify(manifest))}`;

fs.writeFileSync("/tmp/miko-linear-oauth-app-manifest.json", `${manifestJson}\n`);
fs.writeFileSync("/tmp/miko-linear-oauth-app-url.txt", `${manifestUrl}\n`);

console.log(manifestJson);
console.log(`\n${manifestUrl}`);
NODE

LINEAR_MANIFEST_URL="$(cat /tmp/miko-linear-oauth-app-url.txt)"
```

The same URL is now stored in `LINEAR_MANIFEST_URL` for automation commands and in `/tmp/miko-linear-oauth-app-url.txt` for manual copy/paste. The JSON is stored in `/tmp/miko-linear-oauth-app-manifest.json` for review/debugging only; do not ask the user to fill the OAuth app form manually from it.

From mikoagents/miko, Apache-2.0.

More from mikoagents/miko