Valkey: GitHub Actions & GitLab CI

Inicie um serviço real de Valkey a partir do seu pipeline do GitHub Actions ou GitLab CI, execute os seus testes sobre ele e elimine-o automaticamente

👋 Bem-vindo à documentação do Stackhero!

A Stackhero oferece uma solução Valkey cloud pronta a usar que proporciona uma série de benefícios, incluindo:

Interface web UI Redis Commander incluída.

Tamanho e transferências de mensagens ilimitados.

Atualizações simplificadas com apenas um clique.

Desempenho ótimo e segurança robusta alimentados por uma VM privada e dedicada.

Poupe tempo e simplifique a sua vida: são necessários apenas 5 minutos para experimentar a solução Valkey cloud hosting da Stackhero!

Este guia irá guiá-lo na execução de um serviço real e dedicado de Valkey dentro do seu pipeline CI, utilizando GitHub Actions ou GitLab CI. Ao seguir estes passos, poderá testar o seu código contra uma instância ativa de Valkey em condições semelhantes às de produção, deixando de depender de mocks ou simulações. Valkey is an open source, Redis-compatible in-memory data store, a drop-in choice for fast caching and key-value workloads.

Sempre que o seu pipeline for executado, será criada uma nova instância de Valkey. Isto significa que os seus testes interagem com o mesmo tipo de serviço que os seus utilizadores verão em produção. O workflow cria automaticamente uma stack temporária, adiciona o Valkey, aguarda que esteja pronto, obtém as credenciais geradas, executa um smoke test com o redis-cli e, no final, garante sempre a limpeza de todos os recursos.

Irá utilizar o Stackhero CLI, uma ferramenta de linha de comandos autónoma que facilita o lançamento e a gestão de serviços Stackhero de forma rápida e simples.

1. Criar um access token e guardá-lo como segredo CI

Para permitir que o CLI funcione de forma não interativa, irá necessitar de um access token (formato: usr-xxxxxx:tokenId). Só precisa de criar este token uma vez e adicioná-lo ao seu pipeline CI como um segredo seguro e encriptado.

Criar o token: No seu dashboard Stackhero, clique na sua foto de perfil no canto superior direito, aceda a A sua conta, depois Access tokens e clique em Criar token.
Para GitHub Actions: No seu repositório, vá a Settings > Secrets and variables > Actions > New repository secret e introduza o token como STACKHERO_TOKEN.
Para GitLab CI: No seu projeto, vá a Settings > CI/CD > Variables > Add variable, defina a chave como STACKHERO_TOKEN e selecione Masked (e Protected se o seu CI só correr em branches protegidas).

Nunca inclua o seu access token diretamente no ficheiro YAML do pipeline. Se estiver presente no YAML, pode ser exposto a qualquer pessoa com acesso ao repositório e pode aparecer nos logs de build. Guardá-lo como segredo CI mantém-no encriptado e mascarado, garantindo a segurança do seu token.

2. O script de ciclo de vida

Segue-se um exemplo completo de script que gere todo o ciclo de vida do serviço. Demonstra como a configuração é simples, bastando apenas alguns comandos. Pode copiar o YAML pronto para a sua plataforma nas secções abaixo.

#!/bin/bash
set -euo pipefail

# STACKHERO_TOKEN é fornecido pelo segredo CI, o CLI deteta-o automaticamente.

stackName="ci-valkey-$$"          # Nome único da stack para cada execução
serviceStore="valkey"             # O serviço store de Valkey
instance="1G"        # Altere se necessário (ver passo 3)
region="europe"                         # Nome da região (ver stackhero regions-list)

# 1. Instalar o CLI no runner
curl -fsSL https://www.stackhero.io/install.sh | sh

# 2. Instalar o cliente necessário para o smoke test (jq + curl são o mínimo)
apt-get update && apt-get install -y --no-install-recommends jq curl redis-tools

# 3. Criar uma stack dedicada para esta execução
stackId=$(stackhero --format=script stack-create --name="$stackName")
echo "Stack criada: $stackId"

# 4. Adicionar Valkey e obter o id do serviço
serviceId=$(stackhero --format=script service-add \
  --stack="$stackId" \
  --service-store="$serviceStore" \
  --instance="$instance" \
  --region="$region")
echo "Serviço adicionado: $serviceId"

# 5. Esperar até o serviço estar operacional (pode demorar alguns minutos)
stackhero service-wait-for --service="$serviceId"

# 6. Ler a configuração (contém as credenciais geradas)
config=$(stackhero service-configuration-get --service="$serviceId" --format=json)

# 7. Extrair as credenciais necessárias
host=$(echo "$config" | jq -r '.configuration.domain')
password=$(echo "$config" | jq -r '.configuration.credentials.password')

# 8. Smoke test: Send a PING and expect a PONG.
redis-cli -h "$host" -p 6380 -a "$password" --tls --no-auth-warning PING | grep -q PONG

echo "✅ Valkey está acessível a partir do CI."

O passo de teardown, que elimina o serviço, aguarda a sua remoção e depois elimina a stack, é detalhado nas secções específicas de cada plataforma abaixo. Este método garante que a limpeza é sempre realizada, mesmo que um smoke test falhe.

Uma stack só pode ser eliminada quando estiver vazia. Elimine sempre o serviço primeiro e aguarde a sua remoção, depois elimine a stack. O comando service-wait-for garante que o serviço está em execução ou já foi eliminado antes de prosseguir, sendo a ferramenta adequada também para aguardar pela eliminação.

3. Escolher o tamanho da instância

Os exemplos abaixo utilizam por defeito a instância de entrada 1G para Valkey. É uma escolha sólida para a maioria dos workloads, mas pode ajustá-la conforme necessário. Para ver todos os tipos de instância disponíveis para Valkey, execute:

# A coluna NAME mostra o valor a passar para --instance
stackhero instances-store-list --service-store=valkey

4. GitHub Actions

Para começar, guarde o seguinte conteúdo como .github/workflows/ci.yml. A partir de agora, cada push e pull request irá executar testes contra uma instância real de Valkey.

name: CI com Valkey

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    env:
      STACKHERO_TOKEN: ${{ secrets.STACKHERO_TOKEN }}
      STACK_NAME: ci-valkey-${{ github.run_id }}-${{ github.run_attempt }}
      INSTANCE: "1G"   # Altere se necessário (ver passo 3)
      REGION: europe
    steps:
      - uses: actions/checkout@v4

      - name: Instalar o Stackhero CLI e o cliente
        run: |
          curl -fsSL https://www.stackhero.io/install.sh | sh
          apt-get update && apt-get install -y --no-install-recommends jq curl redis-tools

      - name: Criar o serviço Valkey
        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="valkey" \
            --instance="$INSTANCE" \
            --region="$REGION")
          echo "SERVICE_ID=$SERVICE_ID" >> "$GITHUB_ENV"
          stackhero service-wait-for --service="$SERVICE_ID"

      - name: Executar testes sobre Valkey
        run: |
          set -euo pipefail
          config=$(stackhero service-configuration-get --service="$SERVICE_ID" --format=json)
          host=$(echo "$config" | jq -r '.configuration.domain')
password=$(echo "$config" | jq -r '.configuration.credentials.password')
          # Send a PING and expect a PONG.
          redis-cli -h "$host" -p 6380 -a "$password" --tls --no-auth-warning PING | grep -q PONG
          echo "✅ Valkey está acessível a partir do CI."
          # Pode executar a sua própria suite de testes aqui usando as credenciais acima ...

      - name: Limpeza (sempre, mesmo em caso de falha)
        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

O passo de limpeza está configurado com if: always() para garantir que é sempre executado, assegurando que a sua instância de Valkey é eliminada e que não será cobrado por recursos não utilizados.

5. GitLab CI

Pode guardar esta configuração como .gitlab-ci.yml. Com esta configuração, cada execução do pipeline cria uma nova instância real de Valkey para os seus testes.

test:
  image: ubuntu:24.04
  variables:
    STACK_NAME: "ci-valkey-$CI_PIPELINE_ID-$CI_JOB_ID"
    INSTANCE: "1G"   # Altere se necessário (ver passo 3)
    REGION: "europe"
    SERVICE_STORE: "valkey"
  # STACKHERO_TOKEN vem da variável CI/CD criada no passo 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 redis-tools
    - 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')
password=$(echo "$config" | jq -r '.configuration.credentials.password')
    # Send a PING and expect a PONG.
    - redis-cli -h "$host" -p 6380 -a "$password" --tls --no-auth-warning PING | grep -q PONG
    - echo "✅ Valkey está acessível a partir do CI."
    # Pode executar a sua própria suite de testes aqui usando as credenciais acima ...
  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

No GitLab, a limpeza é feita na secção after_script. Esta secção é sempre executada, mesmo que o job falhe, garantindo que os recursos de Valkey são eliminados e que não será cobrado por recursos não utilizados.

No GitLab, o after_script corre numa shell nova. Para lidar com isto, o script grava os IDs do serviço e da stack em deploy.env durante o job e volta a carregá-los antes da limpeza. Assim, mesmo que algo falhe a meio do job, os seus recursos são sempre eliminados.

Este é o ciclo CI completo para Valkey: criar uma stack, adicionar o serviço, aguardar, obter credenciais, smoke-test e garantir sempre a limpeza. Cada execução do pipeline recebe um serviço real e isolado, sem nada a correr no final. Para mais informações sobre os comandos disponíveis e autenticação não interativa com STACKHERO_TOKEN, consulte a documentação completa do CLI.