Gitlab on Software Factory

Source Code Management

Mon, 01 Jan 0001 00:00:00 +0000

➡️ For detailed information about SCM Practices, refer to the section SCM Practices .

Organize your repositories

GitLab Group

Groups in GitLab are used to manage multiple projects together that share a common purpose or belong to the same team.

They act as containers that can hold projects, other groups (subgroups), and members.

Key Points:

Project Management: Groups allow you to manage permissions, settings , and access controls across multiple projects.
Collaboration: They facilitate collaboration by grouping related projects and team members together.
Subgroups: Groups can have subgroups, allowing for a nested structure to represent different departments or teams within an organization.

For example, you might have a GitLab Group called “NextGen Radar” that contains separate projects for the application frontend, backend, and content.

Plan

Mon, 01 Jan 0001 00:00:00 +0000

GitLab helps teams organize, plan, align and track project work to ensure teams are working on the right things by maintaining end to end visibility and traceability of issues throughout the delivery lifecycle.

By using GitLab for the plan stage your, you use the same tool that developers use to create, test, secure, and release the software making the whole process transparent and adding more collaboration.

With GitLab Plan you can:

CI/CD

Mon, 01 Jan 0001 00:00:00 +0000

GitLab CI/CD is a robust suite of DevOps tools embedded within GitLab, facilitating the automation of the entire software development lifecycle.

It integrates seamlessly with GitLab repositories, offering a complete pipeline framework to automate the processes of building, testing and deploying code.

Key Concepts and Components

Pipelines: Series of steps that execute in a defined order. Each step performs a specific actions, such as building the code, running tests, or deploying to an environment.
Pipelines could be triggered by various events, such as pushes to the repository, merge requests, or scheduled intervals. You can find a detailed explanation of pipelines .

Secure

Mon, 01 Jan 0001 00:00:00 +0000

GitLab Ultimate embeds a suite of security scanners directly into your CI/CD pipelines. They cover two complementary approaches: static analysis (source code, dependencies, secrets) and dynamic analysis (running application). All results are centralised in a single vulnerability report within GitLab.

Tip

Not familiar with the terminology? See SAST, DAST, SCA and other security terms in the glossary.

Analytics

Mon, 01 Jan 0001 00:00:00 +0000

DevOps Adoption Analytics

GitLab’s DevOps Adoption feature provides visibility into how your teams are using GitLab’s capabilities on DevOps life cycle.

This analytics tool helps leadership and DevOps coaches measure and identify opportunities for improvement.

What is DevOps Adoption?

DevOps Adoption is a built-in dashboard that tracks DevOps usage across your instance or groups and subgroups.

It measures whether teams are actively using core GitLab features that represent DevOps best practices, providing a clear picture of your organization’s DevOps maturity.

GitLab Kanban

Mon, 01 Jan 0001 00:00:00 +0000

Kanban is a scheduling system based on push (rather than pull from scrum). In this tutorial, we will manage a simple Kanban board with 4 statuses as these are adequate for a demonstration

Create new subgroup and epics

Create a subgroup / project

Navigate to your group, and select New subgroupin the top right for the page,
Type a name for your subgroup and select Create subgroupto create it.
inside the newly created subgroup, select New projectat the top of the page,
Give your project a Name and select Create project.

Create epics

Navigate to your subgroup, on open Planmenu on left pane,
Select Epics
Select New epicon the top right and type at least some content into the Title field, you can fill other field, but they are not mandatory
Select Create epic

For the purpose of this tutorial, you can create 2 others

Black Duck SCA

Mon, 01 Jan 0001 00:00:00 +0000

This guide outlines practical, step-by-step instructions for integrating Black Duck SCA into your workflow, from initial project setup to CI/CD integration, advanced manual operations, and local IDE scanning.

Prerequisites: You must have Maintainer permissions for your GitLab repository and access to the Black Duck server.

How to Prepare Your Black Duck Project

Before analyzing your source code, you must provision a project space.

Log in to your account on the Black Duck server.
In the top-right corner of the dashboard, click + Create Project.
Enter your Project Name.
Enter an initial Version Name (e.g., main, v1.2.0).
Fill out the desired fields (like Tier or Phase) and click Save.
Ensure your user account (or service account) has Project Code Scanner permissions.

How to Generate and Secure an Authentication Token

Your tools need access to a token to communicate with the server. Never hardcode this token in your source code.

Dynamic Application Security Testing (DAST)

Mon, 01 Jan 0001 00:00:00 +0000

GitLab Ultimate uses the same open source tool [OWASP Zed Attack Proxy] for analysis as ZAP. It’s already embedded in your engineering environment and results are directly published in the vulnerability report within GitLab.

Always use a staging environment with fake data, not on a production environment.

How does DAST Scanning Work?

The two main modes available for DAST are:

Docker image pull

Mon, 01 Jan 0001 00:00:00 +0000

Pulling Docker Images from Artifactory

Docker Hub limits the number of Docker image pulls to 100 per 6 hours per IP address for anonymous users.

GitLab Instance Runners provided by the Software Factory use a single IP to pull images from Docker Hub.

When the pull rate limit is reached, the following error message will appear:

ERROR: Job failed:
prepare environment: waiting for pod running: pulling image "image:tag":
image pull failed [...] 429 Too Many Requests - Server message: toomanyrequests: You have reached your pull rate limit.

To be able to pull Docker images (image: in .gitlab-ci.yml) from private registries (for example from artifactory.thalesdigital.io), you need to set up the CICD GitLab variable DOCKER_AUTH_CONFIG.

Documentation

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

Good documentation is essential for projects to be successful. It allows team collaboration and easy onboarding, and preserves valuable knowledge.

GitLab offers a variety of powerful tools to help you document your project comprehensively.

In this guide, we will explore the different options available for project documentation.

By using these tools, you can create clear, accessible, and well-organized documentation.

GitLab Wiki

GitLab Wiki is an integrated feature within GitLab projects providing a collaborative space for teams to write, edit, and organize content.

GitLab

Mon, 01 Jan 0001 00:00:00 +0000

This guide provides a concise overview of GitLab’s core features and commonly used functionalities. It aims to familiarize you with the product and equip you with best practices to optimize your development workflow.

For detailed information and advanced features, refer to the official GitLab documentation

Info

This page describes the tool independently of any platform-specific details. For the service URL and other platform-specific configuration, please refer to your platform’s dedicated page .

GitLab Advanced Search

Mon, 01 Jan 0001 00:00:00 +0000

Overview

This page explains how to enable advanced search. Once activated, advanced search offers faster results and enhanced search capabilities.

Warning

Prior to enabling this feature, please be aware that Elasticsearch require more resources than GitLab installation requirements and review the official GitLab system requirements for Elasticsearch thoroughly.

How to Enable GitLab Container Scanning

Mon, 01 Jan 0001 00:00:00 +0000

For more information, see SCA practice

Configure your pipeline

Add the following to your .gitlab-ci.yml and push to your repository:

How to Enable GitLab DAST

Mon, 01 Jan 0001 00:00:00 +0000

For more information, see DAST practice

Configure your pipeline

Important

DAST requires a running web application accessible from the GitLab Runner, not just your local machine.

How to Enable GitLab Dependency Scanning

Mon, 01 Jan 0001 00:00:00 +0000

For more information, see SCA practice

Add to your pipeline

Add the following to your .gitlab-ci.yml and push to your repository:

GitLab Documentation

Mon, 01 Jan 0001 00:00:00 +0000

Automated Documentation with Sphinx

Create a .gitlab-ci.yml file if it does not already exist.

Add a job for generating documentation. For example:

stages:
 - build
 - docs

generate_docs:
 stage: docs
 image: sphinxdoc/sphinx
 script:
 - sphinx-build -b html source/ build/html
 artifacts:
 paths:
 - build/html

Configure your pipeline to trigger the documentation generation job on relevant events, such as merging to the main branch or tagging a release.

GitLab Merge Request

Mon, 01 Jan 0001 00:00:00 +0000

Approval rules

Create a list of users who act as code owners for specific files and require their approval before merging work.

In the root of your repository, create (if not exist) a new directory .gitlab/
Create a file CODEOWNERS
set the rules based on this exemple :

## Code Owners for a file
filename-path @username1 @username2

## Code Owners for a directory
directory-path/ @username1 @username2

## All group members as Code Owners for a file
filename @groupname

Merge Checks

To configure checks behavior :

GitLab mirroring

Mon, 01 Jan 0001 00:00:00 +0000

Overview

A pull mirror in GitLab allows you to keep a GitLab repository synchronized with a remote repository by regularly pulling in changes from the source. This is useful for keeping a copy of an external project updated within your GitLab instance, or for backing up your own repositories to a separate location.

For detailed information, refer to the official GitLab Mirror Pull .

How to set up a pull mirror

Accessing Mirror Settings

You can configure a pull mirror in two ways:

GitLab repo. clean

Mon, 01 Jan 0001 00:00:00 +0000

This guide will help you check your storage consumption in GitLab, explaining different elements that contribute to storage usage.

Check Storage Consumption in GitLab

This guide will help you check your storage consumption in GitLab, explaining different elements that contribute to storage usage.

1. Access Project Settings:

Navigate to your GitLab project.
On the right of the page, you can find project information, with the storage overview

How to Enable GitLab SAST

Mon, 01 Jan 0001 00:00:00 +0000

For more information, see SAST practice

Configure your pipeline

Add the following to your .gitlab-ci.yml and push to your repository:

How to Enable GitLab Secret Detection

Mon, 01 Jan 0001 00:00:00 +0000

For more information, see Secret Detection practice

Configure your pipeline

Add the following to your .gitlab-ci.yml and push to your repository:

GitLab secure repo

Mon, 01 Jan 0001 00:00:00 +0000

Proctecting branches

Navigate to Your Repository Settings:
- Go to your GitLab project.
- Navigate to Settings > Repository.
- Scroll down to the Protected branches and expand section.
- Select Add protected branch
Configure a Protected Branch:
- In the Protect a branch form, select or type the name of the branch you want to protect (e.g., main, develop, or prod*).
- Select values to Allowed to Merge (ex: Select Maintainers).
- Select values to Allowed to Push: (ex: Maintainers or specific trusted users).
Define more settings:

GitLab templates

Mon, 01 Jan 0001 00:00:00 +0000

Create a Description Template

Navigate to the root directory of your GitLab repository
Create a .gitlab directory if it doesn’t exist.
Inside the .gitlab directory, create the appropriate subdirectory:
- For issue templates: create issue_templates
- For merge request templates: create merge_request_templates
Inside the newly created subdirectory, create your Markdown (.md) files:
- For issue templates, examples include bug_report.md, feature_request.md
- For merge request templates, examples include Feature Merge Request.md, Bug Fix Merge Request.md

You should have a similar file structure:

GitLab tokens

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

In GitLab, tokens are used to facilitate secure access to the GitLab API, manage permissions, and automate processes. Here are the different types of tokens you might encounter:

Personal Access Tokens: These are user-specific tokens that allow you to authenticate API requests with your user account. They can be scoped to different permissions, such as read or write access to the repository.
Project Access Tokens: These tokens are designed for automated processes within a specific project. They can be used for CI/CD pipelines, allowing services to interact with the project without exposing personal credentials.
Group Access Tokens: These tokens grant access to all projects within a specific group. They are useful for situations where you want to manage permissions across multiple projects efficiently.

How to create a personal Access Token

Here are the steps you typically follow:

Jira/GitLab integration

Mon, 01 Jan 0001 00:00:00 +0000

Concept

The integration between Jira and GitLab creates a powerful synergy between project management and code development. This connection establishes bidirectional links between:

Jira items (Epics, User Stories)
GitLab activities (commits, Merge Requests)

NOTE: Creating a GitLab branch from a Jira ticket is not covered in the how-to because it requires the Jira DVCS connector, which is not yet integrated.

Use Case

From Jira

When reviewing a ticket, you have direct access to the associated code changes through links to corresponding GitLab commits or Merge Requests (MR).

Merge Requests

Mon, 01 Jan 0001 00:00:00 +0000

Objectives & Benefits

Merge requests (MRs) are a critical component in the software development life cycle (SDLC) specially in the GitLab workflow .

They allow developers to:

Propose code changes from feature branches to be merged into the main branch.
Get feedback from team members as part of code review workflows.
Enable approval and check gates before integrating changes into the main codebase.

Merge Requests improve regular collaboration and team spirit because they serve as educational moments and foster team effort.

NextGen CICD

Mon, 01 Jan 0001 00:00:00 +0000

NextGen CICD is an Inner Source project that provides a standalone catalogue of ready-to-use reusable steps and pipelines that support CI/CD best practices. Virtually every step runs in a container based on a trusted image we provide.

The objective is to speed up the lead time for a project to set up a CI/CD pipeline by using templates with the ability to customize them or create their own pipelines based on individual steps that we provide in the catalogue.

Polarion/Tests integration

Mon, 01 Jan 0001 00:00:00 +0000

Concept

Import data from automatic test execution result files to produce conformity matrixes

---
config:
 theme: neutral
 layout: elk
---
graph LR
 %% Sous-graphes
 subgraph Polarion
 R(Requirement)
 TC(Test Case)
 TR(Test Run)
 end

 subgraph Gitlab-ci
 AT(automatic tests)
 end

 %% Relations
 AT -->|"&lt;optional&gt; import"| TC
 AT -->|"import"| TR
 R --> TC
 TC --> TR
 

 class Polarion,Gitlab-ci system;
 class R,TC,TR,AT item;

Test results can be imported using two XML file formats:

JUnit file format
XML from Vivaldi (See Distributed Systems document)

JUnit-Like Format for Test Results

JUnit is a commonly used format for reporting test results in XML format. Polarion supports the import of JUnit XML reports, enabling the automatic creation or update of test runs and test results within Polarion. + This document primarily focuses on the JUnit-like format and elaborates on the structure necessary for importing into Polarion.

Python pipeline Tuto

Mon, 01 Jan 0001 00:00:00 +0000

Getting started

This Tutorial serves as an introduction to using GitLab CI/CD by creating a CI/CD pipeline for a basic Python application.

First, we’ll present an example of a standard GitLab CI/CD pipeline. Following that, we’ll explore integration with NextGen CI/CD .

To get started, we will :

Checkout the repository for a basic Python application.
Define Pipeline Stages in the .gitlab-ci.yml file.
Define jobs to be executed within each pipeline stage
Define Variables for job configurations.
Execute and monitor the pipeline.
Explore triggers to automate pipeline execution based on events.

Checkout the Python Repository

The example application consists of a basic Python code that converts km/h into MPH (US).

Registry

Mon, 01 Jan 0001 00:00:00 +0000

Overview of Registry

The GitLab Registry is a private registry for storing and managing Docker images and other formats.

It’s built into GitLab. This makes it easy to integrate container image management into your CI/CD workflows.

Store Docker images: Securely store your Docker images within your GitLab project.
CI/CD integration: Build and push images as part of your CI/CD pipelines.
Access control: Control who can access and use your images.

✅ Use the GitLab Registry to manage your container images and streamline your deployment process.

Repo Mirroring

Mon, 01 Jan 0001 00:00:00 +0000

Disclaimer

Each platform choose their limitation to use this feature. Refer to Service per platform .

Software Factory recommends that only platform admins have the privilege to create Mirrors.

Runners

Mon, 01 Jan 0001 00:00:00 +0000

GitLab Runners are essential components of GitLab’s CI/CD system. While your project’s pipeline defines what should be done (build, test, deploy steps), runners are the agents responsible for where and how those jobs are actually executed.

They enable teams to automate processes, enforce consistent environments, and scale their software delivery.

Runners execute your CI/CD job from the following options:

Instance Runners: aka Shared runners Available to all projects in a GitLab instance. For some security reason they may not be available on all platforms . On TDP C2 ,they are provided as a free managed service for quick testing or prototyping.
Managed Dedicated Runners: a managed service that guarantees the best quality of life, freeing time for developpers to focus on their projects.
Self-managed Dedicated Runners: Deploy and manage your own project or group runners on your infrastructure.

Runner Architecture

Runners are installed processes (services or daemons) that interact with the GitLab server.

Static Application Security Testing (SAST)

Mon, 01 Jan 0001 00:00:00 +0000

GitLab Ultimate provides a SAST tool already integrated in your development environment. It helps developers identify security issues in their code during the development process, allowing them to fix vulnerabilities before they reach production.

The SAST scanner uses analyzers to detect vulnerabilities in source code. Currently, there are six officially supported analyzers:

GitLab Advanced Security: analyzer designed to discover vulnerabilities by performing cross-function and cross-file taint analysis
Semgrep: standard static scanner for most programming languages
Kubesec: designed to scan Kubernetes manifests and Helm Charts
sobelow: designed to scan Elixir applications
spotbug: designed to scan Java and Groovy applications
pmd-apex: designed to scan Apex code used in Salesforce applications

When the SAST scanner is integrated into your pipeline, it will select the scanner that best suits your repository.

Software Composition Analysis (SCA)

Mon, 01 Jan 0001 00:00:00 +0000

GitLab provides Software Composition Analysis capabilities through two CI-integrated tools: Dependency Scanning and Container Scanning.
Both require GitLab Ultimate, which is included in the Software Factory at no additional cost.

For background on SCA concepts, see the SCA practice page.

Inventory Coverage

The table below maps GitLab SCA’s capabilities to the analysis approaches defined in the SCA practice.

Dependency Scanning parses language-specific lockfiles to build the dependency graph and produces a Source SBOM in CycloneDX format. It currently relies on the Gemnasium-based analyzer, which is deprecated by GitLab but remains the only generally available option. A newer SBOM-based analyzer is in development but not yet GA. See Supported languages and package types for the full list of supported ecosystems.

Secret Detection

Mon, 01 Jan 0001 00:00:00 +0000

Code may use secrets to integrate with external services, such as webservices or databases. These secrets can take various forms, including passwords, API keys, and SSH keys.

If this sensitive information is committed to a source code repository, it may become accessible to anyone who accesses the repository, posing a significant security risk.

To mitigate this risk, GitLab provides a Secret Detection tool that scans your codebase for sensitive information (check [full list of supported secret types]) and alerts you to potential security issues.

Secure your Repository

Mon, 01 Jan 0001 00:00:00 +0000

Securing your repository is essential to maintain the integrity and confidentiality of your code base. This guide covers the practices for implementing robust access controls, enforcing branch protection, securing secrets, and using groups efficiently within GitLab.

Implement Access Controls

Establishing strong access controls is fundamental for repository security.

Properly configured permissions ensure only authorized individuals can perform sensitive actions like pushing code, merging changes, or altering project settings.

Security Policies

Mon, 01 Jan 0001 00:00:00 +0000

You can automate vulnerability management and enforce requirements on merge requests, security scans, and pipeline execution with policies.

Merge Request Approval Policies

GitLab enforces security requirements at the merge request level, not at the pipeline level. When a policy is triggered, GitLab automatically adds required approvers to the MR — the pipeline itself continues to pass, but the merge is blocked until the required approvals are obtained.

Shift Left Testing

Mon, 01 Jan 0001 00:00:00 +0000

This guide provides a definition of Shift Left, outlines its benefits, explains how to implement it and presents some pitfalls to avoid.

Definition

Shift Left refers to the practice of moving testing activities earlier in the software development process.

Instead of waiting until the end of the development cycle to test for defects, Shift Left advocates for testing activities to begin as soon as possible.

This approach is aligned with Agile and DevOps methodologies, promoting ongoing testing throughout the development lifecycle.

Teapot Tuto

Mon, 01 Jan 0001 00:00:00 +0000

Overview

In this tutorial, you’ll learn how to create and deploy a first app from Software Factory C2 to a TDP C2 K8SaaS (the managed Azure Kubernetes Service offered by the TDP C2).

Prerequisites

Enroll your user account in a TDF account (billing account).
Request a DevSecOps offer (needed for GitLab and Artifactory) or Request a DevSecOps InnerSource access if you are only working on InnerSource projects. DevSecOps InnerSource is sponsored by TGS/TCE (Thales Corporate Engineering)
Subscribe to IaaS Discover offer (K8SaaS)

TIPS: If you’re stuck with Multi-Factor Authentication (MFA), you can check this documentation or request a reset .

Technical Documentation

Mon, 01 Jan 0001 00:00:00 +0000

Practices for writing technical documentation

Here are some best practices for writing clear and effective technical documentation:

Know Your Audience: Understand who will be reading the documentation (developers, end-users, stakeholders) and tailor the content to their level of expertise and needs.
Clear Structure and Organization: Use a logical structure with clear headings and subheadings. Maybe include a table of contents for easier navigation, especially for lengthy documents.
Clarity and Conciseness: Break down complex concepts into manageable sections or steps.
Consistency: Maintain consistent terminology, tone, and style throughout the document. Also use a consistent format for headings, code blocks, and lists.
Code Examples: Include code snippets to demonstrate concepts and provide real-world examples.
Maintain and Update: Regularly review and update the documentation to keep it current with any changes in the project or software.

Useful links

Presentation of Diatixis

The Diataxis framework is a comprehensive approach to organizing technical documentation.

Traceability, conformity and conformance

Mon, 01 Jan 0001 00:00:00 +0000

Overview & Expected Benefits

Software engineering projects that work with system engineering face key challenges in communication, development processes, and compliance with specifications.

Five specific areas of focus typically arise and require careful attention.

Specification Transfer and Collaborative Development Processes

One of the primary challenges is the effective transfer of specifications from the system engineering team to the software development team. Clear communication and collaborative documentation are essential to ensure a mutual understanding of requirements. Misinterpretations at this stage can lead to significant setbacks later in the project. In a co-engineering environment, collaboration between system and software teams is essential. Both teams must engage in parallel activities throughout the development phase. This means aligning their engineering efforts and providing real-time feedback to ensure that the project adheres to system specifications.

Vulnerability Report

Mon, 01 Jan 0001 00:00:00 +0000

After analyzing your source code with [SAST], [SCA], and/or your application with [DAST], you can check scan results in the Vulnerability report, available at the group and project level.

To access, navigate to Secure > Vulnerability report .

Tip

At the group level, in addition to the vulnerability report, there is a Security Dashboard that provides an overview of the group’s security posture. To access it: in the left sidebar, select Secure > Security Dashboard .