Setting Up CI/CD Pipelines¶

This guide will help you set up standardized CI/CD pipelines for your projects. You'll learn how to configure pipelines for both single projects and monorepos, understand the available templates, and troubleshoot common issues.

Overview¶

Our CI/CD pipeline templates provide: - Automated quality checks and security scanning - Framework-specific optimizations - Standardized deployment workflows - Efficient caching strategies

Prerequisites¶

Before you begin, ensure you have: - Access to your GitLab project/group - Permissions to modify CI/CD settings - Basic understanding of GitLab CI/CD concepts

Quick Start¶

Create a .gitlab-ci.yml file in your project root:

YAML
include:
  - project: 'stratpoint/engineering-standards'
    ref: main
    file: 'pipelines/ci/gitlab/.gitlab-ci.yml'

Commit and push the file to trigger your first pipeline.
Optional: If you need to sync code to external client repositories, follow our External Sync Guide.

The pipeline will automatically detect your project type and apply the appropriate templates.

Project Types¶

Single Project Setup¶

Follow these steps to set up a pipeline for a single project:

Create a Group
Bash
1
Group name: client-web-2024
Follow Naming Conventions
Group naming determines project type:
- client-web-* for web applications
- client-api-* for API services
- client-mobile-* for mobile applications
Create Your Project
Project naming determines framework:
- Include -next- for Next.js projects
- Include -nest- for Nest.js projects
- Mobile projects use Flutter by default
- API projects use Node.js by default

Example structure:

Bash
client-web-2024/
├── admin-next-dashboard/     # Uses Next.js template
├── api-nest-gateway/         # Uses Nest.js template
└── marketing-next-site/      # Uses Next.js template

Monorepo Setup¶

For monorepo projects, follow these steps:

Create a Group
Bash
1
Group name: client-monorepo-2024

Structure Your Project

Bash
client-monorepo-2024/
└── project-name/
    ├── apps/
    │   ├── web/          # Next.js frontend
    │   ├── mobile/       # Flutter mobile
    │   ├── api/          # Node.js/Nest.js backend
    │   └── libs/         # Shared libraries
    └── package.json

Pipeline Features
Path-based triggers for each application
Shared library changes trigger all pipelines
Independent deployment flows
Optimized caching for monorepo structure

Available Templates¶

Base Templates¶

Quality Gates¶

Quality checks include:

Linting with configurable rules
Unit testing with coverage reporting
Type checking for TypeScript
Dependencies security audit
Bundle size analysis
Performance testing

Security Checks¶

Security features include:

SAST (Static Application Security Testing)
Secret detection
Configurable security logging
Test directory exclusions

Framework-Specific Templates¶

Next.js Projects¶

Dependency management
Build optimization
E2E testing with Playwright
Staging and production deployments
Cache management for builds

Nest.js Projects¶

Backend build process
Integration testing with databases
API documentation generation
Production/staging environments
Service dependencies (PostgreSQL, Redis)

Flutter Projects¶

Multi-platform builds (iOS/Android)
Static analysis
Unit and integration testing
App store deployments
Play Store internal testing
TestFlight distribution
Platform-specific configurations

Node.js API Projects¶

Build and deployment pipeline
API testing suite
Load testing with k6
MongoDB integration
OpenAPI documentation
Environment-specific configurations

Configuration¶

Environment Variables¶

Common Variables¶

Variable	Description
`CI_COMMIT_REF_SLUG`	Branch/tag name for caching
`CI_PROJECT_NAME`	Project name for URLs
`CI_PROJECT_ID`	Project ID for unique identifiers
`WORKSPACE`	Application path in monorepo

Stack-Specific Variables¶

Stack	Variables
Next.js	`NEXT_TELEMETRY_DISABLED`
Flutter	`FLUTTER_VERSION`, `ANDROID_COMPILE_SDK`
Node.js	`NODE_ENV`, `MONGODB_URI`

Cache Configuration¶

Single Project Cache¶

YAML
cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - node_modules/
    - .yarn/
    - .npm/

Monorepo Cache¶

YAML
cache:
  key: ${CI_COMMIT_REF_SLUG}-${CI_JOB_NAME}
  paths:
    - apps/*/node_modules/
    - libs/node_modules/

Troubleshooting Guide¶

Common Issues¶

Pipeline Not Inheriting¶

Check group CI/CD settings
Verify naming conventions
Review GitLab admin settings

Quality Gates Failing¶

Check pipeline logs
Review quality requirements
Verify code standards

Cache Issues¶

Clear pipeline caches
Verify cache key configuration
Check storage quota

Support Process¶

If you encounter issues:

Check pipeline logs
Review template inheritance
Verify naming conventions
Contact systems engineering team

Maintenance¶

Our pipeline templates are: - Managed in the systems-engineering group - Automatically applied to all projects - Tested in staging before deployment - Documented with all modifications

Getting Help¶

Need assistance? Contact: - Systems Engineering Team - DevOps Team - Platform Support

Reference¶

Repository Structure¶

This structure represents the Systems Engineering team's pipeline configuration repository. As a user, you don't need to implement this structure - you only need to reference it in your project's .gitlab-ci.yml as shown in the Quick Start section.

YAML
engineering-standards/                  # Systems Engineering maintained repository
└── pipelines/                          # Pipeline configurations
    ├── ci/
    │   ├── gitlab/                     # GitLab CI configurations
    │   │   ├── .gitlab-ci.yml          # Main GitLab CI entry point
    │   │   ├── configs/                # Main pipeline configs
    │   │   │   ├── single.yml          # Single project pipeline
    │   │   │   └── monorepo.yml        # Monorepo pipeline
    │   │   └── templates/              # Reusable templates
    │   │       ├── base/               # Base templates
    │   │       │   ├── quality.yml     # Quality gates
    │   │       │   └── security.yml    # Security checks
    │   │       └── stacks/             # Stack-specific templates
    │   │           ├── web/
    │   │           │   ├── nextjs.yml  # Next.js frontend
    │   │           │   └── nestjs.yml  # Nest.js backend
    │   │           ├── mobile/
    │   │           │   └── flutter.yml # Flutter mobile
    │   │           └── api/
    │   │               └── node.yml    # Node.js API
    │   └── github/                     # GitHub Actions configurations
    │       └── workflows/              # GitHub Actions workflow templates
    └── gitops/                         # GitOps configurations