Setting Up a CI/CD Pipeline for a React App with GitLab CI/CD
Automating deployment for a React application streamlines development by handling builds, tests, and deployments without manual intervention. This guide walks through configuring a CI/CD pipeline using GitLab CI/CD to build a React app, run tests, and deploy it to GitLab Pages. Prerequisites include a GitLab account, Node.js version 18 or higher installed, Git, and basic familiarity with React and YAML syntax.
Setup
Begin by creating a new React application if you don't have one. This establishes the base project structure for the pipeline. Use Create React App for a quick start with built-in configurations.
npx create-react-app my-react-app
cd my-react-app
After running these commands, you get a directory with src, public, and configuration files like package.json. This setup includes scripts for building and testing, which the pipeline will use. Next, initialize a Git repository and push it to GitLab.
git init
git add .
git commit -m "Initial commit"
Create a new project on GitLab and follow the instructions to add the remote origin. Push the code with git push -u origin master. Your project now exists on GitLab, ready for CI/CD configuration.
⚠️ Note: Ensure your GitLab project is public or you have appropriate access tokens if private, as pipelines require repository access.
Configuring the GitLab CI/CD Pipeline File
The core of GitLab CI/CD is the .gitlab-ci.yml file, which defines the pipeline stages and jobs. Place this file in the root of your repository to trigger pipelines on commits. This configuration ensures automated workflows for consistency.
Start by defining stages for build, test, and deploy. Each stage runs sequentially, allowing failures to halt progression. This structure prevents deploying untested code.
stages:
- build
- test
- deploy
With stages set, add a job for building the React app. This job uses a Node.js image to install dependencies and run the build script. The artifacts section preserves the build output for later stages.
build-job:
stage: build
image: node:18
script:
- npm install
- npm run build
artifacts:
paths:
- build
Commit and push this initial .gitlab-ci.yml to your repository. In GitLab, navigate to CI/CD > Pipelines to see the pipeline start. Expect a successful build job that produces a 'build' directory artifact.
⚠️ Note: If npm install fails due to network issues, check your internet connection or add retries in the script, like npm install --network-timeout=100000.
Adding Testing to the Pipeline
Integrate testing to catch errors early in the pipeline. React apps from Create React App include Jest for unit tests by default. This step runs tests after building, ensuring code quality before deployment.
Extend the .gitlab-ci.yml with a test job. It depends on the build artifacts and executes the test script. Using the same Node.js image keeps the environment consistent across jobs.
test-job:
stage: test
image: node:18
script:
- npm install
- npm run test -- --watchAll=false
dependencies:
- build-job
To make tests meaningful, add a simple test in your React app. Open src/App.test.js and ensure it has at least one passing test. For example, verify the app renders without crashing.
import { render, screen } from '@testing-library/react';
import App from './App';
test('renders learn react link', () => {
render(<App />);
const linkElement = screen.getByText(/learn react/i);
expect(linkElement).toBeInTheDocument();
});
Push the updated files. The pipeline now includes a test stage. Check the pipeline logs for test output, showing passed tests and coverage if configured.
⚠️ Note: Tests might fail if dependencies change; always run npm test locally before pushing to verify.
Configuring Deployment to GitLab Pages
Deployment automates publishing the built app to a live URL via GitLab Pages. This job runs only on the main branch for production safety. It moves the build artifacts to the public directory expected by Pages.
Add the deploy job to .gitlab-ci.yml. Use the alpine image for lightweight file operations. The script renames the build directory to public, and the pages keyword enables GitLab Pages hosting.
pages:
stage: deploy
script:
- mv build public
artifacts:
paths:
- public
only:
- main
dependencies:
- build-job
This completes the pipeline configuration. The full .gitlab-ci.yml now handles build, test, and deploy stages automatically. Commit and push to main to trigger the full pipeline.
stages:
- build
- test
- deploy
build-job:
stage: build
image: node:18
script:
- npm install
- npm run build
artifacts:
paths:
- build
test-job:
stage: test
image: node:18
script:
- npm install
- npm run test -- --watchAll=false
dependencies:
- build-job
pages:
stage: deploy
script:
- mv build public
artifacts:
paths:
- public
only:
- main
dependencies:
- build-job
After pushing, monitor the pipeline in GitLab. Upon success, access the deployed site at https://<username>.gitlab.io/<project-name>. The page displays your React app's content.
⚠️ Note: Deployment fails if the public directory isn't correctly set; double-check the mv command and ensure no naming conflicts.
Testing and Verification
To verify the pipeline, make a small change like updating text in src/App.js and push to main. Watch the pipeline run through build, test, and deploy stages in GitLab's CI/CD section. Confirm success by checking job logs for no errors and visiting the Pages URL to see the update live.
Simulate a failure by introducing a breaking test, such as changing the expected text in App.test.js. Push the change and observe the test job fail, halting deployment. Fix the test, push again, and ensure the pipeline succeeds, deploying the corrected app.
For thorough checks, enable pipeline notifications in GitLab settings. This sends emails on failures, helping quick responses. Review artifacts downloads to inspect build outputs manually if needed.
We configured a CI/CD pipeline that automates building, testing, and deploying a React app to GitLab Pages, reducing manual errors and speeding up iterations. Extend this by adding environment variables for secrets, integrating linting jobs, or deploying to other platforms like AWS S3. Experiment with branch-specific deployments for staging environments to further customize the workflow.
