The Qovery Engine is an abstraction layer to deploy stateless and stateful applications on any Cloud providers. It also bootstraps Kubernetes clusters and mandatory elements (network) for clients.
Qovery engine is able to deploy complete clusters environments and deploy client's applications inside a deployed clusters.
Files to make images that should run for builds or Qovery application run.
Qovery binary application
In order to get your next MR validated, linter, fmt etc...there is a pre commit hook we suggest to install:
./helper.sh install_hook
The pre-commit hook runs ./helper.sh lint (fast lint).
For the full integration-feature clippy matrix, run:
mise run lint-matrix
```shell TERRAFORM_VERSION=$(grep 'TERRAFORM_VERSION' docker/bin_versions | cut -d= -f2 | tr -d '"') OS=$(uname -s | tr '[:upper:]' '[:lower:]') ARCH=$(uname -m | sed 's/x86_64/amd64/;s/arm64/arm64/')
curl -fsSL "https://releases.hashicorp.com/terraform/${TERRAFORM_VERSION}/terraform_${TERRAFORM_VERSION}${OS}${ARCH}.zip" -o /tmp/terraform.zip sudo unzip -o /tmp/terraform.zip -d /usr/local/bin/ && rm /tmp/terraform.zip
# Ensure /usr/local/bin is in your PATH (add to ~/.zshrc or ~/.bashrc if missing) export PATH="$PATH:/usr/local/bin" ```
LIB_ROOT_DIR and WORKSPACE_ROOT_DIR variableexport lib_root_dir="<path-to-engine-repo>/engine/lib-engine/lib/"
export WORKSPACE_ROOT_DIR="<up-to-your-preferences>"
LIB_ROOT_DIR: The absolute path of the engine's lib folderWORKSPACE_ROOT_DIR: The absolute path to the location where .qovery-workspace folder will be located, this folder contains the rendered config
Run cargo
cargo run --package app --bin engine
TERRAFORM_VERSION.To generate a new Engine image version, you have to use Gitlab and GitHub:
Note: naming image tags is made of the first 7 chars Github commit id + a dash + 7 first chars Gitlab commit id
2-deploy-qovery-infra-engines-prod3-dry-run-deploy-prod-clusters4-ai-check-prod-clusters runs automatically — review its findings before proceedingqovery admin cluster deploy --parallel-run 50 --filters IsProduction=true --execution-mode on-the-fly --disable-dry-run2-dry-run-deploy-dev-clusters3-ai-check-dev-clusters runs automatically — review its findings before proceedingqovery admin cluster deploy --parallel-run 50 --filters IsProduction=false --execution-mode on-the-fly --disable-dry-runCreate a branch whose name starts with hot-fix (the build jobs gate on $CI_COMMIT_BRANCH =~ /^hot-fix/), i.e:
hot-fix-staging for staging: useful if we don't want some commits already merged in main
hot-fix-prod for prod: the branch should be based on last prod tag / commitgit co -b hot-fix-staging
git add .
git commit
git push origin HEAD:hot-fix-staging
Once the target branch has been pushed, a branch pipeline should be created with the following jobs:
release-image
⚠️ Do not open a merge request for this branch. An MR creates a
merge_request_eventpipeline where$CI_COMMIT_BRANCHis unset, socreate-multi-arch-imageis skipped — and without it the plainengine:<sha>image is never built, which makes the laterdocker-tagjob fail withengine:<sha>: not found.
create-multi-arch-image to finish (it pushes engine:<sha>), then push a tag on the HEAD of the target branchsh
git tag vX.Y.X
git push origin vX.Y.X
Once the tag has been pushed, a new pipeline should be created with the jobs we use for regular release:
docker-tag
...
Trigger the necessary jobs to deploy either the staging or the production infra engines
After each dry-run, Claude automatically reviews the Terraform and Helm plan diffs across all clusters and flags anything worth attention before the actual deploy. It is not meant to replace human review but to assist it and reduce the risk of missing something.
Under the hood, scripts/ci_release_ai_check.py fetches the diff logs from Loki for each cluster, normalizes sensitive data (UUIDs, ARNs, IPs, account IDs), and sends the Terraform/Helm diffs to Claude for analysis. Findings are returned as structured JSON and categorized by severity (critical, review, info). The job is non-blocking (allow_failure: true) — always review its output before proceeding to the actual deploy.
TODO
TODO
TODO
Note: Make sure LIB_ROOT_DIR and WORKSPACE_ROOT_DIR are set.
gcloud auth logingcloud components install gke-gcloud-auth-plugincargo nextest run --features test-gcp-infra -E 'test(create_and_destroy_gke_cluster_in_europe_west_10)' --no-capture
create_and_destroy_eks_clustercargo nextest run --features test-aws-infra -E 'test(create_and_destroy_eks_cluster)' --no-capture
$WORKSPACE_ROOT_DIR/<Excution date>/bootstrap/<Cluster-name>/terraform
e.g: ~/.qovery-workspace/2026-04-02T09-52-18-819264-00-00/bootstrap/zf03426ac/terraform./helper.sh get_connection_details```shell script RUST_LOG=info LIB_ROOT_DIR=~/qovery-engine/lib WORKSPACE_ROOT_DIR=~/.qovery-workspace cargo test --package qovery-engine --test aws_environment deploy_a_working_development_environment_with_all_options_on_aws_eks -- --exact --nocapture
## Add a new test
How to add a test in a fast or long process? Simply add "#[ignore]" as a test annotation (I know it's not really convenient to get it, but it's how it works in Rust). If the annotation is missing, it will be considered as a fast test.
# Debug
If you have a json context, and you want to deploy for investigation, you need to set 2 environment variables:
```bash
DEPLOY_FROM_FILE=<path_tojson_file>
DEPLOY_FROM_FILE_KIND=<env|infra> # choose between infra (infrastructure deployment) and env (environment deployment)
RUST_LOG=qovery_engine=debug env variableUpdate the rust-toolchain file with the new version. Example of content:
1.92.0
Then create a PR and, build the CI image with the new toolchain version with the build-engine-ci-image pipeline job.
Once the pipeline is done, you can update the gitlab-ci.yml with the new image version, them
$ claude mcp add engine \
-- python -m otcore.mcp_server <graph>