miko-setup-github

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.**

# Setup GitHub

Configures GitHub so Miko can create branches, commits, and pull requests. Optionally creates a GitHub App so Miko can receive and respond to @mentions in PR comments and reviews, automate rebases and merges, and auto-fix based on CI failures (coming soon).

**Credential preference:** When a GitHub App is configured (`GITHUB_APP_ID` + `~/.miko/github-app.pem`), Miko mints installation tokens for known installs, populates `~/.miko/github-tokens.json`, and uses those tokens for `git fetch`/`push` and `gh` (PR create). Push/PR authorship then appears as **that App's bot** (`<slug>[bot]`). The App name/slug/id is **operator-defined** — not hard-coded to a product bot. If no App is present or minting fails, Miko falls back to local `git` config + `gh auth` (Linear-only setups do not need an App).

**Always** add this commit trailer (once per commit; preserve other co-authors; do not change `git user.name`/`user.email` to impersonate mikoagent):

```text
Co-authored-by: mikoagent <332957360+mikoagent@users.noreply.github.com>
```

---

## Part A: GitHub CLI + Git Config (Outbound)

### Step 1: Check Existing Configuration

Check if `gh` is already authenticated:

```bash
gh auth status 2>&1
```

If authenticated, check git config:

```bash
git config --global user.name
git config --global user.email
```

If both `gh` auth and git config are set, inform the user:

> GitHub is already configured. Skipping to webhook setup.

Skip to Part B.

### Step 2: Authenticate GitHub CLI

If `gh` is not authenticated:

```bash
gh auth login
```

This opens an interactive browser flow. Let the user complete it.

After completion, verify:

```bash
gh auth status
```

### Step 3: Configure Git Identity

If git user name or email are not set, ask the user for their preferred values:

> **What name should appear on commits made by Miko?**
> (e.g., your name, or "Miko Bot")

> **What email should appear on commits?**
> (e.g., your email, or a noreply address)

Then set them:

```bash
git config --global user.name "<name>"
git config --global user.email "<email>"
```

### Step 4: Verify

```bash
gh auth status
git config --global user.name
git config --global user.email
```

---

## Part B: GitHub App + Webhooks (Inbound — Optional)

Ask the user:

> **Do you want Miko to respond to GitHub @mentions in Issue/PR comments and reviews?**
>
> - **Yes — enable @mentions**: Creates a GitHub App so Miko can receive Issue/PR comments and reviews via webhooks, respond when @mentioned, and act on "changes requested" reviews.
> - **No — PRs only**: Miko will create branches, commits, and PRs but won't respond to comments.

If **No** → skip to Completion.

### Step 5: Check Existing Webhook Config

```bash
grep -c '^GITHUB_WEBHOOK_SECRET=.' ~/.miko/.env 2>/dev/null
grep -c '^GITHUB_APP_ID=.' ~/.miko/.env 2>/dev/null
grep -c '^GITHUB_APP_INSTALLATION_ID=.' ~/.miko/.env 2>/dev/null
test -f ~/.miko/github-app.pem && echo "PEM exists" || echo "PEM missing"
```

If all four checks pass (1, 1, 1, "PEM exists"), skip to Completion — webhooks are already configured.

### Step 6: Collect Inputs

Read the webhook base URL:

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

If `MIKO_BASE_URL` is not set, stop and tell the user to run the endpoint setup step first.

Use the `AGENT_NAME` value from the orchestrator (set in Step 0 of `/miko-setup`). If not available, ask:

> **What should the GitHub App be named?** (e.g., "Miko", "My Code Agent")

**Important — GitHub @mention autocomplete quirk:** GitHub's autocomplete in PR comments only suggests real GitHub *user accounts*, not App bots. This means `@your-bot` won't appear in the autocomplete dropdown unless a GitHub user with that exact name exists. The mention still *works* if typed manually, but for the best experience:

From mikoagents/miko, Apache-2.0.

More from mikoagents/miko