How to Deploy a Web App from a Git Repository: A Repeatable CI/CD Workflow

Overview

A Git-based deployment workflow connects a repository event, usually a push or pull request, to a sequence of automated steps. The exact screens and commands vary between a managed developer hosting platform, an open source deployment platform, and a self-hosted CI/CD system, but the underlying process is similar:

1. Source: A branch or tag identifies the code to build.
2. Validation: Automated checks run before deployment, including formatting, linting, type checks, and tests.
3. Build: The pipeline installs dependencies and creates the deployable output.
4. Configuration: Runtime settings and secrets are supplied without storing sensitive values in Git.
5. Release: The application is deployed to a preview, staging, or production environment.
6. Verification: Health checks, smoke tests, logs, and basic user flows confirm that the release works.

The most important design decision is to separate environments. A pull request can create a preview deployment, a protected integration branch can deploy to staging, and an approved tag or main-branch change can deploy to production. This gives reviewers a useful target without making every code change a production release.

Before choosing a provider, compare repository integration, build runners, secret management, deployment targets, logs, rollback support, and ownership requirements. Teams evaluating open source hosting can use this comparison of GitHub alternatives as a starting point. If you need more control over runners and infrastructure, review the self-hosted CI/CD pipeline guide.

Checklist by scenario

Scenario 1: Deploying a frontend application

For a static site or client-rendered application, the build normally produces a directory of HTML, CSS, JavaScript, and assets. Confirm the following:

• The correct Node.js or other runtime version is defined and used consistently by local development and CI.
• Dependencies are installed from a lockfile when the project uses one.
• The build command and output directory are documented, such as npm run build and dist.
• Public configuration, including an API base URL, is set for the target environment.
• Single-page application routing is configured so direct navigation to a nested route does not return a server error.
• Source maps, asset caching, and deployment size are reviewed according to the project’s needs.

Deploy the generated output rather than the development source tree. After release, test the homepage, a representative deep link, form submission, asset loading, and the connection to any backend API.

Scenario 2: Deploying a backend or API

A backend deployment usually requires a running process, a listening port, a database connection, and operational checks. Add these items to the workflow:

• Use the port supplied by the hosting environment instead of assuming a fixed local port.
• Keep migrations separate from application startup unless the deployment design explicitly makes them safe and repeatable.
• Define a lightweight health endpoint that checks application readiness without exposing sensitive data.
• Set request timeouts, logging behavior, and graceful shutdown handling.
• Verify database, cache, queue, and third-party service credentials in the target environment.
• Test authentication, authorization, error responses, and one representative write operation.

Do not treat a successful process start as proof that the API is healthy. A service may bind to its port while failing to connect to a required dependency.

Scenario 3: Deploying a containerized application

For a container workflow, the pipeline builds an image, runs checks against it, publishes it to a registry, and updates the deployment target. Check that:

• The image uses a deliberate base image and does not include unnecessary development files or credentials.
• The build is reproducible and receives a meaningful commit or release identifier.
• Container startup, health checks, and signal handling work outside the local machine.
• The deployment target can pull the exact image version being released.
• The previous image remains available until the new deployment is verified.

For registry selection and private image management, see the guide to open source container registries.

Scenario 4: Deploying from a monorepo

A monorepo needs an explicit relationship between changed files and deployable services. Use path filters or dependency-aware tasks where supported, but keep a full validation path available for shared packages. Confirm:

• Each application has an unambiguous build and start command.
• Shared package changes trigger the applications that depend on them.
• Working directories and cache keys are correct for each job.
• Only the intended service is released when independent deployment is supported.
• Cross-service compatibility checks run before production deployment.

More detailed planning considerations are covered in this monorepo CI/CD guide.

What to double-check

Repository and trigger settings

Confirm that the deployment system is connected to the intended repository and branch. Review whether deployments start on pushes, pull requests, tags, manual approvals, or a combination. Protect production branches and require review where the project’s risk level calls for it. Make sure duplicate triggers cannot release the same commit twice unintentionally.

Build reproducibility

Run the same essential commands in a clean environment that developers use in CI. Pin or constrain runtime versions, commit lockfiles, and fail clearly when required tools are missing. Caches can reduce build time, but they should accelerate a valid build rather than determine whether it succeeds. If a cache is restored incorrectly, the pipeline should be able to rebuild from a clean state.

Environment variables and secrets

Classify configuration into three groups: values safe to expose to the browser, server-side configuration, and credentials. Store secrets in the deployment system or an external secret manager, limit their scope, and avoid printing them in logs. Check variable names carefully; a misspelled value can look like an application bug.

Release and rollback behavior

Document what constitutes a successful deployment and how to return to the last known-good version. A rollback may mean selecting a previous build, redeploying a prior container image, reverting a Git change, or switching traffic to an earlier release. Database schema changes require extra care: prefer backward-compatible migrations when an application rollback may be needed.

Post-deployment verification

Use a short, repeatable smoke-test list: load the main page, authenticate if applicable, exercise one important user flow, inspect the health endpoint, review error logs, and confirm that static assets and API requests use the expected environment. Automated checks are valuable, but a small manual check can catch configuration and routing problems that unit tests do not cover.

Common mistakes

• Deploying directly from an unreviewed feature branch: Use previews for branch-level testing and reserve production for a controlled release path.
• Relying on local configuration: Document required variables and validate them at startup or during the pipeline.
• Building with one runtime and running with another: Align versions across local development, CI, containers, and the hosting target.
• Skipping dependency installation checks: A pipeline that silently uses stale files can produce a deployment that does not match the commit.
• Running destructive migrations automatically: Back up where appropriate, review migration behavior, and define a recovery plan.
• Ignoring failed previews: Preview failures often reveal the same build, routing, or environment issues that would affect production.
• Making rollback theoretical: Practice the rollback path in a non-production environment and record who can initiate it.
• Putting secrets in repository files: Remove exposed credentials, rotate them, and inspect build logs if a secret may have been printed.

For small troubleshooting tasks, online code utilities can help inspect configuration and payloads, but sensitive production data should not be pasted into an unapproved tool. The developer tools toolkit explains appropriate uses for JSON, SQL, JWT, and regex utilities.

When to revisit

Revisit this checklist before a major planning cycle, after changing hosting or repository providers, and whenever the application’s build or runtime changes. It should also be reviewed after a failed release, a security incident, a new database migration strategy, or the addition of a service such as a queue, cache, object store, or external API.

At minimum, keep these deployment records current:

• The supported runtime and dependency installation command.
• The build, test, and start commands for each application.
• Required environment variables and which environment owns each value.
• Branch, tag, approval, and manual-trigger rules.
• Health checks, smoke tests, log locations, and alert destinations.
• The rollback procedure and the person or team authorized to use it.

When workflows or tools change, run one controlled release through preview, staging, and production—or the equivalent environments available to your project. Record the commit, configuration changes, verification results, and rollback outcome. A Git-based deployment workflow stays dependable not because it never changes, but because its assumptions are visible, tested, and easy to update.