|
| 1 | +--- |
| 2 | +description: "Deploy a project through Syncable by orchestrating authentication, project analysis, security gating, and cloud deployment using the Syncable CLI sync-ctl tool" |
| 3 | +--- |
| 4 | + |
| 5 | +## Purpose |
| 6 | + |
| 7 | +Orchestrate a full deployment pipeline through the Syncable platform: authenticate, analyze the project, run a security audit as a gate, then deploy. Ensures no deployment happens without authentication and security review. |
| 8 | + |
| 9 | +## Prerequisites |
| 10 | + |
| 11 | +- `sync-ctl` binary installed and on PATH |
| 12 | +- Internet access for Syncable API |
| 13 | +- Agent has access to the project directory |
| 14 | + |
| 15 | +## Workflow Steps |
| 16 | + |
| 17 | +### Step 1: Check authentication and platform context |
| 18 | + |
| 19 | +```bash |
| 20 | +sync-ctl auth status |
| 21 | +``` |
| 22 | + |
| 23 | +**Decision point:** If not authenticated: |
| 24 | +```bash |
| 25 | +sync-ctl auth login |
| 26 | +``` |
| 27 | + |
| 28 | +Then verify project/environment context: |
| 29 | +```bash |
| 30 | +sync-ctl project current |
| 31 | +``` |
| 32 | + |
| 33 | +**Decision point:** If no project selected: |
| 34 | +```bash |
| 35 | +sync-ctl org list |
| 36 | +# Ask user which org |
| 37 | +sync-ctl org select <ORG_ID> |
| 38 | +sync-ctl project list |
| 39 | +# Ask user which project |
| 40 | +sync-ctl project select <PROJECT_ID> |
| 41 | +sync-ctl env list |
| 42 | +# Ask user which environment |
| 43 | +sync-ctl env select <ENV_ID> |
| 44 | +``` |
| 45 | +
|
| 46 | +### Step 2: Analyze the project |
| 47 | +
|
| 48 | +```bash |
| 49 | +sync-ctl analyze <PATH> --agent |
| 50 | +``` |
| 51 | +
|
| 52 | +Save the `full_data_ref` from the analyze output — do not re-run analyze in later steps; use `sync-ctl retrieve` with this ref_id instead. |
| 53 | +
|
| 54 | +### Step 3: Pre-deploy security audit |
| 55 | +
|
| 56 | +Execute the `syncable-security-audit` workflow inline (all its steps and decision logic). **Note:** Step 2's analyze output is reused here — do not re-run analyze. |
| 57 | +
|
| 58 | +1. `sync-ctl security <PATH> --mode paranoid --agent` |
| 59 | +2. `sync-ctl vulnerabilities <PATH> --agent` |
| 60 | +3. `sync-ctl validate <PATH>` (if IaC files exist per Step 2's analysis) |
| 61 | +
|
| 62 | +**CRITICAL GATE:** Check the security output's `status` field: |
| 63 | +- If `status` is "CRITICAL_ISSUES_FOUND": present findings to user, warn, require confirmation |
| 64 | +- If `status` is "HIGH_ISSUES_FOUND": warn but allow deployment |
| 65 | +- If `status` is "CLEAN": proceed to deploy |
| 66 | +
|
| 67 | +All critical findings are in the `critical_issues` array of the compressed output — no retrieval needed for the gate decision. |
| 68 | +
|
| 69 | +### Step 4: Deploy |
| 70 | +
|
| 71 | +**4a. Get deployment recommendation:** |
| 72 | +```bash |
| 73 | +sync-ctl deploy preview <PATH> |
| 74 | +``` |
| 75 | +
|
| 76 | +This returns JSON with: provider recommendation (with reasoning), region, machine type, detected port, health check endpoint, alternatives, discovered .env files, and already-deployed service endpoints. |
| 77 | +
|
| 78 | +**4b. Present recommendation to user and confirm.** Show: |
| 79 | +- Recommended provider, region, machine type |
| 80 | +- Detected port and whether public/internal |
| 81 | +- Any .env files found — ask if they should be injected |
| 82 | +- Any service endpoints that could be referenced (e.g., `BACKEND_URL`) |
| 83 | +
|
| 84 | +**4c. Deploy with confirmed settings:** |
| 85 | +```bash |
| 86 | +sync-ctl deploy run <PATH> --provider <PROVIDER> --region <REGION> --port <PORT> |
| 87 | +``` |
| 88 | +
|
| 89 | +Add `--public` if user wants a public URL. Add `--env KEY=VALUE` for env vars and `--secret KEY` for secrets (user prompted in terminal). Add `--env-file .env` to inject from file. |
| 90 | +
|
| 91 | +**4d. Monitor:** |
| 92 | +```bash |
| 93 | +sync-ctl deploy status <TASK_ID> --watch |
| 94 | +``` |
| 95 | +
|
| 96 | +**Example with user overrides:** |
| 97 | +```bash |
| 98 | +# User said "deploy to GCP in us-central1, make it public, use the .env file" |
| 99 | +sync-ctl deploy run ./services/api \ |
| 100 | + --provider gcp --region us-central1 --port 8080 --public \ |
| 101 | + --env-file .env \ |
| 102 | + --secret "STRIPE_KEY" |
| 103 | +``` |
| 104 | +
|
| 105 | +## Decision Points Summary |
| 106 | +
|
| 107 | +| Condition | Action | |
| 108 | +|-----------|--------| |
| 109 | +| Not authenticated | Run `sync-ctl auth login` first | |
| 110 | +| No project/env selected | Guide user through selection | |
| 111 | +| Critical security findings | Warn user, require explicit confirmation to proceed | |
| 112 | +| High security findings (no critical) | Warn user but allow deployment | |
| 113 | +| Clean security audit | Proceed to deploy | |
| 114 | +
|
| 115 | +## Safety |
| 116 | +
|
| 117 | +- **Never deploy without the security gate.** Even if the user says "just deploy", run at least a fast security scan. |
| 118 | +- **Always confirm with the user before triggering deployment.** Show them what will be deployed, to which environment. |
| 119 | +- **Monitor deployment status** after triggering — don't fire-and-forget. |
| 120 | +
|
| 121 | +## Cross-Step Retrieval |
| 122 | +
|
| 123 | +Each step produces a `full_data_ref` in its output. You can retrieve details from any previous step at any time: |
| 124 | +
|
| 125 | +```bash |
| 126 | +# Check what data is available from all steps |
| 127 | +sync-ctl retrieve --list |
| 128 | + |
| 129 | +# Get framework details from Step 2 (analyze) |
| 130 | +sync-ctl retrieve <analyze_ref_id> --query "section:frameworks" |
| 131 | + |
| 132 | +# Get critical security findings from Step 3 |
| 133 | +sync-ctl retrieve <security_ref_id> --query "severity:critical" |
| 134 | + |
| 135 | +# Get vulnerability details from Step 3 |
| 136 | +sync-ctl retrieve <vuln_ref_id> --query "severity:high" |
| 137 | +``` |
| 138 | +
|
| 139 | +Do NOT re-run a command just to get more detail — use `sync-ctl retrieve` instead. |
0 commit comments