Orbit
Distribuzione del Tuo Progetto
Once a repository is connected, Orbit deploys on every push to your production branch: it clones the commit, installs dependencies, runs your build, packages the output and starts serving it. This…
Una volta collegato un repository, Orbit esegue il deploy a ogni push nel tuo ramo di produzione: clona il commit, installa le dipendenze, esegue il build, pacchettizza l'output e inizia a servire il contenuto. Questa guida illustra il ciclo di deploy completo, come attivarne uno manualmente e i controlli che decidono quando un deploy può andare in produzione.
Come funzionano i deploy automatici
Ogni push al ramo impostato come Production branch in Settings, quindi Git, attiva un deploy. Orbit:
- Riceve l'evento push da GitHub, GitLab o Bitbucket.
- Accoda un deployment e gli assegna uno slot di build.
- Clona il tuo repository a quel commit esatto.
- Ripristina la cache di
node_modulesse la build cache è disponibile sul tuo piano. - Esegue il comando di installazione (
npm ci,yarn installopnpm install, rilevato dal tuo lockfile). - Esegue il comando di build.
- Pacchettizza la directory output in un artefatto di deployment e lo carica.
- Commuta l'ambiente per servire il nuovo artefatto.
La pagina dei dettagli del deployment li mostra come Build phases denominate: Clone, Cache restore, Install, Cache save, Build, Upload, Done. La maggior parte dei progetti termina in uno o tre minuti.
Stati del deploy
| Stato | Significato |
|---|---|
| Queued | In attesa di uno slot di build. La pagina del deployment mostra la tua posizione in coda |
| Awaiting approval | Sospeso perché Require approval for production è attivo. Qualcuno deve approvarlo |
| Building | Installazione delle dipendenze ed esecuzione del comando di build |
| Deploying | Build terminato, il nuovo artefatto viene messo davanti al traffico |
| Succeeded (mostrato come Live) | Serve il traffico. Il deployment ha un badge CURRENT |
| Failed | Si è verificato un errore nella fase di build o di deploy. Apri il log per vedere dove |
| Cancelled | Interrotto prima del completamento, da te o da un push più recente nello stesso ramo |
| Rolled back | Sostituito da un rollback a una build precedente |
Monitorare un build in corso
La Overview del progetto mostra il build corrente con un log in streaming dal vivo nel pannello Latest build. Clicca Full details per aprire la pagina dei dettagli del deployment, che aggiunge una barra di avanzamento del build, un tempo rimanente stimato, la posizione in coda e la timeline del build suddivisa per fase.
Se il tuo piano consente più di un build simultaneo e sono tutti occupati, la pagina te lo comunica chiaramente: mostra quanti dei tuoi slot di build simultanei sono in uso e avvia il tuo deployment automaticamente quando uno si libera. Puoi vedere ogni build in corso su tutti i tuoi progetti in Orbit, quindi Queue.
Attivare un deploy manualmente
Ci sono quattro modi per eseguire il deploy senza effettuare un push di un nuovo commit.
Ridistribuire l'ultimo commit
- Apri il progetto.
- Apri la scheda Deployments.
- Clicca il deployment che vuoi, per aprire la sua pagina di dettagli.
- Clicca Retry build. Usa More retry options, quindi Retry with cleared cache, se sospetti una dipendenza cache stale.
Deploy now
Il pulsante Deploy now nella scheda Deployments accoda un build fresco dell'head corrente del tuo ramo di produzione.
Pianificare un deploy
Un deployment può essere pianificato per un momento futuro. Orbit crea uno snapshot del commit nel momento in cui lo pianifichi, quindi il build che viene eseguito in seguito è il codice che hai approvato, non quello che potrebbe essere arrivato nel frattempo.
Deploy Hooks
Un deploy hook è un URL segreto che accoda un build quando qualcosa gli invia una richiesta POST. Usali per ricostruire da un headless CMS, un cron job o una pipeline CI. Configurali nella scheda Hooks del progetto. Vedi Triggering Deployments Via Deploy Hooks.
Impostazioni di build
Orbit rileva impostazioni predefinite ragionevoli per la maggior parte dei progetti. Ignora qualsiasi impostazione in Settings, quindi Build settings:
| Campo | Segnaposto se vuoto | Esempi |
|---|---|---|
| Install command | npm ci (auto-detected) | npm ci, yarn install --frozen-lockfile, pnpm install |
| Build command | npm run build (auto-detected) | npm run build, next build, vite build, astro build |
| Output directory | dist (auto-detected) | dist, .next, out, build, .output |
| Root directory | / (monorepo subdirectory) | apps/web |
| Node.js version | Platform default | 18, 20, 22 |
Lascia un campo vuoto per mantenere il valore rilevato automaticamente. Dettagli completi, inclusi i valori per framework specifici e gli errori che causano il fallimento di un primo deploy, sono in Configuring Your Build Command and Output Directory.
Impostare una Root directory fa più che cambiare la directory di lavoro. I push che cambiano solo file al di fuori di quel percorso vengono saltati automaticamente, quindi un monorepo non viene ricostruito su ogni commit.
Decidere quando un deploy è consentito
Orbit ha diversi gate indipendenti. Tutti si trovano in Settings.
Deploy Locks
Usa un lock per bloccare la produzione durante un incident, una finestra di manutenzione o un code freeze.
- Apri il progetto.
- Clicca Lock deploys.
- Aggiungi un motivo opzionale.
Mentre bloccato, i deploy push-triggered sono silenziosamente saltati e un banner legge Production deploys are locked con il tuo motivo. I deploy manuali continuano a funzionare, il che è intenzionale: un lock arresta i deploy accidentali, non la correzione che stai cercando di spedire. Clicca Unlock deploys per rimuoverlo.
Richiedi approvazione per la produzione
Attiva Require approval for production sotto Deploy protection. I deploy di produzione push-triggered si mettono in pausa a Awaiting approval finché qualcuno non apre il deployment e clicca Approve o Reject. I panel deploy e i deploy hook non sono interessati.
Richiedi il successo della staging prima
Require staging success before production trattiene un deploy di produzione push-triggered finché l'ambiente di staging non ha distribuito lo stesso commit con successo. Qualcuno può comunque approvare manualmente per saltare l'attesa.
CI Required Checks
Gate deploy sulla tua CI personalizzata in CI required checks. Su GitHub, inserisci nomi di job Actions separati da virgola e tutti devono passare. Su GitLab, qualsiasi valore non vuoto attende l'intera pipeline. Un errore di CI annulla automaticamente il deploy Orbit.
Deploy Freeze Schedule
Deploy freeze schedule blocca i deploy push-triggered al di fuori delle finestre approvate: un blocco di fine settimana, un intervallo di ore consentito, o entrambi. Tutti i tempi sono UTC. I deploy manuali e i deploy hook non sono interessati.
Ogni gate sopra, tranne il deploy freeze, blocca solo i deploy push-triggered. I deploy hook e i panel deploy manuali passano direttamente. Se un URL hook viene divulgato, nessuna di queste impostazioni lo fermerà dall'accodare un build. Tratta gli URL hook come credenziali.
Saltare i build di cui non hai bisogno
- Ignored paths: pattern glob separati da virgola. Se ogni file in un push corrisponde, il build viene saltato.
*.md,docs/**arresta i commit di documentazione dal trigger dei deploy. - Branch ignore patterns: i push dai rami corrispondenti vengono saltati completamente.
dependabot/*,renovate/*è il caso comune. - Git tag deploys: esegui il deploy in produzione quando viene spinto un tag corrispondente, usando un glob come
v*.
Build Cache
Orbit memorizza nella cache node_modules tra i build sui piani Liftoff e Apex. Quando viene utilizzato un install in cache, il deployment mostra un badge Cache hit e la fase di install è notevolmente più breve. Un cold build mostra Cold build invece.
Per forzare una reinstallazione completa, apri Settings, quindi Clear build cache e conferma. Il prossimo deployment per ogni ambiente esegue un install completo da zero.
Se un build fallisce in un modo che non riesci a spiegare e il codice va bene localmente, riprova con la cache cancellata prima di iniziare a cambiare qualcosa. Un albero di dipendenza cache stale è una causa comune e molto confusa.
Quando un deploy va storto
Orbit può catturare un cattivo deploy per te piuttosto che lasciarlo live:
- Auto-rollback on failure ripristina automaticamente l'ultimo deployment sano se un deploy di produzione fallisce.
- Health check recupera un percorso che scegli dopo ogni deploy di produzione. Una risposta diversa da 2xx entro 15 secondi ripristina il deployment sano precedente.
- Smoke tests eseguono richieste GET su un massimo di 10 percorsi dopo ogni deploy riuscito e registrano successo o fallimento. Combinato con auto-rollback, un smoke test non riuscito fa il rollback del deploy.
Per annullare un deploy da solo, vedi Rolling Back a Deployment. Per capire perché un build è fallito, vedi Troubleshooting Failed Builds.