Gemini 3 Flash

Manual deployments are prone to human error, resulting in "it works on my machine" syndrome and inconsistent production environments. This guide demonstrates how to automate the lifecycle of a React application using GitLab CI/CD to ensure every commit is validated, tested, and deployed to a live environment. You will need a GitLab account, Node.js 20+ installed locally, and a basic understanding of Git commands.

Environment Setup and Project Initialization

We will use Vite to scaffold our React application because it provides a faster development experience and smaller bundle sizes compared to older tools. Run the following commands in your terminal to create a new TypeScript-based React project and prepare it for version control.

# Create a new Vite project with the React-TS template
npm create vite@latest react-cicd-app -- --template react-ts

# Navigate into the project directory
cd react-cicd-app

# Install dependencies locally to ensure the project runs
npm install

# Initialize git and create an initial commit
git init
git add .
git commit -m "Initial commit: React + Vite scaffold"

Vite generates a standard directory structure with a src folder for your logic and a public folder for static assets. Before proceeding, verify that the application starts correctly on your local machine to confirm the baseline is stable.

# Start the development server
npm run dev

The terminal should display a local URL (usually http://localhost:5173). Open this in your browser to see the default React + Vite landing page. Once confirmed, stop the process with Ctrl+C and create a new repository on GitLab. Link your local project to GitLab using the following command, replacing the placeholder with your actual repository URL.

# Link your local repository to GitLab
git remote add origin https://gitlab.com/your-username/react-cicd-app.git

⚠️ Note: Ensure your GitLab repository is empty before pushing. If you initialized it with a README on the GitLab website, you will need to pull those changes first or use the force flag, which is generally discouraged in collaborative environments.

Defining the CI/CD Pipeline Configuration

GitLab CI/CD is managed by a single file named .gitlab-ci.yml located in the root of your project. This file defines the stages, jobs, and scripts that the GitLab Runner will execute whenever code is pushed to the repository. We will define four distinct stages: install, test, build, and deploy.

# Use the official Node.js 20 Alpine image for a lightweight execution environment
image: node:20-alpine

# Define the order of execution for our jobs
stages:
  - install
  - test
  - build
  - deploy

# Global cache configuration to persist node_modules across jobs and pipeline runs
cache:
  key:
    files:
      - package-lock.json
  paths:
    - .npm/

# This job installs dependencies and caches them
install_dependencies:
  stage: install
  script:
    - npm ci --cache .npm --prefer-offline
  artifacts:
    paths:
      - node_modules/
    expire_in: 1 hour

The npm ci command is used instead of npm install because it is optimized for continuous integration environments. It ensures that the package-lock.json is strictly followed, preventing version drift between your local machine and the build server. We use artifacts to pass the node_modules folder to subsequent stages, ensuring we don't waste time re-installing packages.

Next, we add the testing and building jobs to the configuration file. These jobs rely on the node_modules provided by the previous stage. The build stage generates a dist folder containing the minified production assets.

# Run linting and unit tests
run_tests:
  stage: test
  dependencies:
    - install_dependencies
  script:
    - npm run lint
    # If you have Vitest or Jest set up, run: npm run test

# Compile the React application for production
build_application:
  stage: build
  dependencies:
    - install_dependencies
  script:
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 1 week

Vite's build process creates a highly optimized version of your app. By saving the dist folder as an artifact with a 1-week expiration, you can download specific builds directly from the GitLab UI if you need to debug a previous release. The dependencies keyword ensures that this job only starts after the install_dependencies job completes successfully.

Handling Vite Base Paths for GitLab Pages

When deploying to GitLab Pages, your application is typically hosted at a subpath like https://username.gitlab.io/project-name/. By default, Vite assumes the app is at the root directory, which causes CSS and JS files to return 404 errors. We must modify vite.config.ts to handle this dynamic routing.

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [react()],
  // Set the base path to the repository name for GitLab Pages compatibility
  // Replace 'react-cicd-app' with your actual GitLab project slug
  base: '/react-cicd-app/',
})

This configuration ensures that all asset URLs generated during the build process are prefixed with the correct path. Without this, the browser would look for /assets/index.js at the domain root instead of within your project folder. Now, we add the deployment stage to .gitlab-ci.yml to push these assets to GitLab Pages.

# Special job name 'pages' is required for GitLab Pages deployment
pages:
  stage: deploy
  dependencies:
    - build_application
  script:
    # GitLab Pages looks for a folder named 'public'
    # We move our 'dist' contents into 'public'
    - mkdir .public
    - cp -r dist/* .public
    - mv .public public
  artifacts:
    paths:
      - public
  rules:
    # Only run this job when changes are merged into the main branch
    - if: $CI_COMMIT_BRANCH == "main"

The pages job is a reserved keyword in GitLab CI. When this job finishes and provides an artifact named public, GitLab automatically starts a background process to host those files. Using the rules attribute prevents experimental feature branches from overwriting your live production site.

⚠️ Note: If your project is a User or Group page (e.g., username.gitlab.io), the base in vite.config.ts should remain /. Only use the project slug if the URL includes a trailing path.

Optimizing the Pipeline with Caching Strategies

Speed is critical in CI/CD. Re-downloading every npm package on every commit is a waste of resources and time. While we used artifacts to pass node_modules between stages in a single pipeline, cache is used to share files between completely different pipeline runs.

Update the top of your .gitlab-ci.yml to include a more aggressive caching strategy. This configuration uses a hash of the package-lock.json file as the cache key, meaning the cache is only invalidated when you add or remove a dependency.

cache:
  key:
    files:
      - package-lock.json
  paths:
    - .npm/
    - node_modules/

# Update the install job to use the cache effectively
install_dependencies:
  stage: install
  script:
    - npm ci --cache .npm --prefer-offline
  artifacts:
    paths:
      - node_modules/

By including node_modules/ in the cache paths, the install_dependencies job will find the folder already populated in subsequent runs. The npm ci command will then only verify the integrity of the files rather than downloading them. This can reduce pipeline execution time by several minutes for larger React projects.

Expected Output: When you push this configuration, navigate to Build > Pipelines in GitLab. You should see four green checkmarks indicating that each stage (install, test, build, deploy) has passed. Clicking on the pages job log will show the successful upload of artifacts to the GitLab Pages server.

Verification and Testing

To verify the pipeline, make a small change to src/App.tsx. Change the text inside the h1 tag to "React + GitLab CI/CD" and commit the change. This should trigger the pipeline automatically.

# Stage changes
git add .

# Commit with a descriptive message
git commit -m "Update heading and verify CI/CD pipeline"

# Push to the main branch
git push origin main

Monitor the progress in the GitLab sidebar under Build > Pipelines. Each stage will run sequentially. If the run_tests stage fails (for example, if a linting error is introduced), the build_application and pages stages will be skipped, preventing a broken version of the app from reaching production.

Once the pages job completes, go to Deploy > Pages in the GitLab sidebar. You will find a URL where your application is hosted. Click it to see your live React app. If the page appears blank, open the browser's developer console (F12) to check for 404 errors, which usually indicate an incorrect base path in vite.config.ts.

To further verify the "Test" stage, you can intentionally break a linting rule. For example, define a variable that is never used and push the code. The run_tests job will fail because the default Vite linting rules (ESLint) forbid unused variables, and the pipeline will stop immediately.

Wrap-up

You have successfully built a multi-stage CI/CD pipeline that automates the installation, testing, building, and deployment of a React application. This setup ensures that only code passing your quality checks reaches the end-user, while caching and artifacts optimize the build speed. To extend this further, consider adding Playwright for end-to-end testing or integrating environment variables via GitLab's CI/CD settings to manage different API endpoints for staging and production environments.