Mastering GitLab CI/CD Pipeline Fundamentals: GitLab CI/CD for React App

This comprehensive study note explores building an end-to-end continuous integration and deployment (CI/CD) pipeline for a frontend React.js application using GitLab CI/CD, integrated with Maven as a unified build driver.

1. Why Do We Need Frontend Pipelines? (Problem Statement & Status Quo)

Up to this point in our GitLab CI/CD playlist, our focus has been strictly on backend applications (such as Spring Boot). However, modern production architectures require robust automated pipelines for frontend applications built with frameworks like React.js.

• Local vs. Production Execution: Running a local development server using npm start spins up an unoptimized, in-memory development server (webpack-dev-server) that is unsuited for production deployment.
• The Optimization Gap: Production deployments require an optimized, minified bundle of static assets (HTML, CSS, and compiled JavaScript) generated via dedicated build tools.
• Automation Necessity: Manual building, testing, linting, and publishing introduce human error and slow down delivery velocity. We need a reproducible, automated pipeline in GitLab CI/CD to handle this lifecycle.

2. Core Mental Model: React Build Workflow & Maven as a Driver

Real-Life Analogy

Real-Life Analogy: Think of building a React application like preparing a raw blueprint (source code) into a finished, packaged commercial product (distribution build). During local development, workers walk around the workshop freely (npm start). But before shipping it to customers, you need a specialized factory assembly line (npm run build) that compresses, packages, and seals the product into a clean box (the build/ folder), ready for delivery trucks to pick up and drop off at a retail warehouse (Artifact Repository).

Why Use Maven for a Node.js/React Project?

While you can directly execute Node commands (npm run build, npm test), introducing Maven (pom.xml) into a React project standardizes the build lifecycle across both backend and frontend tech stacks.

• Streamlined Release Management: Maven provides built-in lifecycle phases, snapshot versioning, and distribution management out-of-the-box.
• Unified Tooling: Teams familiar with Java/Maven can leverage the exact same build paradigms and repository integrations for frontend projects.

3. Local React App Mechanics: Start, Build, and Test

Before writing our CI/CD YAML configuration, let's examine the local lifecycle commands used in a React project:

Running the Production Build Locally

When you run npm run build, React bundles your application into optimized static files:

npm run build

Output structure generated inside the project:

Note: Only the contents inside the build/ folder need to be deployed to a web server or CDN; raw source files are unnecessary in production.

4. Configuring Maven (pom.xml) as a Build Driver

To orchestrate NPM commands through Maven, a custom pom.xml is configured. This configuration maps Maven lifecycle goals directly to Node script execution.

<project xmlns="http://maven.apache.org/POM/4.0.0" 
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    
    <groupId>com.devops.react</groupId>
    <artifactId>ui-blog-app</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>jar</packaging>

    <name>React Frontend Pipeline Project</name>

    <!-- Distribution Management for Snapshot Publishing -->
    <distributionManagement>
        <snapshotRepository>
            <id>my-snapshot-repo</id>
            <url>http://artifactory.local/libs-snapshot</url>
        </snapshotRepository>
    </distributionManagement>

    <build>
        <plugins>
            <!-- Frontend Maven Plugin configuration to drive npm/node tasks -->
            <plugin>
                <groupId>com.github.eirslett</groupId>
                <artifactId>frontend-maven-plugin</artifactId>
                <version>1.12.0</version>
                <executions>
                    <execution>
                        <id>install node and npm</id>
                        <goals>
                            <goal>install-node-and-npm</goal>
                        </goals>
                        <configuration>
                            <nodeVersion>v16.14.0</nodeVersion>
                        </configuration>
                    </execution>
                    <execution>
                        <id>npm install</id>
                        <goals>
                            <goal>npm</goal>
                        </goals>
                        <configuration>
                            <arguments>install</arguments>
                        </configuration>
                    </execution>
                    <execution>
                        <id>npm run build</id>
                        <goals>
                            <goal>npm</goal>
                        </goals>
                        <configuration>
                            <arguments>run build</arguments>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

5. Designing the 4-Stage GitLab CI/CD Pipeline

Our GitLab CI/CD pipeline consists of four distinct stages, where each stage contains a dedicated job:

1. lint: Performs static code analysis and syntax checking.
2. build: Triggers Maven compilation and generates the optimized production bundle.
3. test: Executes automated unit test cases.
4. publish: Packages the build artifacts into a ZIP archive and pushes them to the artifact repository.

Workflow Rules & Branch Filtering

To optimize build times and prevent redundant resource consumption:

• Merge Requests (MR): Linting, Unit Testing, and Snapshot Publishing jobs are skipped (rules: if: '$CI_PIPELINE_SOURCE == "merge_request_event"' -> when: never). Only the build job runs during MR reviews to validate compilation.
• Target/Default Branch (e.g., main or master): All stages execute in sequence upon merging.

6. Complete GitLab CI/CD Pipeline YAML (.gitlab-ci.yml)

Here is the complete pipeline definition used to drive our React application:

stages:
  - lint
  - build
  - test
  - publish

variables:
  MAVEN_OPTS: "-Dmaven.repo.local=.m2/repository"

cache:
  paths:
    - .m2/repository
    - node_modules/

linting_job:
  stage: lint
  image: maven:3.8.4-openjdk-11
  script:
    - echo "Running code linting and syntax checks..."
    - mvn spotless:check
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      when: never
    - when: on_success

build_job:
  stage: build
  image: maven:3.8.4-openjdk-11
  script:
    - echo "Building React application production bundle via Maven..."
    - mvn clean install -DskipTests
  artifacts:
    name: "react-build-$CI_COMMIT_SHORT_SHA"
    paths:
      - build/
    expire_in: 7 days
  # Allowed to run on Merge Requests to validate code builds successfully

unit_test_job:
  stage: test
  image: maven:3.8.4-openjdk-11
  script:
    - echo "Executing React unit test suites..."
    - mvn test
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      when: never
    - when: on_success

snapshot_publish_job:
  stage: publish
  image: maven:3.8.4-openjdk-11
  script:
    - echo "Packaging build folder into ZIP and publishing snapshot..."
    - mvn clean deploy -DskipTests
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      when: never
    - when: on_success

7. Step-by-Step Execution & Pipeline Verification

Let's trace what happens when a developer commits a code change and pushes it to GitLab.

Step 1: Code Commit & Pipeline Trigger

We make a minor text adjustment inside src/App.js (changing branding text) and commit the changes to a feature branch (nav-fix).

Step 2: Job Execution Breakdown

Upon visiting the GitLab Pipelines dashboard for Pipeline #4, we observe four sequential jobs executing:

1. Linting (linting_job): Analyzes code formatting and detects no syntax errors.
2. Build (build_job): Executes mvn clean install -DskipTests. The underlying Node engine runs npm run build, producing the optimized build/ folder. GitLab saves this folder as a pipeline artifact.
3. Unit Tests (unit_test_job): Executes mvn test, running all 4 React test suites (e.g., using Jest). All tests pass successfully (4 passed, 0 failed).
4. Snapshot Publish (snapshot_publish_job): Packages the build output into a ZIP archive (ui-blog-3.3-snapshot.zip) and uploads it to the configured artifact repository.

8. Verifying Artifacts in Artifactory

Navigating to the artifact repository (Artifactory) confirms successful deployment:

• Target Location: ui-blog-3.3-SNAPSHOT
• Build Number Match: The repository displays artifact version #4, perfectly synchronizing with Pipeline #4 executed on GitLab.
• Packaged Format: The generated artifact is cleanly zipped and stored for downstream release pipelines.

9. Merge Request (MR) Lifecycle & Branch Pipelines

When a developer raises a Merge Request (MR) from the feature branch into the target branch (vt-ui), GitLab triggers a Merge Request Pipeline with specialized behavior:

• MR Pipeline Results: Only the build_job executes. This ensures fast feedback during code reviews without unnecessarily consuming runner compute time on testing or publishing before code is approved.
• Post-Merge Execution: Once the Merge Request is approved and merged into the target branch, a full pipeline runs automatically on the target branch, executing all four stages (lint, build, test, publish).

10. Summary and Key Takeaways

• Frontend CI/CD Parity: React.js applications require optimized production builds (npm run build) rather than running unoptimized development servers in CI runners.
• Maven as a Build Driver: Using Maven plugins (frontend-maven-plugin) for Node.js projects standardizes build lifecycles, artifact packaging, and release management across disparate tech stacks.
• Artifact Management: Production builds generate lightweight static assets (build/ folder) that should be zipped and pushed to an artifact repository during the publishing phase.
• Pipeline Optimization with Rules: Utilizing rules: if: '$CI_PIPELINE_SOURCE == "merge_request_event"' prevents heavy testing and deployment tasks from running unnecessarily during pull request reviews.
• Separation of Concerns: Splitting pipelines into granular stages (lint, build, test, publish) ensures clear diagnostic logging and fast identification of failures in production workflows.