How to Deploy a Web App From a Git Repository: A Complete CI/CD Workflow

Overview

A Git-based deployment workflow turns a repository into the source of truth for an application. A typical change moves through these stages:

1. A developer pushes a branch or opens a pull request.
2. The CI system installs dependencies, runs checks, and builds the application.
3. A preview environment is created for review when appropriate.
4. An approved change is merged into the production branch.
5. The deployment system builds the selected commit and releases it to production.
6. Health checks, logs, and monitoring confirm whether the release is working.

The exact commands depend on the language, framework, hosting model, and CI/CD platform. The underlying design is more durable: keep build instructions in version control, make environments explicit, separate secrets from source code, and ensure every production release can be traced to a commit.

An open source deployment platform or developer hosting platform can provide repository integration, build runners, deployment targets, environment management, and release history. Self-hosted CI/CD can offer more control over infrastructure and data, while a managed service may reduce operational work. In either case, document the workflow so another developer can reproduce it without relying on one person's local setup.

For related infrastructure decisions, see how to choose an open source API gateway and open source build cache and remote caching options.

Checklist by scenario

Scenario 1: Deploying a small static or frontend application

• Confirm the repository contains a documented install command, build command, and output directory.
• Set the required runtime version and package manager version where the platform supports it.
• Use a clean build in CI rather than depending on files left over from a previous build.
• Configure the application’s public base URL, API URL, and other non-secret build settings.
• Decide whether every pull request receives a preview URL or only selected branches.
• Set the production branch and require a successful build before deployment.

For single-page applications, verify that the hosting layer serves the application entry point for client-side routes. A build may succeed while a direct request to a nested route returns a not-found response if fallback routing is not configured.

Scenario 2: Deploying an API or backend service

• Define the start command separately from the build command.
• Set the service port through the hosting environment rather than hard-coding an assumption.
• Configure database, queue, storage, and third-party service connections as environment variables or managed secrets.
• Add a lightweight health endpoint that confirms the process is accepting requests.
• Decide how database migrations run and whether they must complete before traffic moves to the new release.
• Set request timeouts, resource limits, and graceful shutdown behavior where supported.

Do not treat a process-started signal as proof that the API is usable. A deployment check should test the service through the same route and configuration that real traffic uses, while avoiding destructive operations.

Scenario 3: Deploying with containers

• Keep the Dockerfile and related build files in the repository.
• Pin important base images and dependencies according to your maintenance policy.
• Use a multi-stage build when it clearly separates compilation tools from the runtime image.
• Build the image in CI, scan it according to your security process, and publish it to an accessible container registry.
• Deploy an immutable image reference, such as a commit-based tag or digest, rather than an ambiguous moving tag.
• Confirm that the runtime user, filesystem permissions, exposed port, and required certificates are correct.

If the project needs private images, include registry authentication in the deployment environment instead of placing credentials in the repository. A registry decision should also account for retention, access control, and recovery; see this guide to open source container registries for private projects.

Scenario 4: Using a monorepo

• Identify which directories changed and avoid rebuilding unrelated applications when the CI system can safely filter work.
• Keep each deployable service’s build, test, and start instructions discoverable.
• Define dependency boundaries and shared package behavior.
• Use path-based deployment rules carefully so a shared library change triggers all affected applications.
• Separate environment variables and deployment targets for each service.

Monorepo optimization can reduce unnecessary work, but incorrect path filters can create stale deployments. Compare optimization gains with the risk of skipping a required build. For a broader planning checklist, see monorepo CI/CD best practices.

Scenario 5: Adding pull-request previews

• Give each preview an identifiable URL or label.
• Use safe, limited test data rather than copying production data into temporary environments.
• Provide the preview with only the secrets it needs.
• Set an expiration or cleanup process for abandoned previews.
• Make the preview status visible in the pull request.

Preview environments are most useful when reviewers can test a realistic build without waiting for a manual handoff. They should still be treated as deployments with access, cost, and data-retention implications. Review the separate guide to preview environments for pull requests.

What to double-check

Repository and branch settings

• The deployment is connected to the intended repository and organization.
• The production branch is clearly named and protected against accidental direct pushes.
• Builds run against the commit that will actually be deployed.
• Forks and untrusted pull requests cannot access production secrets.
• Webhook or integration permissions are limited to what the workflow requires.

Build reproducibility

Run the same essential checks locally and in CI, but do not make a local machine a hidden dependency. Commit lockfiles, define supported runtime versions, and use a clean checkout during automated builds. If a build requires generated files, decide whether they are produced in CI or stored in the repository. Record the commands in a README or project-specific development document.

Environment variables and secrets

Separate configuration into at least development, preview, and production scopes. Classify each value as public configuration, sensitive configuration, or a credential. Public browser-side values are not secret merely because they are stored in an environment-variable interface; anything bundled into frontend code may be visible to users.

Check variable names, whitespace, multiline formatting, rotation procedures, and availability during both build time and runtime. Never print secrets in build logs. If a credential may have been exposed, revoke or rotate it and investigate where it appeared.

Release safety

• Require tests and review before production deployment.
• Use a deployment approval step for systems where an immediate release is inappropriate.
• Run a smoke test after deployment.
• Record the commit, image, configuration version, and migration state for each release.
• Keep the previous known-good release available for rollback.
• Define who can initiate, approve, and reverse a production deployment.

Feature flags can separate code delivery from feature exposure, particularly when a full rollback is difficult because of data changes. Learn more about open source feature flag tools.

Common mistakes

Deploying directly from a developer laptop

Manual deployment hides the exact commit, command, and environment used for a release. Keep an emergency procedure if necessary, but make the normal path a recorded CI/CD workflow.

Using different commands locally and in CI

A local build that uses cached dependencies or uncommitted generated files can create false confidence. Start from a clean checkout and run the documented commands in an environment close to production.

Putting secrets in Git

Removing a secret from the latest commit does not guarantee it is absent from repository history, logs, caches, or artifacts. Use the hosting platform’s secret store, rotate exposed credentials, and add secret-file patterns to ignore rules where appropriate.

Skipping rollback planning

A failed deployment is easier to handle when the previous artifact is known and redeployable. Test the rollback path before it is needed, and distinguish application rollback from database rollback. Schema changes may require a backward-compatible transition rather than an immediate reversal.

Ignoring logs and deployment artifacts

When a release fails, you need the build output, runtime logs, deployment status, and health-check response. Set retention that supports investigation while respecting your data-handling requirements. Avoid relying on a single dashboard that may be unavailable during an incident.

Optimizing before measuring

Build caches, parallel jobs, and selective monorepo builds can improve speed, but they also add invalidation and correctness concerns. First establish a reliable baseline, then measure queue time, build time, deployment time, and failure rate before changing the workflow.

When to revisit

Revisit this deployment checklist before a seasonal planning cycle, a major release, or a change in traffic and availability requirements. It should also be reviewed whenever the repository structure, framework, runtime, container base image, CI/CD platform, hosting provider, secrets, registry, database, or deployment target changes.

Use the following practical review sequence:

1. Deploy a small change to a non-production environment.
2. Confirm that tests, preview creation, logs, and health checks behave as expected.
3. Promote the same verified commit or immutable artifact to production.
4. Run the documented smoke tests and compare key application signals with the expected baseline.
5. Perform a controlled rollback or verify that the rollback artifact is ready, depending on the risk of the change.
6. Update the repository documentation when a command, variable, permission, or approval step changes.

At minimum, assign an owner for the workflow and keep a short record of its last review. The goal is not to create a complicated release system. It is to ensure that deploying from Git remains understandable, repeatable, secure, and reversible as the application and its hosting environment evolve.