Skip to content

Using Jenkins for Building and Deploying Packages

IMPORTANT: This is an IA-generated version waiting for approval.

Overview

Purpose

This documentation explains how Jenkins is used within our infrastructure to automate the creation and deployment of software packages. It provides a standardised workflow for ensuring consistent delivery of changes across different environments.

Scope

This guide covers: - Concepts of packages, builds, and deployments in the Jenkins context. - Operational steps for building and deploying packages. - Versioning conventions and artefact tracking. - Verification and troubleshooting for common pipeline issues. - High-level release identification for non-operational users.

Audience

  • Primary: TSQA and testers responsible for triggering builds, deploying to test environments, and verifying changes.
  • Secondary: Business Process (BP) users who need to understand release versions and change contents.

Conceptual Background

A package is a bundled, distributable unit containing all components necessary for a specific service or application version.

  • Building a package: The process of converting source code into a deployable package (e.g., .tar.gz, .jar, or Docker image).
  • Deploying a package: The automated process of installing a specific package version onto a target system and activating it.
  • Versioning: Every build is assigned a unique version identifier, allowing for precise tracking of changes and rollbacks.

For canonical definitions of these terms, refer to Introduction into Deployment.

Prerequisites

Access Requirements

  • Connectivity to the internal network (VPN or office network).
  • Active user account in the internal identity provider.

Permissions

  • Read: Required for all users to view job status and logs.
  • Build: Required for TSQA/Testers to trigger package creation.
  • Deploy: Required for TSQA/Testers to initiate deployments to target environments.

[QUINTESSENCE-SPECIFIC] Describe: The specific procedure for requesting Jenkins access, including which Jira project or team to contact.
Owner: IT Infrastructure Team
Source of truth: Internal Access Policy
Required confirmation by: Team Lead / System Admin
Notes: N/A

Architecture Diagram

graph LR
    User((User))

    subgraph "Source"
        GL[GitLab]
    end

    subgraph "Automation"
        JK[Jenkins]
    end

    subgraph "Artefacts"
        Repo[Package Repository]
    end

    subgraph "Environments"
        Target[Target Environment]
    end

    User -->|1. Trigger Build| JK
    JK -->|2. Fetch Code| GL
    JK -->|3. Create Package| Repo
    User -->|4. Trigger Deploy| JK
    JK -->|5. Install Package| Target

[QUINTESSENCE-SPECIFIC] Describe: A diagram showing the integration between GitLab (Source), Jenkins (CI/CD), Nexus/Packages Server (Artefacts), and the target environment hosts.
Owner: Infrastructure Architects
Source of truth: System Architecture Docs
Required confirmation by: Lead Architect
Notes: N/A

Configuration Details

Common Parameters

When triggering a build or deployment, the following parameters are typically used: - BRANCH_NAME: The source branch in GitLab (e.g., main, develop, or a feature branch). - VERSION_SUFFIX: Optional label added to the version string (e.g., RC1, beta). - TARGET_ENV: The destination environment for deployment (e.g., test, dev, prod).

[QUINTESSENCE-SPECIFIC] Describe: List of any mandatory internal environment variables or specific credentials required for pipeline execution.
Owner: DevOps Team
Source of truth: Jenkins Credentials Store / Global Config
Required confirmation by: DevOps Lead
Notes: Credentials are handled via Jenkins secrets; users do not need to provide them manually.

Step-by-Step Setup

Building a Package (TSQA & Testers)

  1. Log in: Access the Jenkins dashboard at [QUINTESSENCE-SPECIFIC-URL].
  2. Navigate: Locate the relevant project folder and pipeline.
  3. Trigger Build: Click Build with Parameters in the left sidebar.
  4. Configure:
    • Select the correct BRANCH_NAME.
    • Ensure the VERSION settings align with the release plan.
  5. Execute: Click the Build button.
  6. Monitor: Follow the progress in the Build History or via the Blue Ocean interface.

Deploying a Package (TSQA & Testers)

  1. Locate Deploy Job: Navigate to the deployment pipeline for your target environment.
  2. Configure Parameters:
    • Select the Package Version generated in the build step.
    • Confirm the Target Environment.
  3. Run Deployment: Click Build.
  4. Verify Console Output: Watch the logs to ensure the deployment scripts complete successfully.

Identifying Releases (BP Users)

How Releases are Installed New releases of ASGARD (ASG) and MIDGARD (MG) are installed through an automated process managed by Jenkins. This process is triggered by the TSQA team after a package has been successfully built and verified. No manual file copying or server configuration is required by end users; the system handles the distribution and activation of the new software version on the target environments.

graph LR
    TSQA((TSQA Team))
    Jenkins[Jenkins Automation]
    Env[Target Environment]

    TSQA -->|1. Triggers Update| Jenkins
    Jenkins -->|2. Installs Software| Env
    Env -->|3. New Version Active| TSQA

Tracking Changes Business Process users can identify which package contains their required changes by: - Checking the GitLab commit history linked in the Jenkins build metadata. - Reviewing the Change Log generated automatically in the build summary. - Cross-referencing the Package Version with the release notes in Jira.

Validation & Testing

Post-Build Checks

  • Artefact Availability: Verify the new package appears in the Packages Server or Nexus.
  • Log Review: Check for "SUCCESS" at the end of the console output.

Post-Deployment Checks

  • Service Reachability: Ping the application URL or check the health endpoint.
  • Version Verification: Confirm the deployed version matches the intended build number (usually visible in the application footer or /version API).
  • Functional Smoke Test: Perform basic actions in the UI/API to ensure core stability.

Troubleshooting

Issue Potential Cause Resolution
Build fails during 'mvn deploy' Nexus connectivity or permissions Contact the DevOps team; check Nexus status.
Deployment fails with 'SSH Error' Target host unreachable or key mismatch Verify target server is up; check SSH Host List.
"Access Denied" in Jenkins Missing permissions Request the appropriate role (Build/Deploy) from IT.

Security Considerations

  • All Jenkins traffic is encrypted via HTTPS.
  • Build agents run in isolated Docker containers (Dind) to prevent host compromise.
  • Production deployments require a manual approval step in the pipeline.

Maintenance

[QUINTESSENCE-SPECIFIC] Describe: Maintenance schedule for the Jenkins controller and worker nodes.
Owner: System Administration
Source of truth: Infrastructure Maintenance Log
Required confirmation by: SysAdmin
Notes: N/A

Change Log

Version Date Description Author
1.0 2026-03-17 Initial creation aligned with 07_template.md opencode

Changelog

Date Author Message
2026-03-17 aresnikowa docs: enable mermaid diagrams and update jenkins guide