Skip to main content

Review

Runs project-owned scripts to create and stop a GitLab review environment.

Use this component when the application already has executable start and stop scripts in the repository. The component wires those scripts into GitLab environments, adds on_stop, and keeps both jobs on the same resource_group so start and stop actions do not overlap.

Basic review app​

Create executable scripts in the application repository:

mkdir -p scripts
cat > scripts/start-review.sh <<'SH'
#!/usr/bin/env bash
set -euo pipefail

kubectl create namespace "$CI_ENVIRONMENT_SLUG" --dry-run=client -o yaml | kubectl apply -f -
kubectl config set-context --current --namespace="$CI_ENVIRONMENT_SLUG"
helm upgrade "$CI_PROJECT_NAME" chart --install --wait --timeout "${HELM_TIMEOUT:-10m}"

host="${CI_ENVIRONMENT_SLUG}.apps.example.com"
printf 'CI_ENVIRONMENT_HOST=%s\n' "$host" > review.env
SH

cat > scripts/stop-review.sh <<'SH'
#!/usr/bin/env bash
set -euo pipefail

kubectl config set-context --current --namespace="$CI_ENVIRONMENT_SLUG"
helm uninstall "$CI_PROJECT_NAME" --wait --ignore-not-found || true
kubectl delete namespace "$CI_ENVIRONMENT_SLUG" --wait=false --ignore-not-found=true
SH

chmod +x scripts/start-review.sh scripts/stop-review.sh

Then include the component:

include:
  - component: $CI_SERVER_FQDN/$CI_PROJECT_PATH/review@$CI_COMMIT_SHA
    inputs:
      environment: review
      review-subdomain: apps.example.com
      review-start-script: scripts/start-review.sh
      review-stop-script: scripts/stop-review.sh

The start script can write CI_ENVIRONMENT_HOST=<hostname> to review.env when the hostname is discovered at runtime. If it does not, the environment URL uses review-domain.

Waiting for tests before stop​

The stop job defaults to waiting for an optional review:cypress job. Set needs-stop when your review tests use a different job name:

include:
  - component: $CI_SERVER_FQDN/$CI_PROJECT_PATH/review@$CI_COMMIT_SHA
    inputs:
      needs-stop:
        - job: smoke:review
          optional: true
          artifacts: false

Custom image and dependencies​

Use needs-start to fetch build artifacts and image when the review scripts need project-specific tooling:

include:
  - component: $CI_SERVER_FQDN/$CI_PROJECT_PATH/review@$CI_COMMIT_SHA
    inputs:
      image: "$CI_REGISTRY_IMAGE/review-tools:$CI_COMMIT_SHA"
      needs-start:
        - job: build:application
          artifacts: true

Script contract​

The start script should:

  • create or update the review application;
  • write review.env when it computes a dynamic CI_ENVIRONMENT_HOST;
  • exit non-zero when deployment fails.

The stop script should:

  • remove the same resources created by the start script;
  • tolerate already-removed resources;
  • avoid deleting shared namespaces or shared infrastructure unless the start script created them for this review environment.

Inputs​

NameDescriptionDefaultType
------------
environmentGitLab environment prefix for the review application.teststring
environment-identifierGitLab environment suffix. CI variables are expanded before use./review-$CI_PIPELINE_IID-$CI_COMMIT_SHORT_SHAstring
imageContainer image used to run the review scripts.${CI_TOOLS_REPO}/tools:mainstring
needs-startJobs that the start job depends on.[]array
needs-stopJobs that the stop job depends on.[]array
review-contextOptional context value for project-owned review scripts.string
review-domainDomain name to use for access to the review application.$CI_ENVIRONMENT_SLUG.$CI_REVIEW_SUBDOMAINstring
review-start-scriptPath to a script in the application that creates a review namespace and installs the application.scripts/start-review.shstring
review-stop-scriptPath to a script in the application that destroys the review namespace and application.scripts/stop-review.shstring
review-subdomainSubdomain name to create and access review applications.apps.02.xrow.netstring
rulesThe rules to determine when to run the job.[{"if":"$CI_PIPELINE_SOURCE == \"schedule\"","when":"never"},{"if":"$CI_COMMIT_TAG =~ $CI_PATTERN_SEMVER","when":"never"},{"if":"$CI_PIPELINE_SOURCE == \"merge_request_event\"","when":"on_success"},{"if":"$CI_COMMIT_REF_SLUG =~ $CI_DEFAULT_BRANCH","when":"on_success"},{"when":"never"}]array
stagePipeline stage for the review start and stop jobs.teststring
tagRunner tag for review jobs.string
timeoutReview job timeout and environment auto-stop interval.2hstring