@awesomate/hosting-mcp/skill/awesomate-github/SKILL.md

Awesomate MCP server — lets Claude manage your Awesomate WordPress hosting, plan, limits, n8n automations, and build Node/static apps + databases

---
name: awesomate-github
description: Set up GitHub version control for the user's app with zero Git knowledge required — connect their GitHub once, then create the repo, .gitignore, first commit and push-to-deploy for them. Use when the user says "connect GitHub", "back up my app", "save my work", "set up version control", "put this on GitHub", or after building an app when it should be version-controlled — and proactively: run its vc-healthcheck at session start and before deploys to keep commits/pushes/deploys healthy for users who do not know Git. Companion to awesomate-app-builder.
---

# Awesomate GitHub — version control for people who don't know Git

Assume the user knows **nothing** about Git or GitHub. Never make them run raw
git commands or understand branches/remotes. You drive everything through the
`gh` CLI and the bundled script; you ask only simple, plain questions.

## 0. First run

1. **Is `gh` installed?** Run `gh --version`. If missing, give the one-line
   install for their OS and stop until it's there:
   - macOS: `brew install gh`
   - Debian/Ubuntu: `sudo apt install gh` (or https://cli.github.com)
   - Windows: `winget install --id GitHub.cli`
2. **Are they connected to GitHub?** Run `gh auth status`. If not:
   - Say plainly: *"I'll connect you to GitHub — I'll show a link and a short
     code. Open the link, paste the code, and click approve. No password, no
     tokens to copy."*
   - Have them run `gh auth login` (choose GitHub.com → HTTPS → "Login with a
     web browser"). It prints a one-time code + opens the device-flow page.
     Wait for them to finish, then re-check `gh auth status`.
   - Never ask them for a token or paste one yourself.

## 1. Set up a project (the whole thing, via one script)

Once `gh auth status` is good, run the scaffolder from the project folder:

```
node ~/.claude/skills/awesomate-github/scripts/github-setup.mjs <repo-name> [--public]
```

It does, in order (all idempotent — safe to re-run):
1. **Secret guard** — refuses if a `.env` or an obvious secret (key/token
   shapes) is about to be tracked. Fix that first (use the
   awesomate-credentials skill) — never commit secrets.
2. Ensures `.gitignore` exists and excludes `.env` (creates/appends if needed).
3. `git init` (if needed), stages everything, makes the first commit.
4. `gh repo create <name> --private --source=. --push` (private by default;
   `--public` to override). Personal accounts work — no org needed.
5. Prints the repo URL.

Ask only: **"What should we call this project?"** (repo name) and, if relevant,
**"Keep it private?"** (default yes). Derive a sensible kebab-case repo name
from what they tell you.

**The script's first push goes to `main`.** It runs `git init -b main` and
pushes the current branch, so on a fresh repo `main` — the PRODUCTION branch
for Node apps — is what gets created. That's fine for a repo that's just a
backup, but if the code isn't ready to be live, say so before running it, or
create and check out `dev` first. There is **no `dev` branch until you make
one**: `git push origin dev` on a fresh repo fails. Create it, then push:

```
git checkout -b dev
git push -u origin dev
```

## 2. Push-to-deploy (Node apps on Awesomate)

Node apps deploy on a push to `dev` / `staging` / `main` (dev → dev, main →
prod). GitHub Actions builds on its own runner and ships only the built
files to the account; **nothing builds on the hosting account**, and neither
should you over SSH. Once wired, explain it as *"save your work = it goes
live"*; don't lecture on branches.

**Wiring it is one command, run from the repo folder, and needs no ticket:**

```
node ~/.claude/skills/awesomate-github/scripts/deploy-key.mjs <appId>
```

It generates a key **for this app only**, authorises it on the user's own
hosting account through the hub (Support Plus and above), sets
`SSH_PRIVATE_KEY`, `SSH_HOST` and `SSH_USER` on the repo with `gh secret set`,
shreds the private key locally, and tells the hub which repo the app deploys
from. Re-running it is safe; `--rotate` replaces the key. `<appId>` comes from
`awesomate_app_list` / `awesomate_app_get`.

The repo also needs the Awesomate plumbing: a scaffolded app already has it;
an existing repo (Replit, Lovable, anything) gets it from
`awesomate_app_scaffold` with `mode: 'adopt'` after the repo check. The full
order for an existing repo lives in the app-builder skill's
`references/migrate-from-replit.md`, and `awesomate_app_migration_plan` tells
you which step is next.

**When a deploy run goes red**, read the failing step (`gh run view
--log-failed`), report it with `awesomate_app_deploy_event`, fix the cause,
and push again. Three failures on one environment inside a day make the hub
open a support ticket itself and show it in the plan; tell the user
"Awesomate has been notified" and keep working. Do not raise that ticket
yourself and do not loop on pushes.

Static sites have no deploy workflow at all: the template is just the page
files, so pushing does not publish them. They are copied to the site's
document root over the account SSH (awesomate-hosting `ssh-connect.sh`).

## 3. Everyday use (plain language)

- "Save my work" → stage, commit with a short message you write for them, push.
- "Put it live" → push to the right branch (dev/staging/main) and tell them the
  URL. If the branch doesn't exist yet, create it (`git checkout -b <name>`)
  before pushing — only `main` exists after first-time setup.
- Always write clear commit messages **for** them; don't ask them to.

## 4. Be the version-control guardian (proactive, not reactive)

The user is ~99% likely to have no idea what a repo is. YOU own their version
control — they should never have to think about it:

- **Health check at session start.** Before touching an app folder, run:
  ```
  node ~/.claude/skills/awesomate-github/scripts/vc-healthcheck.mjs <project-dir>
  ```
  It prints JSON (`problems[]`: `no_repo`, `no_remote`, `uncommitted_changes`,
  `unpushed_commits`, `env_file_tracked`, `last_deploy_failed`, …). Fix what
  you can silently (commit + push loose work with a message you write); for
  `no_repo`/`no_remote`, offer setup (§1) in plain words: *"your last changes
  aren't backed up anywhere — want me to set that up? Takes a minute."*
  `env_file_tracked` is urgent: untrack it, .gitignore it, and route the
  secrets through awesomate-credentials.
  **`last_deploy_failed`:** first check the three deploy secrets exist
  (`gh secret list`). If they are missing, run `deploy-key.mjs <appId>` (§2);
  that is the fix, not a ticket. If they exist, read the failing step with
  `gh run view --log-failed`, report it with `awesomate_app_deploy_event`,
  fix the cause and push once. A "Killed" or exit 137 inside a step that runs
  on the account means memory: the build must move to the runner (it does by
  default; check `.awesomate.json` deploy.build is not being run over SSH).
- **Auto-checkpoint.** After every meaningful working change (feature works,
  bug fixed, content updated), commit with a plain-English message — don't
  wait for "save my work", and never ask them to write a message. Push at
  natural pauses so their backup is never behind.
- **Health check before every deploy/publish.** Re-run the script; never push
  to a deploy branch with a failing prior run you haven't explained.
- **Report in their language.** "Your work is backed up" / "your last 3
  changes were never saved — I've saved them now" — never "you're 2 commits
  ahead of origin/main".

## Hard rules
- Never commit a secret or a `.env`. The script's secret guard is a backstop,
  not a licence to skip checking. The script's `.gitignore` list — `.env`,
  `.env.local`, `.awesomate/`, `*.log`, `.DS_Store`, `node_modules/` — is only
  applied when the script has been run in that project, so on a repo somebody
  else set up, read `.gitignore` before committing rather than assuming.
  `.awesomate/` matters especially: the credentials skill's file-drop fallback
  puts a live secret there. If you spot a secret, route it through the
  awesomate-credentials skill instead.
- Never ask the user for a GitHub token or password; the device-flow is the
  only auth path.
- Default repos to **private**.