CI/CD

1. Overview

Our RPA development and release process is based on an integrated CI/CD pipeline using the Eagle GitLab instance and the RPA Release VMs.

The process is divided into two main phases:

CI — Continuous Integration: handled by GitLab pipelines and defined in the .gitlab-ci.yml file.
CD — Continuous Deployment: handled automatically by a deployment script running on each Release VM.

The overall process is:

Developer commits and pushes code → GitLab CI builds and pushes Docker images → Release VM detects the new image → Existing container is stopped → Latest image is pulled → Container is restarted

The process is designed to be fully automated, but this guide also explains the main troubleshooting and fallback procedures.

2. Continuous Integration (CI)

2.1 The `.gitlab-ci.yml` file

The CI process is defined by the .gitlab-ci.yml file located in the repository.

There are several possible CI configurations depending on the type of project and release:

Standard configuration — Single-release projects

This is the standard configuration used for approximately 90% of our developments, typically:

Backend-only (BE)
Standalone applications

In this scenario, the CI pipeline performs the standard build and image publication process.

Mixed release configuration

Some projects require separate or coordinated releases involving:

Backend (BE)
Frontend (FE)

These projects use a variant of the standard .gitlab-ci.yml configuration to manage the different components and their respective images.

Special cases

Some projects may require custom CI configurations due to particular architectural or deployment requirements.

In all cases, the general principles described below remain the same:

Build the application/container image.
Tag the image.
Push the image to the internal GitLab Container Registry.
Make the image available for the CD process.

3. CI Build Process

The CI pipeline builds the Docker image using a TOKEN build argument.

The token is required when the application needs to install private packages hosted on our GitLab instance.

Conceptually, the build process is:

Source Code
    ↓
GitLab CI Pipeline
    ↓
Docker Build
    ↓
Build with TOKEN
    ↓
Docker Image
    ↓
Tag Image
    ↓
Push to Internal Container Registry

The TOKEN is therefore used during the build process to allow access to private dependencies.

4. Image Tagging Strategy

For each successful CI pipeline, the image is pushed to the repository's internal Container Registry using two tags.

The tags are conceptually:

latest-ENV

and

ENV-COMMIT-TITLE

Where:

ENV identifies the target environment.
COMMIT-TITLE represents the commit version/title used to identify the specific build.

For example, depending on the project and environment, the resulting tags could conceptually look like:

latest-dev
dev-1.2.3

or:

latest-test
test-1.2.4

The two tags serve different purposes:

latest-ENV is the moving tag used by the automated CD process.
ENV-COMMIT-TITLE provides a specific, traceable version of the image.

The CD process always pulls the image associated with the relevant latest environment tag.

5. The Three Main Branches and Environments

The CI pipeline is triggered by changes to the three main branches:

Git Branch	Target Environment
`dev`	Development
`test`	Test
`main`	Main/Production

Therefore, the branch receiving the commit determines the target environment.

Conceptually:

dev
 ↓
Development VM

test
 ↓
Test VM

main
 ↓
Main/Production VM

Each branch therefore represents a deployment environment.

6. Critical Point: The Commit Version

The most important element to monitor is the commit that triggers the pipeline.

In particular, you must pay attention to:

The merge commit, when changes are merged into the target branch.
The latest commit, when code is pushed directly to the target branch.

This commit determines the version used to build and identify the Docker image.

The version must follow Semantic Versioning (SemVer) best practices.

A valid version should follow the general format:

MAJOR.MINOR.PATCH

For example:

1.0.0
1.2.3
2.5.1

If the version extracted from the commit is not valid according to the expected SemVer format, the CI pipeline will fail.

Developer checklist before merging

Before merging into one of the three deployment branches, verify that:

The commit version is valid.
The version follows the expected SemVer format.
The merge commit will result in a valid version.
The pipeline is expected to build the correct environment image.

Important: A CI failure caused by an invalid version is normally not a Docker or infrastructure problem. Check the commit/version first.

7. Verifying the CI Result

After the CI pipeline completes successfully, the generated images are available in the repository's Container Registry.

To verify them:

Open the relevant GitLab repository.
Go to:
Deploy → Container Registry
Locate the images generated by the latest pipeline.
Verify that the expected tags are present.

You should normally find the two images/tags generated by the CI process:

latest-ENV
ENV-COMMIT-TITLE

This is the first place to check when verifying that CI has completed correctly.

8. GitLab CI Runners

The CI pipeline relies on the availability of GitLab Runners.

A Runner is a service dedicated to executing CI jobs, such as:

Building the Docker image.
Installing dependencies.
Tagging the image.
Pushing the image to the internal Container Registry.

The CI pipeline cannot execute correctly if the required Runner is unavailable.

If the Runner is unavailable

If the pipeline cannot start or execute because the Runner is unavailable:

Verify that the problem is related to Runner availability.
Report the issue to the DevOps team through the designated ticketing channel.
Include the relevant:
- GitLab project.
- Pipeline/job.
- Branch.
- Error message.
- Timestamp.

9. CI Fallback: Manual Local Build and Push

If the automated CI process is temporarily unavailable, it is possible to bypass the automatic pipeline.

The developer can manually perform the same operations locally:

Build
  ↓
Tag
  ↓
Push

The objective is to reproduce the operations normally performed by GitLab CI:

Build the Docker image.
Use the required build arguments, including TOKEN when private packages are required.
Apply the correct environment tag.
Apply the version-specific tag.
Push both tags to the internal GitLab Container Registry.

The manual process should therefore produce the same result as the automated CI pipeline.

Important: Manual execution should be considered a workaround for CI infrastructure issues, not the standard development workflow. The normal process remains the automated GitLab CI pipeline.

10. Continuous Deployment (CD)

The CD process is fully automated and is handled by a deployment script installed on every RPA Release VM.

The script runs periodically, approximately every 10 seconds.

The overall process is:

Every ~10 seconds
        ↓
Check running containers
        ↓
Find containers with:
cloud.eagleprojects.autocd.enable=true
        ↓
Stop/remove the relevant container
        ↓
Pull the latest image
        ↓
Start the container again

The deployment mechanism is based on the Docker label:

cloud.eagleprojects.autocd.enable=true

Only containers with this label are managed by the automated CD mechanism.

11. How the Automatic CD Works

At a high level, the CD script performs the following operations.

Step 1 — Identify managed containers

The script lists the currently running containers and identifies those with the label:

cloud.eagleprojects.autocd.enable=true

Step 2 — Stop the existing container

The container associated with the deployment is brought down.

Step 3 — Pull the latest image

The script pulls the most recent image associated with the configured environment tag.

The deployment process uses the relevant latest tag.

For example, conceptually:

latest-dev
latest-test
latest-main

The exact tag depends on the Release VM and its configured environment.

Step 4 — Start the container

The container is started again using the newly pulled image.

Therefore, the expected deployment flow is:

New commit
    ↓
GitLab CI
    ↓
New Docker image
    ↓
Push latest-ENV
    ↓
Release VM detects new image
    ↓
Container down
    ↓
Image pull
    ↓
Container up
    ↓
New version running

Under normal conditions, no manual deployment action is required.

12. CD Troubleshooting

Although CD is fully automated, unexpected problems can occur.

The most important symptom to monitor is:

The CI pipeline completed successfully, but the container is not restarted with the new image.

If this happens, first allow the system some time to complete the automatic deployment.

Recommended waiting time

After a successful CI pipeline:

Wait approximately 5 minutes.
Check whether the expected container has been restarted.
Verify whether the new version is running.

If the container has not been restarted after approximately 5 minutes, proceed with the workaround below.

13. CD Workaround: Restart the Service via Ansible

If the automatic CD process does not restart the container, the recommended workaround is to restart the relevant deployment service using Ansible.

The default Ansible playbooks currently used by our deployment tasks perform the same basic operation as the automatic CD process:

Down
  ↓
Pull
  ↓
Up

Therefore, the Ansible-based workaround forces the same deployment sequence manually.

The procedure is:

Confirm that the GitLab CI pipeline completed successfully.
Confirm that the expected images are visible in:
Deploy → Container Registry
Wait approximately 5 minutes.
Check that the container has not been automatically restarted.
Restart the relevant service using Ansible.
Verify that the container is:
- Running.
- Using the expected image.
- Using the expected environment tag/version.
Verify the application's functionality.

The two default playbooks currently used by the deployment tasks available as of August 2026 perform the same core operation:

Down → Pull → Up

14. End-to-End Troubleshooting Checklist

When a new release does not appear on the target VM, follow this order.

Step 1 — Check the commit

Verify:

Which commit triggered the pipeline?
Was it a merge commit?
Was it pushed directly to the branch?
Is the version valid SemVer?

Step 2 — Check the GitLab CI pipeline

Verify:

Did the pipeline start?
Did the Runner execute the job?
Did the build complete successfully?
Did the image push complete successfully?

Step 3 — Check the Container Registry

Go to:

Deploy → Container Registry

Verify that both expected tags are available:

latest-ENV
ENV-COMMIT-TITLE

Step 4 — Check the Release VM

If CI is successful, wait approximately 5 minutes and verify whether the container has been restarted automatically.

Step 5 — Check the CD mechanism

If the container has not restarted:

Verify that the container is managed by the CD mechanism.
Check that it has the label:

cloud.eagleprojects.autocd.enable=true

Step 6 — Use the Ansible workaround

If the container is still not restarted:

Ansible
  ↓
Down
  ↓
Pull
  ↓
Up

Step 7 — Contact DevOps

If the problem persists, contact the DevOps team through the standard ticketing channel.

Include as much information as possible:

GitLab project.
Branch.
Commit/version.
Pipeline URL or identifier.
CI error, if any.
Container Registry status.
Release VM.
Container name.
Relevant logs or error messages.
Steps already performed.

15. Quick Reference

Normal release flow

1. Develop
   ↓
2. Commit
   ↓
3. Merge/push to dev, test or main
   ↓
4. GitLab CI starts
   ↓
5. Docker image is built
   ↓
6. Private packages are installed using TOKEN, if required
   ↓
7. Image is tagged
   ↓
8. Two tags are pushed to GitLab Container Registry
   ↓
9. Release VM detects the updated latest-ENV image
   ↓
10. Existing container is stopped
   ↓
11. Latest image is pulled
   ↓
12. Container is restarted
   ↓
13. New version is running

If CI fails

Check commit/version
        ↓
Check SemVer
        ↓
Check Runner availability
        ↓
Contact DevOps if Runner is unavailable
        ↓
Use local build/tag/push as a temporary workaround if necessary

If CD does not deploy

CI successful?
    ↓
Yes
    ↓
Images available in Container Registry?
    ↓
Yes
    ↓
Wait ~5 minutes
    ↓
Container restarted?
    ├── Yes → Done
    └── No
          ↓
    Restart service via Ansible
          ↓
       Down/Pull/Up
          ↓
    Still not working?
          ↓
    Contact DevOps

16. Key Takeaways

GitLab CI is responsible for building and publishing Docker images.
The .gitlab-ci.yml defines the CI process.
The standard configuration is used for most BE/standalone projects.
BE/FE projects and special cases may use dedicated .gitlab-ci.yml variants.
Private GitLab packages are installed during the build using the TOKEN build argument.
The CI process pushes two tags to the internal Container Registry:
- latest-ENV
- ENV-COMMIT-TITLE
The three main branches are:
- dev
- test
- main
The commit that triggers the pipeline is critical because it determines the image version.
The version must comply with the expected SemVer format.
A successful pipeline makes the images available under Deploy → Container Registry.
CI depends on the availability of GitLab Runners.
If the Runner is unavailable, contact DevOps through the designated ticketing channel.
As a temporary workaround, the CI operations can be performed manually from a local environment.
CD is fully automated and runs on every Release VM.
The CD script runs approximately every 10 seconds.
Containers must have the label cloud.eagleprojects.autocd.enable=true to be managed automatically.
The automated deployment follows the basic sequence:
Down → Pull → Up
If the container is not restarted within approximately 5 minutes, use the Ansible-based workaround.
If the issue persists, contact DevOps through the standard support channel.