Meilisearch: GitHub Actions & GitLab CI

Launch a real Meilisearch service from your GitHub Actions or GitLab CI pipeline, run your tests against it, and automatically tear it down

Welcome to the Stackhero documentation!

If you are looking for a powerful and easy-to-use search engine, Stackhero's Meilisearch cloud service is an excellent choice. Here is what you can expect:

  • Customisable domain name with integrated HTTPS security.
  • Effortless updates, just a single click required.
  • High performance and enhanced security thanks to your own private and dedicated VM.

Want to get started quickly? Try Stackhero's Meilisearch cloud hosting solution in just 5 minutes. It is designed to save you time and make your setup as straightforward as possible!

This guide explains how to run a real, dedicated Meilisearch service within your CI pipeline using either GitHub Actions or GitLab CI. By following these steps, you can test your code against a live Meilisearch instance in production-like conditions, so you no longer need to rely on mocks or simulations. Meilisearch is a fast, open source, typo-tolerant search engine that delivers instant, relevant results out of the box.

Each time your pipeline runs, a new Meilisearch instance is created. This means your tests interact with the same type of service your users will see in production. The workflow automatically creates a temporary stack, adds Meilisearch, waits for it to be ready, retrieves the generated credentials, runs a smoke test using curl, and always cleans everything up at the end of the run.

You will use the Stackhero CLI, a standalone command-line tool that makes launching and managing Stackhero services quick and straightforward.

1. Create an access token and store it as a CI secret

To allow the CLI to work non-interactively, you will need an access token (format: usr-xxxxxx:tokenId). You only need to create this token once, then add it to your CI pipeline as a secure, encrypted secret.

  1. Create the token: In your Stackhero dashboard, click your profile picture at the top right, go to Your account, then Access tokens, and click Create token.
  2. For GitHub Actions: In your repository, go to Settings > Secrets and variables > Actions > New repository secret, and enter the token as STACKHERO_TOKEN.
  3. For GitLab CI: In your project, go to Settings > CI/CD > Variables > Add variable, set the key to STACKHERO_TOKEN, and tick Masked (and Protected if your CI only runs on protected branches).

Never add your access token directly into your pipeline YAML file. If it is present in the YAML, it could be exposed to anyone with repository access and may appear in build logs. Storing it as a CI secret ensures it remains encrypted and masked, keeping your token secure.

2. The lifecycle script

Here is a complete example script that manages the entire service lifecycle. It shows just how simple the setup is, requiring only a few commands. You can copy the ready-to-use YAML for your platform from the sections below.

#!/bin/bash
set -euo pipefail

# STACKHERO_TOKEN is provided by the CI secret, the CLI picks it up automatically.

stackName="ci-meilisearch-$$"          # Unique stack name for each run
serviceStore="meilisearch"             # The Meilisearch service store
instance="10G"        # Change this as needed (see step 3)
region="europe"                         # Region name (see stackhero regions-list)

# 1. Install the CLI on the runner
curl -fsSL https://www.stackhero.io/install.sh | sh

# 2. Install the client required for smoke testing (jq + curl are the baseline)
apt-get update && apt-get install -y --no-install-recommends jq curl

# 3. Create a dedicated stack for this run
stackId=$(stackhero --format=script stack-create --name="$stackName")
echo "Stack created: $stackId"

# 4. Add Meilisearch and capture its service id
serviceId=$(stackhero --format=script service-add \
  --stack="$stackId" \
  --service-store="$serviceStore" \
  --instance="$instance" \
  --region="$region")
echo "Service added: $serviceId"

# 5. Wait until the service is running (this may take a couple of minutes)
stackhero service-wait-for --service="$serviceId"

# 6. Read the configuration (contains the generated credentials)
config=$(stackhero service-configuration-get --service="$serviceId" --format=json)

# 7. Extract the credentials you need
host=$(echo "$config" | jq -r '.configuration.domain')

# 8. Smoke test: Call the Meilisearch health endpoint.
curl -fsS "https://$host/health" | grep -q '"status":"available"'

echo "✅ Meilisearch is reachable from CI."

The teardown step, which deletes the service, waits for its removal, and then deletes the stack, is detailed in the platform-specific sections below. This approach ensures cleanup always takes place, even if a smoke test fails.

A stack can only be deleted once it is empty. Always delete the service first and wait for its removal, then delete the stack. The service-wait-for command ensures the service is either running or deleted before continuing, making it the right tool for deletion waits as well.

3. Choose the instance size

The examples below use the entry-level instance 10G for Meilisearch by default. This is a reliable choice for most workloads, but you can adjust it as needed. To see all available instance types for Meilisearch, run:

# The NAME column shows the value to pass to --instance
stackhero instances-store-list --service-store=meilisearch

4. GitHub Actions

To get started, save the following as .github/workflows/ci.yml. From now on, every push and pull request will run tests against a real Meilisearch instance.

name: CI with Meilisearch

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    env:
      STACKHERO_TOKEN: ${{ secrets.STACKHERO_TOKEN }}
      STACK_NAME: ci-meilisearch-${{ github.run_id }}-${{ github.run_attempt }}
      INSTANCE: "10G"   # Change this as needed (see step 3)
      REGION: europe
    steps:
      - uses: actions/checkout@v4

      - name: Install the Stackhero CLI and the client
        run: |
          curl -fsSL https://www.stackhero.io/install.sh | sh
          apt-get update && apt-get install -y --no-install-recommends jq curl

      - name: Create the Meilisearch service
        run: |
          set -euo pipefail
          STACK_ID=$(stackhero --format=script stack-create --name="$STACK_NAME")
          echo "STACK_ID=$STACK_ID" >> "$GITHUB_ENV"
          SERVICE_ID=$(stackhero --format=script service-add \
            --stack="$STACK_ID" \
            --service-store="meilisearch" \
            --instance="$INSTANCE" \
            --region="$REGION")
          echo "SERVICE_ID=$SERVICE_ID" >> "$GITHUB_ENV"
          stackhero service-wait-for --service="$SERVICE_ID"

      - name: Run tests against Meilisearch
        run: |
          set -euo pipefail
          config=$(stackhero service-configuration-get --service="$SERVICE_ID" --format=json)
          host=$(echo "$config" | jq -r '.configuration.domain')
          # Call the Meilisearch health endpoint.
          curl -fsS "https://$host/health" | grep -q '"status":"available"'
          echo "✅ Meilisearch is reachable from CI."
          # You can run your own test suite here using the credentials above ...

      - name: Tear down (always, even on failure)
        if: always()
        run: |
          if [ -n "${SERVICE_ID:-}" ]; then
            stackhero service-delete --service="$SERVICE_ID" --confirm
            stackhero service-wait-for --service="$SERVICE_ID"
          fi
          if [ -n "${STACK_ID:-}" ]; then
            stackhero stack-delete --stack="$STACK_ID" --confirm
          fi

The teardown step uses if: always() to ensure it runs in all cases, guaranteeing your Meilisearch instance is deleted and you are not billed for unused resources.

5. GitLab CI

You can save this configuration as .gitlab-ci.yml. With this setup, each pipeline run creates a new Meilisearch instance for your tests.

test:
  image: ubuntu:24.04
  variables:
    STACK_NAME: "ci-meilisearch-$CI_PIPELINE_ID-$CI_JOB_ID"
    INSTANCE: "10G"   # Change this as needed (see step 3)
    REGION: "europe"
    SERVICE_STORE: "meilisearch"
  # STACKHERO_TOKEN comes from the CI/CD variable you created in step 1.
  script:
    - set -euo pipefail
    - curl -fsSL https://www.stackhero.io/install.sh | sh
    - apt-get update && apt-get install -y --no-install-recommends jq curl
    - STACK_ID=$(stackhero --format=script stack-create --name="$STACK_NAME")
    - echo "STACK_ID=$STACK_ID" >> deploy.env
    - SERVICE_ID=$(stackhero --format=script service-add --stack="$STACK_ID" --service-store="$SERVICE_STORE" --instance="$INSTANCE" --region="$REGION")
    - echo "SERVICE_ID=$SERVICE_ID" >> deploy.env
    - stackhero service-wait-for --service="$SERVICE_ID"
    - config=$(stackhero service-configuration-get --service="$SERVICE_ID" --format=json)
    - host=$(echo "$config" | jq -r '.configuration.domain')
    # Call the Meilisearch health endpoint.
    - curl -fsS "https://$host/health" | grep -q '"status":"available"'
    - echo "✅ Meilisearch is reachable from CI."
    # You can run your own test suite here using the credentials above ...
  after_script:
    - test -f deploy.env && . ./deploy.env || true
    - >
      if [ -n "${SERVICE_ID:-}" ]; then
        stackhero service-delete --service="$SERVICE_ID" --confirm
        stackhero service-wait-for --service="$SERVICE_ID"
      fi
    - >
      if [ -n "${STACK_ID:-}" ]; then
        stackhero stack-delete --stack="$STACK_ID" --confirm
      fi

On GitLab, cleanup is performed in after_script. This section is always executed, even if the job fails, ensuring your Meilisearch resources are deleted and you are not charged for unused resources.

In GitLab, after_script runs in a fresh shell. To handle this, the script writes the service and stack IDs to deploy.env during the job and reloads them before cleanup. This ensures that even if something fails mid-job, your resources are still deleted.

That is the complete CI lifecycle for Meilisearch: create a stack, add the service, wait, retrieve credentials, smoke-test, and always tear down. Each pipeline run gets a real, isolated service, with nothing left running once you are finished. For more information about available commands and non-interactive STACKHERO_TOKEN authentication, you can refer to the full CLI documentation.

Other articles for Meilisearch

  1. Automate with the CLI
    Start Meilisearch, retrieve its credentials, and modify its configuration programmatically using the Stackhero CLI