GitLab CI Guide

GitLab CI/CD makes running NeoSpaxe ridiculously clean because GitLab executes jobs directly inside container images—meaning you don’t even need Docker-in-Docker (dind). You just point image: at ghcr.io/toolboxanonymous/neospaxe-engine:latest and invoke /engine/src/image/main.mjs.

1. Configure GitLab CI/CD Variables

In your GitLab project, go to Settings → CI/CD → Variables and add these variables (check Mask variable for secrets):

• NEOSPAXE_LICENSE_KEY — Your Dodo Payments license key.
• AWS_ACCESS_KEY_ID — Your AWS IAM access key ID.
• AWS_SECRET_ACCESS_KEY — Your AWS IAM secret access key.
• AWS_REGION — Your target AWS region (e.g., us-east-1).

2. Add the Preview Job to .gitlab-ci.yml

Here is the canonical GitLab CI configuration from our engine examples (engine/workflows/gitlab-ci.yml):

deploy-preview:
  stage: deploy
  image: ghcr.io/toolboxanonymous/neospaxe-engine:latest
  rules:
    - if: $CI_PIPELINE_SOURCE == "web"
  variables:
    NEOSPAXE_STAGE: "preview"
    NEOSPAXE_ACTION: "deploy"
  script:
    - export NEOSPAXE_LICENSE_KEY="$NEOSPAXE_LICENSE_KEY"
    - export NEOSPAXE_API="https://neospaxe.com/functions/v1/neospaxe-engine"
    - export NEOSPAXE_WORKSPACE="$CI_PROJECT_DIR"
    - node /engine/src/image/main.mjs

How to Trigger From the GitLab Web UI

1. In GitLab, navigate to Build → Pipelines and click Run pipeline.
2. Override NEOSPAXE_STAGE with your branch or feature name (for example, mr-88 or feat-search).
3. Set NEOSPAXE_ACTION to deploy to spin up or update the stack, or remove to tear it down when you’re finished.

3. Adding a Dedicated Remove Job (Or Merge Request Environments)

If you prefer separate manual buttons in your Merge Request pipeline for deploying and stopping environments, add a matching remove-preview job:

remove-preview:
  stage: deploy
  image: ghcr.io/toolboxanonymous/neospaxe-engine:latest
  rules:
    - if: $CI_PIPELINE_SOURCE == "web"
  variables:
    NEOSPAXE_STAGE: "preview"
    NEOSPAXE_ACTION: "remove"
  script:
    - export NEOSPAXE_LICENSE_KEY="$NEOSPAXE_LICENSE_KEY"
    - export NEOSPAXE_API="https://neospaxe.com/functions/v1/neospaxe-engine"
    - export NEOSPAXE_WORKSPACE="$CI_PROJECT_DIR"
    - node /engine/src/image/main.mjs