agentleFS
Sign inStart free
Marid5Marid5/ai-tutor/.claude/skills/deploy/SKILL.md

deploy

Skill1 starsChanged 25 days agoMITView on GitHub

Ships the main branch of AI Tutor to the user's server through CI and the deploy workflow, then verifies the running commit and the security checks. Use when the user asks to deploy, release or ship a change, or to check that a deploy worked.

  • Reads credentials
  • Commits and pushes

We split this skill into the rules it gives an agent

10 rules. 0 are common, 5 are distinctive, and 5 are very specific to this project.

  • 0

    Common

    Most of the 137 edited versions we read keep these.

  • 5

    Distinctive

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If frontend/ changed: npm --prefix frontend run typecheck and npm --prefix frontend test pass.

    line 16
  2. Distinctive:

    Do not push red. CI runs the same checks and the deploy would not start anyway.

    line 18
  3. Very specific:

    Run all four checks after every deploy and report each result.

    line 30
  4. Distinctive:

    The app port is closed from outside: Run it from your machine, not from the server:

    line 38
  5. Very specific:

    No line contains 0.0.0.0: or [::]:, except the proxy's own ports 80 and 443 when Caddy runs in a container.

    line 52
  6. Distinctive:

    If check 2, 3 or 4 fails, treat it as a security incident: tell the user at once and stop deploying until it is fixed.

    line 54
  7. Distinctive:

    Never edit files on the server by hand: the next deploy resets the checkout.

    line 64
  8. Very specific:

    Never publish the app port without 127.0.0.1: (or the bridge address in docker-compose.edge.yml).

    line 65
  9. Very specific:

    Never put secrets, .env or keys into the repository or the workflow logs.

    line 66
  10. Distinctive:

    Never skip the checks in step 3 because the workflow is green.

    line 67

“Common” is measured: kept by at least 6 in 10 of the 137 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Deploy

A push to main runs CI (.github/workflows/ci.yml). When CI passes, .github/workflows/deploy.yml connects to the server over SSH with a key that can only run deploy/remote-deploy.sh. That script fetches origin/main, resets the checkout to it, backs up the database if the app is running, rebuilds and restarts the container, and waits up to 60 seconds for /api/health to report the new commit. Background and troubleshooting: docs/deploy.md. Server details: deploy/setup-server.md.

You need: a server prepared with deploy/setup-server.md (otherwise use the setup-server skill), the repository secrets DEPLOY_HOST, DEPLOY_SSH_KEY and DEPLOY_KNOWN_HOSTS, the domain, and the server's public IP address. Ask the user for the domain and the address if you do not know them.

1. Check before pushing

  1. git status --short is clean and the branch is main (or the change is merged into main through a pull request).
  2. make validate, make test and make lint pass.
  3. If frontend/ changed: npm --prefix frontend run typecheck and npm --prefix frontend test pass.

Do not push red. CI runs the same checks and the deploy would not start anyway.

2. Push and follow the workflows

  1. git push origin main; if the change was merged through a pull request, skip the push. Never force-push main.
  2. Find the CI run for the commit and wait for it: gh run list --workflow CI --commit "$(git rev-parse origin/main)" --limit 1, then gh run watch <run-id> --exit-status.
  3. Then the deploy: gh run list --workflow Deploy --commit "$(git rev-parse origin/main)" --limit 1, then gh run watch <run-id> --exit-status.
    • A green run whose log says "Deployment is not configured" deployed nothing: the secrets are missing (see deploy/setup-server.md, step 9).
    • On failure, read gh run view <run-id> --log-failed. A health-check failure prints the last 50 lines of the app's log.

3. Verify the deploy

Run all four checks after every deploy and report each result. Replace tutor.example.com and 203.0.113.10 with the user's domain and server address.

  1. The new commit is serving, through the domain.
    curl -fsS https://tutor.example.com/api/health
git rev-parse origin/main
    status is ok and git_sha equals the commit. For content changes, program_version must equal the local value: .venv/bin/python -c "from app.content import load_program; print(load_program('content').program_version)".
  2. The app port is closed from outside. Run it from your machine, not from the server:
    curl -m 5 http://203.0.113.10:8000/ ; echo "exit code: $?"
    It must fail (timeout or connection refused, non-zero exit code).
  3. File serving does not leave the app's directory. A harmless traversal probe:
    curl -s --path-as-is https://tutor.example.com/%2e%2e/VERSION | head -c 200
    The answer must be the app's HTML start page, never the bare version string from VERSION.
  4. Nothing is published on every interface. On the server (needs the user's own SSH login; the CI key cannot open a shell):
    docker ps --format '{{.Names}}\t{{.Ports}}'
    No line contains 0.0.0.0: or [::]:, except the proxy's own ports 80 and 443 when Caddy runs in a container.

If check 2, 3 or 4 fails, treat it as a security incident: tell the user at once and stop deploying until it is fixed.

When a deploy fails

  • Health check failed: the new commit did not report healthy within 60 seconds. Read the log in the workflow output, fix forward with a new commit, or revert: git revert <sha> and git push origin main, which deploys the previous state.
  • Data looks wrong after the deploy: every deploy over a running app first writes a backup to /srv/ai-tutor/data/backups/. Restoring one replaces the live database, so give the user the steps and let them run them: in /srv/ai-tutor, docker compose stop app; move data/ai_tutor.db, data/ai_tutor.db-wal and data/ai_tutor.db-shm aside; copy the chosen backup to data/ai_tutor.db with owner 10001 and mode 600; docker compose up -d.
  • Manual deploy: on the server, sudo -u deploy /srv/ai-tutor/deploy/remote-deploy.sh does exactly what the workflow does.

Never

  • Never edit files on the server by hand: the next deploy resets the checkout. Change the repository instead.
  • Never publish the app port without 127.0.0.1: (or the bridge address in docker-compose.edge.yml).
  • Never put secrets, .env or keys into the repository or the workflow logs.
  • Never skip the checks in step 3 because the workflow is green.

Download now (ZIP)

  • Other versions153 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 153

    1. ok-oldking/ok-wuthering-waves★ 8.4ksame name
    2. memovai/mimiclaw★ 5.8ksame name
    3. microsoft/agent-skills★ 3.2ksame name
    4. microsoft/skills★ 3.2ksame name
    5. jhd3197/ServerKit★ 1.8ksame name
    6. microsoft/azure-skills★ 1.6ksame name
    7. pedrohcgs/claude-code-my-workflow★ 1.6ksame name
    8. mattmireles/gemma-tuner-multimodal★ 1.5ksame name
    9. microsoft/power-platform-skills★ 1.1ksame name
    10. jazzyalex/agent-sessions★ 930same name

    143 more not listed

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • Used alongsideProjects with it also use pm-discovery, qa-phase and 10 more.

    Other files people use alongside this one.

    Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
    • ww-w-aiSkill

      pm-discovery

      PM Agent Team - Automated product discovery, strategy, and PRD generation. Runs PM analysis workflow to produce comprehensive PRD before PDCA Plan phase.

      Also in 3 projects that use this

    • ww-w-aiSkill

      qa-phase

      Run QA tests at various levels (L1-L5) for features under PDCA management. Integrates with MCP tools to execute structured test plans.

      Also in 3 projects that use this

    • +10 more from ww-w-ai
  • In this repository5 other files it gives its agents.

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free