Mosquitto: 5. GitLab CI

This documentation is part of the GitHub Actions & GitLab CI guide. You can view the complete guide here: Launch a real Mosquitto service from your GitHub Actions or GitLab CI pipeline, run your tests against it, and automatically tear it down.

👋 Welcome to the Stackhero documentation!

Stackhero provides you with a fully managed Mosquitto MQTT cloud environment, designed for reliability and flexibility:

• Unlimited message throughput and data transfers, so your workflows never encounter artificial limits.
• Unlimited device authentication via your own external API, making onboarding and access management straightforward.
• Advanced ACLs for precise control over topics, users, and actions.
• A custom domain name with integrated HTTPS for secure, branded endpoints (for example: https://mqtt.your-company.com).
• Effortless updates: apply improvements or security patches with a single click.
• Consistent performance and enhanced security, with every instance running on a private, dedicated infrastructure.

Accelerate your IoT projects and reduce operational overhead. You can have a secure, production-ready Mosquitto MQTT cloud hosting instance up and running in just a few minutes.

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

test:
  image: ubuntu:24.04
  variables:
    STACK_NAME: "ci-mosquitto-$CI_PIPELINE_ID-$CI_JOB_ID"
    INSTANCE: "200"   # Change this as needed (see step 3)
    REGION: "europe"
    SERVICE_STORE: "mosquitto"
  # 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 mosquitto-clients
    - 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')
user=$(echo "$config" | jq -r '.configuration.authenticationUsers[0].login')
password=$(echo "$config" | jq -r '.configuration.authenticationUsers[0].password')
    # Publish a test message to a topic.
    - mosquitto_pub -h "$host" -p 8883 -u "$user" -P "$password" --capath /etc/ssl/certs -t "stackhero/ci" -m "hello"
    - echo "✅ Mosquitto 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 Mosquitto 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 Mosquitto: 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.