Harden CI/CD: add security automation, concurrency control, and cross-links

- Add large file detection and Docker image size limit to CI
- Add CI gate to CD workflow via workflow_call
- Add .gitattributes for cross-platform line ending consistency
- Add AGENTS.md (AI context), SECURITY.md, dependabot.yml
- Add MCP Server to cross-link banner in READMEs

Author: heznpc

.gitattributes

@@ -0,0 +1,2 @@
+# Auto-detect text files and normalize line endings
+* text=auto eol=lf

.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+  - package-ecosystem: docker
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5

.github/workflows/cd.yml

@@ -6,12 +6,20 @@ on:
     tags:
       - 'v*'
 
+concurrency:
+  group: deploy-${{ github.ref }}
+  cancel-in-progress: false
+
 permissions:
   contents: write
   packages: write
 
 jobs:
+  ci:
+    uses: ./.github/workflows/ci.yml
+
   deploy:
+    needs: ci
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -35,13 +43,27 @@ jobs:
             exit 1
           fi
 
+      - name: Validate secrets
+        run: |
+          MISSING=""
+          if [ -z "${{ secrets.VPS_HOST }}" ]; then MISSING="$MISSING VPS_HOST"; fi
+          if [ -z "${{ secrets.VPS_USER }}" ]; then MISSING="$MISSING VPS_USER"; fi
+          if [ -z "${{ secrets.VPS_SSH_KEY }}" ]; then MISSING="$MISSING VPS_SSH_KEY"; fi
+          if [ -n "$MISSING" ]; then
+            echo "::error::Missing required secrets:$MISSING — See docs/VPS_DEPLOY.md"
+            exit 1
+          fi
+
       - name: Log in to GHCR
         uses: docker/login-action@v3
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
       - name: Build and push
         uses: docker/build-push-action@v6
         with:
@@ -50,6 +72,8 @@ jobs:
           tags: |
             ghcr.io/${{ github.repository }}:latest
             ghcr.io/${{ github.repository }}:${{ steps.version.outputs.version }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
 
       - name: Deploy to VPS via SSH
         uses: appleboy/ssh-action@v1

.github/workflows/ci.yml

@@ -5,13 +5,28 @@ on:
     branches: [main]
   pull_request:
     branches: [main]
+  workflow_call:
 
 jobs:
   ci:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
 
+      - name: Scan for secrets
+        uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Check for large files
+        run: |
+          LARGE=$(find . -not -path './.git/*' -type f -size +5M)
+          if [ -n "$LARGE" ]; then
+            echo "::error::Large files detected (>5 MB):"
+            echo "$LARGE"
+            exit 1
+          fi
+
       - name: Lint Dockerfile
         uses: hadolint/hadolint-action@v3.1.0
         with:
@@ -25,3 +40,20 @@ jobs:
 
       - name: Build Docker image
         run: docker build -t docker-deploy-starter:test .
+
+      - name: Scan image for vulnerabilities
+        uses: aquasecurity/trivy-action@0.28.0
+        with:
+          image-ref: docker-deploy-starter:test
+          exit-code: '1'
+          severity: CRITICAL,HIGH
+
+      - name: Check image size
+        run: |
+          SIZE=$(docker image inspect docker-deploy-starter:test --format='{{.Size}}')
+          SIZE_MB=$((SIZE / 1024 / 1024))
+          echo "Image size: ${SIZE_MB} MB"
+          if [ "$SIZE_MB" -gt 500 ]; then
+            echo "::error::Docker image exceeds 500 MB (${SIZE_MB} MB) — consider multi-stage build"
+            exit 1
+          fi

AGENTS.md

@@ -0,0 +1,59 @@
+# Docker Deploy Starter
+
+Language-agnostic Docker + GitHub Actions CI/CD + VPS SSH deployment starter.
+
+## Project Structure
+
+```
+app/              → Example app (replace with your own)
+Dockerfile        → Example Node.js (swap for your language, see docs/DOCKERFILE_EXAMPLES.md)
+docker-compose.yml → Local dev + VPS deployment
+.env.example      → Environment variables template
+VERSION           → Single source of truth for version (1.0.0)
+scripts/bump-version.js → Version bumping (patch/minor/major)
+docs/             → Setup guides (VPS, GHCR, HTTPS, Dockerfile examples)
+```
+
+## CI/CD Pipeline
+
+- **ci.yml**: Runs on push/PR to main. Hadolint lint + docker-compose validate + Docker build test + Trivy CVE scan (CRITICAL/HIGH). No secrets needed.
+- **cd.yml**: Manual trigger OR tag push (v*). Builds image (Buildx + GHA cache) → pushes to GHCR → deploys to VPS via SSH → cleans old images → creates GitHub Release. Concurrency controlled (no parallel deploys).
+- **setup.yml**: First push only. Auto-creates GitHub Issue with setup checklist.
+
+## Secrets (for CD)
+
+| Secret | Required | Purpose |
+|--------|----------|---------|
+| `VPS_HOST` | Yes | VPS IP or domain |
+| `VPS_USER` | Yes | SSH username |
+| `VPS_SSH_KEY` | Yes | SSH private key (full PEM content) |
+| `APP_PORT` | No | Defaults to 3000 |
+| `GITHUB_TOKEN` | Auto | Provided by GitHub Actions |
+
+## What to Modify
+
+- `app/` → Replace with your application code
+- `Dockerfile` → Swap for your language (copy from docs/DOCKERFILE_EXAMPLES.md)
+- `.env.example` → Add your app-specific environment variables
+- `docker-compose.yml` → Update ports, volumes, service name if needed
+- `VERSION` → Bump via `node scripts/bump-version.js patch|minor|major`
+
+## Do NOT Modify
+
+- `.github/workflows/ci.yml` → CI pipeline structure
+  - **Why**: Hadolint → compose validate → build → Trivy scan 순서가 의도적. 빠른 검사부터 느린 검사 순서로 fail-fast.
+- `.github/workflows/cd.yml` → Deployment pipeline
+  - **Why**: GHCR push → SSH deploy → cleanup → release 순서에 의존성이 있음. 순서 변경 시 미배포 이미지가 릴리즈되거나, 배포 전 이미지가 정리될 수 있음.
+- Version guard logic in cd.yml
+  - **Why**: 같은 버전을 두 번 배포하면 GHCR 태그 충돌 + GitHub Release 중복 생성. 이 guard가 없으면 CI 통과해도 CD에서 조용히 깨짐.
+- Health check pattern in Dockerfile and docker-compose.yml
+  - **Why**: `docker compose up -d --wait`가 health check 통과를 기다림. health check 없으면 컨테이너 시작 = 배포 성공으로 판단해서 깨진 앱이 배포될 수 있음.
+- Concurrency control in cd.yml
+  - **Why**: 동시에 두 배포가 실행되면 SSH에서 race condition 발생. `cancel-in-progress: false`로 순서대로 실행.
+
+## Customization Examples
+
+- **Change port**: Set `APP_PORT` secret in GitHub + update `EXPOSE` in Dockerfile + update `.env`
+- **Add database**: Add service to docker-compose.yml, add DB env vars to .env.example
+- **Switch to Python/Go/Rust/Java**: Copy Dockerfile from docs/DOCKERFILE_EXAMPLES.md, replace app/
+- **Add HTTPS**: Follow docs/HTTPS_SETUP.md (Caddy reverse proxy)

README.ko.md

@@ -17,6 +17,12 @@
 
 ---
 
+> **[Starter Series](https://github.com/heznpc/starter-series)** — 매번 AI한테 CI/CD 설명하지 마세요. clone하고 바로 시작하세요.
+>
+> [Docker Deploy](https://github.com/heznpc/docker-deploy-starter) · [Discord Bot](https://github.com/heznpc/discord-bot-starter) · [Telegram Bot](https://github.com/heznpc/telegram-bot-starter) · [Browser Extension](https://github.com/heznpc/browser-extension-starter) · [Electron App](https://github.com/heznpc/electron-app-starter) · [npm Package](https://github.com/heznpc/npm-package-starter) · [React Native](https://github.com/heznpc/react-native-starter) · [VS Code Extension](https://github.com/heznpc/vscode-extension-starter) · [MCP Server](https://github.com/heznpc/mcp-server-starter)
+
+---
+
 ## 빠른 시작
 
 ```bash

README.md

@@ -17,6 +17,12 @@ Build your app. Push to deploy.
 
 ---
 
+> **Part of [Starter Series](https://github.com/heznpc/starter-series)** — Stop explaining CI/CD to your AI every time. Clone and start.
+>
+> [Docker Deploy](https://github.com/heznpc/docker-deploy-starter) · [Discord Bot](https://github.com/heznpc/discord-bot-starter) · [Telegram Bot](https://github.com/heznpc/telegram-bot-starter) · [Browser Extension](https://github.com/heznpc/browser-extension-starter) · [Electron App](https://github.com/heznpc/electron-app-starter) · [npm Package](https://github.com/heznpc/npm-package-starter) · [React Native](https://github.com/heznpc/react-native-starter) · [VS Code Extension](https://github.com/heznpc/vscode-extension-starter) · [MCP Server](https://github.com/heznpc/mcp-server-starter)
+
+---
+
 ## Quick Start
 
 ```bash
@@ -63,7 +69,7 @@ docker compose up
 ## Features
 
 - **Language agnostic** — Swap the Dockerfile for any language (Node, Python, Go, Rust, Java, static)
-- **CI Pipeline** — Dockerfile lint (hadolint), docker-compose validation, build verification on every push
+- **CI Pipeline** — Dockerfile lint (hadolint), docker-compose validation, build verification, Trivy CVE scan on every push
 - **CD Pipeline** — Build → push to GHCR → health-checked deploy to VPS via docker compose + auto GitHub Release
 - **Dockerfile examples** — Multi-stage builds for Node, Python, Go, Rust, Java in docs
 - **Version management** — `node scripts/bump-version.js patch/minor/major`
@@ -81,6 +87,7 @@ docker compose up
 | Lint Dockerfile | [Hadolint](https://github.com/hadolint/hadolint) checks for best practices |
 | Validate compose | Verifies `docker-compose.yml` syntax |
 | Build test | Builds the Docker image to catch build errors |
+| Scan image | [Trivy](https://github.com/aquasecurity/trivy) scans for CRITICAL/HIGH CVEs |
 
 ### CD (manual trigger or tag push)
 

SECURITY.md

@@ -0,0 +1,27 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability, please report it responsibly:
+
+1. **Do NOT open a public issue.**
+2. Email **security@heznpc.dev** or use [GitHub Security Advisories](../../security/advisories/new).
+3. Include steps to reproduce, impact assessment, and suggested fix if possible.
+
+We will respond within 48 hours and work with you to resolve the issue.
+
+## Security Features
+
+This template includes automated security checks in CI:
+
+- **Dependency audit** — `npm audit` on every push (HIGH/CRITICAL threshold)
+- **Secret leak detection** — [gitleaks](https://github.com/gitleaks/gitleaks) scans every commit
+- **Dependency updates** — [Dependabot](https://docs.github.com/en/code-security/dependabot) monitors for vulnerable dependencies
+- **Dockerfile lint** — [Hadolint](https://github.com/hadolint/hadolint) enforces best practices
+- **Container scan** — [Trivy](https://github.com/aquasecurity/trivy) detects CRITICAL/HIGH CVEs in built images
+
+## Best Practices
+
+- Never commit `.env` files or secrets — they are gitignored by default
+- Use GitHub Secrets for deployment credentials
+- Keep dependencies up to date by merging Dependabot PRs