Skip to content

Upgrading GitFlic from Version 3.x.x to 4.x.x

Important Notice

If you're using GitFlic 2.x.x, first follow the 2.x.x to 3.x.x migration guide before proceeding with this upgrade.

Pre-Upgrade Requirements

Before upgrading to GitFlic 4.0.0, create backups of: - PostgreSQL and Redis/KeyDB databases - Static data (img, repo, cicd, registry, releases directories) - SSH server keys (/opt/gitflic/key.pem)

Overview

Version 4.0.0 introduces critical architectural changes that break backward compatibility. This guide addresses migration challenges from 3.x.x to 4.x.x.

For upgrade assistance, contact support@gitflic.ru.

Key Changes in 4.0.0

  • New RSA key handling for package signatures and auth tokens (requires gitflic.vault.cert.publicKey and gitflic.vault.cert.privateKey)
  • Mandatory User UID field for LDAP configurations
  • Revised SAML connection signature handling
  • CI/CD agents now execute jobs in single context by default
  • Kubernetes manifests replaced with Helm Charts
  • Revised Docker container deployment approach

Upgrade Process

  1. Extract RSA keys using keys-retriever.jar: 

    java -jar keys-retriever.jar /path/to/application.properties
    This generates private_key.pem and public_key.pem in the current directory.

  2. Stop GitFlic and update application.properties: 

    gitflic.vault.cert.publicKey=/path/to/public_key.pem
gitflic.vault.cert.privateKey=/path/to/private_key.pem

  3. Replace gitflic.jar with the 4.0.0 version and restart.

Docker Compose Changes

  • New version uses Docker volumes instead of direct filesystem mounts
  • Full data migration required when using default compose files

Enterprise Edition

For enterprise users: 1. Download gitflic-server-ee.tar from your account 2. Import image: 

docker load -i gitflic-server-ee_<version>.tar
3. Update .env: 
GITFLIC_IMAGE=gitflic-server-ee:<version>

  1. Extract RSA keys: 

    docker pull registry.gitflic.ru/project/gitflic/keys-retriever/keys-retriever:1.0.0
CONTAINER_ID=$(docker run -d --env-file ./ENV --network gitflic_network registry.gitflic.ru/project/gitflic/keys-retriever/keys-retriever:1.0.0)
docker cp $CONTAINER_ID:/opt/key-retriever/private_key.pem ./
docker cp $CONTAINER_ID:/opt/key-retriever/public_key.pem ./

  2. Stop GitFlic 3.x.x containers

  3. Create volumes and migrate data: 

    docker volume create gitflic_cert
sudo cp *.pem $(docker volume inspect gitflic_cert -f '{{.Mountpoint}}')
cp -rT old_path/data/* $(docker volume inspect new_volume -f '{{.Mountpoint}}')

  4. Start GitFlic 4.x.x and verify data integrity

Post-Upgrade Configuration

LDAP Changes

Version 4.0.0 requires configuring a permanent User UID attribute. The system auto-populates this field from the login attribute, but administrators should manually set it to a true unique identifier (e.g., uid, employeeNumber).

SAML Changes

New SAML signature verification uses SHA1 fingerprints. The Verify metadata certificate option is disabled by default. When enabled, ensure the SHA1 certificate hash field is populated.

CI/CD Agent Updates

Execution Context Change

Version 4.0.0 agents execute jobs in single context by default. To revert to previous behavior, add to application.properties: 

runner.enableExecScriptsInSession=false

Automatic translation!

This page has been automatically translated. The text may contain inaccuracies.