Deploying a web app from a Git repository is more than connecting a branch and clicking deploy. This guide provides a provider-neutral workflow for choosing a deployment method, defining reproducible builds, managing environment variables, creating preview environments, attaching a domain, enabling HTTPS, handling database migrations, and recovering safely when a release fails.
Overview
A Git-based deployment workflow turns repository changes into repeatable application releases. A typical pipeline checks out a commit, installs dependencies, runs tests, builds the application, packages the resulting files or image, and starts the new version. Depending on the hosting model, the process may be handled by a managed developer hosting platform, a self-hosted CI/CD runner, or infrastructure that you operate directly.
The most reliable setup separates four concerns:
- Source: the repository, branch, commit, and access permissions used for a deployment.
- Build: the runtime version, dependency installation command, test command, build command, and output directory.
- Runtime: environment variables, ports, processes, databases, queues, storage, and health checks.
- Traffic: preview URLs, production domains, DNS records, certificates, and rollback behavior.
Before choosing a provider, document what the application needs. A static frontend can often be deployed as generated files, while a backend may require a long-running process, a managed database, background workers, scheduled jobs, or private network access. Treat the deployment configuration as part of the application rather than as undocumented settings in a hosting dashboard.
Compare deployment methods
| Method | Best fit | Advantages | Trade-offs to check |
|---|---|---|---|
| Managed Git deployment | Frontends, APIs, and small teams seeking a short setup path | Repository integration, previews, certificates, and deployment history may be built in | Review runtime limits, data portability, logs, and provider-specific configuration |
| CI/CD pipeline to a host | Teams needing explicit tests, approvals, and release controls | Clear automation, auditable steps, and flexibility across hosting targets | Requires pipeline maintenance, secrets management, and reliable runners |
| Container image deployment | Applications with multiple services or consistent runtime requirements | Packages dependencies and runtime assumptions into a portable artifact | Requires image security, registry access, orchestration, and operational monitoring |
| Self-hosted deployment | Teams needing infrastructure control or private environments | Greater control over networking, storage, and deployment policy | You must maintain servers, backups, certificates, runners, and recovery procedures |
For repository and infrastructure decisions, see the guide to choosing an open-source Git hosting platform for teams. If you operate your own runners, the self-hosted CI/CD runner guide covers architecture and maintenance considerations.
What to track
Repository and build settings
Connect the repository using the narrowest access scope that supports deployments. Select the production branch deliberately, and use a protected branch or reviewed merge process for production releases. Record the commit associated with every deployment so that a successful version can be reproduced or restored.
Make the build steps explicit. A common sequence is:
- Install the declared runtime version.
- Install dependencies from the lockfile.
- Run linting, unit tests, and any required integration tests.
- Run the framework's production build command.
- Publish the generated output or create and deploy an application artifact.
Do not assume that a local build is equivalent to a hosted build. Differences in operating system, Node or Python version, native dependencies, case sensitivity, available memory, and environment variables can expose failures only after deployment. Pin or clearly document runtime versions, and keep the build command in repository configuration where practical.
Environment variables and secrets
Environment variables should vary by environment, not by developer workstation. Keep public configuration, such as a browser-visible API base URL, separate from secrets such as database credentials, signing keys, and private service tokens. Never commit production secrets to Git, place them in client-side bundles, or paste them into issue comments and logs.
Use a non-secret template in the repository so a new environment is understandable:
APP_ENV=production
PORT=8080
PUBLIC_API_BASE_URL=https://api.example.test
DATABASE_URL=<managed-by-hosting-secret-store>
SESSION_SECRET=<managed-by-hosting-secret-store>
LOG_LEVEL=info
Check whether a variable is needed at build time or only at runtime. Frontend frameworks often embed selected values into static assets during the build, which means changing the hosting dashboard value may require a new build. Backend values are commonly read when the process starts. Confirm the behavior for the framework you use rather than relying on variable names alone.
Previews, domains, and HTTPS
Preview deployments give each pull request or branch a testable URL before production traffic changes. Use previews to verify navigation, API integration, authentication redirects, responsive layouts, and database-safe test behavior. Preview environments should not automatically receive production credentials or unrestricted access to production data.
For a custom domain, first decide which hostname serves the frontend and which serves the API. Add the DNS records requested by the hosting system, then verify ownership if required. Check the final DNS targets, redirect behavior, cookie scope, allowed origins, and callback URLs for authentication providers. HTTPS certificates are generally issued only after the domain points to the expected service and verification succeeds. Test both the canonical hostname and any redirect from an alternate hostname.
Database migrations and rollback data
A code rollback does not automatically undo a database migration. Prefer backward-compatible changes: add new columns before using them, deploy code that supports both old and new shapes, backfill separately, and remove obsolete fields only after the older release is no longer needed. Test migrations against a representative database copy where permitted.
Keep database backups and restoration instructions separate from the application rollback procedure. The database migration workflow provides a useful framework for reviewing, testing, and reversing schema changes.
Operational checkpoints
- Deployment status, commit identifier, duration, and failure reason.
- Build logs and application startup logs with secrets redacted.
- Health-check response, error rate, latency, and resource consumption.
- DNS resolution, certificate validity, and domain redirect behavior.
- Dependency, image, and operating-system updates that can alter the build.
- Backup completion and the last tested restoration point.
Cadence and checkpoints
Use the following preflight checklist before the first production deployment and whenever the application changes its framework, runtime, database, or hosting target:
- Repository access is limited to the required project and deployment branch.
- The lockfile is committed and the supported runtime version is documented.
- Build, test, and start commands work from a clean checkout.
- Required environment variables are listed, classified, and supplied per environment.
- Secrets are stored in an approved secret store rather than in repository files.
- Preview deployments do not expose production data or credentials.
- The service listens on the port supplied by the hosting environment.
- Health checks test meaningful readiness, not merely process existence.
- Database migrations have an owner, a test result, and a recovery plan.
- A previous release can be identified and redeployed.
- The domain, DNS records, HTTPS certificate, redirects, and allowed origins are verified.
- Logs and alerts are available to the people responsible for the service.
Review deployment behavior after the first release, again after the first significant traffic change, and on a monthly or quarterly schedule appropriate to the application. Record build duration, failed deployment causes, rollback frequency, certificate and DNS changes, runtime upgrades, and unresolved warnings. This turns a one-time setup into a deployment record that can reveal gradual drift.
How to interpret changes
When a deployment fails, first identify which boundary failed: source retrieval, dependency installation, build, release startup, health check, database migration, or incoming traffic. Avoid changing several settings at once; preserve the failing commit and logs so the cause remains visible.
Build failure
Compare the hosted runtime with the local runtime, confirm that the lockfile is being honored, and inspect the first meaningful error rather than the final wrapper message. Check missing environment variables, native package requirements, case-sensitive import paths, generated files excluded by ignore rules, and memory or time limits. Reproduce the build from a clean checkout before retrying.
Runtime or health-check failure
Confirm that the process starts with the expected command, listens on the assigned port and interface, and can reach required services. Inspect startup logs for malformed connection strings, invalid credentials, incompatible migrations, and missing assets. A health endpoint should distinguish a process that is running from an application that is ready to serve traffic.
Domain or HTTPS failure
Check DNS resolution from outside the deployment network, remove conflicting records, and verify that the domain is attached to the intended service. Then check certificate issuance, hostname coverage, HTTP-to-HTTPS redirects, proxy settings, and application-level trusted-origin configuration. Browser errors can also result from incorrect CORS or cookie settings after the domain changes.
Rollback procedure
Stop promotion of the failing release, identify the last known-good commit or artifact, and redeploy it through the same controlled path. Confirm health checks, key user flows, background jobs, and database compatibility. If the release changed data, do not perform an automatic schema reversal without assessing data loss; use the migration recovery plan instead. For a fuller incident sequence, consult the CI/CD rollback and incident response playbook.
When to revisit
Revisit this deployment guide at least quarterly, and immediately after a hosting migration, framework upgrade, runtime change, domain move, repository permission change, or failed release. Hosting interfaces, supported runtimes, build defaults, certificate requirements, and repository integration steps can change even when application code does not.
Use a short review record with the review date, hosting method, runtime version, build command, output directory, required variables, domain configuration, migration status, rollback target, and owner. Update the record when a deployment exposes a new assumption. Also review dependency and supply-chain controls; the SBOM and dependency scanning workflow can help track release contents and open-source risk.
For the next release, take these practical steps:
- Create a clean checkout and run the documented build and test commands.
- Deploy the commit to a preview environment with non-production data.
- Verify environment variables, logs, health checks, and essential user flows.
- Review migration compatibility before promoting the release.
- Record the commit and artifact, then deploy to production with a rollback target ready.
- After release, check domain behavior, HTTPS, errors, latency, and background work.
- Schedule the next review and note any platform terminology or configuration that should be rechecked.
A dependable Git-based deployment is not defined only by a successful first release. It is defined by repeatable builds, controlled configuration, observable runtime behavior, safe data changes, and a rollback path that the team has actually tested.