Inicio rápido

Cada proyecto está vinculado a una organización. Para crearlo, diríjase a Proyectos > Nuevo proyecto en la consola web.

• Nombre (obligatorio, hasta 80 caracteres)
• Descripción (opcional, hasta 500 caracteres)
• Tecnologías (opcional, se autocompletan al vincular el repositorio en el siguiente paso)

No es indispensable contar con un repositorio vinculado para inicializar el proyecto. Conectar el repositorio, generar la API key y configurar el reporte en CI son pasos independientes que pueden realizarse en cualquier orden.

Nota: Los proyectos nuevos inician sin suites registradas, sin ejecuciones y con el indicador de repositorio desconectado hasta recibir la primera carga de datos.

Este paso habilita el flujo de cambios de código. Qably recibe las actualizaciones mediante webhooks enviados por el proveedor del repositorio, de forma independiente a la API key del paso 3.

Selección del repositorio

1. Inicie sesión con GitHub si aún no lo ha hecho. Qably utiliza este token de OAuth para listar los repositorios accesibles en su cuenta personal y organizaciones asociadas.
2. En la sección Integraciones del proyecto, seleccione el repositorio deseado de la lista disponible, ordenada por fecha de push reciente.
3. Al seleccionar un repositorio no vinculado, se crea una conexión dentro de la organización y se genera su secreto de webhook. Seleccionar un repositorio previamente vinculado reutiliza la conexión existente.

Registro del webhook en el proveedor

Qably no registra webhooks de forma automática en proveedores externos. Debe agregarse manualmente en la configuración del repositorio.

1. Obtenga el secreto ejecutando POST /connections/:id/webhook-secret desde la interfaz de la conexión. La respuesta entrega el valor en texto plano una sola vez (al crearlo o rotarlo), por lo que debe copiarse inmediatamente.
2. En GitHub, acceda a Settings > Webhooks > Add webhook dentro del repositorio.
3. Payload URL: https://api.qably.dev/webhooks/scm/github
4. Content type: application/json
5. Secret: el valor obtenido en el paso anterior
6. Events: seleccione push como mínimo. Se recomienda marcar también pull request para registrar la actividad completa del equipo.

Validación de la firma: Qably valida cada entrega entrante contra el secreto registrado mediante una firma HMAC-SHA256 (encabezado x-hub-signature-256 en formato sha256=<hex>). Las peticiones sin firma o con firmas inválidas se rechazan con código HTTP 401.

Verificación de la entrega: Las entregas exitosas se reflejan de inmediato en el historial de webhooks del proveedor. En la vista Repository de Qably, el lote de ingesta y los cambios de código aparecerán tras el siguiente push o pull request.

Este paso habilita el flujo de resultados de pruebas, proporcionando una credencial de máquina para que el pipeline de CI reporte ejecuciones sin requerir una sesión de usuario.

1. En la pestaña API Keys del proyecto, cree una clave asignándole un nombre identificable como "CI/CD Pipeline". Esta acción requiere rol de owner o admin en la organización.
2. El token generado sigue la estructura qbly_<lookupId>_<secret> y se muestra una única vez en la pantalla de confirmación. Qably almacena únicamente su hash SHA-256 y no puede recuperarlo posteriormente.
3. Guarde el valor en su proveedor de CI. En GitHub Actions, vaya a Settings > Secrets and variables > Actions > Secrets y cree el secreto de repositorio QABLY_API_KEY. Si utiliza una URL personalizada, agregue la variable QABLY_API_BASE_URL en la pestaña Variables. Nunca incluya este token en el repositorio de código.

Cada API key tiene alcance exclusivo sobre un proyecto y únicamente permite registrar ejecuciones. No tiene permisos de lectura sobre otros proyectos ni facultades administrativas sobre la organización. El proyecto destino se infiere directamente de la clave.

Revocar una clave desactiva su uso de forma inmediata pero conserva los registros históricos asociados. Es posible mantener múltiples claves activas simultáneamente para facilitar la rotación sin interrumpir los pipelines de CI.

Para conectar Qably a su integración continua, cree un archivo de flujo de trabajo en su repositorio (por ejemplo, .github/workflows/ci.yml). El lenguaje YAML organiza el pipeline a través de los eventos de activación on, la definición de entornos bajo jobs y la secuencia ordenada de comandos en steps para preparar el entorno, ejecutar las pruebas y enviar el reporte.

En Jest, instale jest-junit y defina JEST_JUNIT_ADD_FILE_ATTRIBUTE como "true" para que el XML incluya la ruta de archivo de cada caso de prueba, lo que permite a Qably vincular las pruebas con el código fuente. Vitest incluye un reporter JUnit propio: actívelo con --reporter=junit e indique el archivo de salida con --outputFile, como en el flujo siguiente.

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    name: Run tests and report to Qably
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Install dependencies
        run: npm ci

      - name: Run Jest tests
        env:
          JEST_JUNIT_OUTPUT_DIR: ./reports
          JEST_JUNIT_OUTPUT_NAME: junit.xml
          JEST_JUNIT_ADD_FILE_ATTRIBUTE: 'true'
        run: npx jest --ci --reporters=default --reporters=jest-junit

      - name: Report results to Qably
        if: always()
        env:
          QABLY_API_KEY: ${{ secrets.QABLY_API_KEY }}
        run: |
          curl --fail --silent --request POST \
            "https://api.qably.dev/runs/ingest/junit?externalId=gha-${{ github.run_id }}-${{ github.job }}&source=github_actions&commitSha=${{ github.event.pull_request.head.sha || github.sha }}" \
            --header "Authorization: Bearer $QABLY_API_KEY" \
            --header "Content-Type: application/xml" \
            --data-binary @./reports/junit.xml || true

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    name: Run tests and report to Qably
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Install dependencies
        run: npm ci

      - name: Run Vitest tests
        run: npx vitest run --reporter=default --reporter=junit --outputFile=./reports/junit.xml

      - name: Report results to Qably
        if: always()
        env:
          QABLY_API_KEY: ${{ secrets.QABLY_API_KEY }}
        run: |
          curl --fail --silent --request POST \
            "https://api.qably.dev/runs/ingest/junit?externalId=gha-${{ github.run_id }}-${{ github.job }}&source=github_actions&commitSha=${{ github.event.pull_request.head.sha || github.sha }}" \
            --header "Authorization: Bearer $QABLY_API_KEY" \
            --header "Content-Type: application/xml" \
            --data-binary @./reports/junit.xml || true

El endpoint POST /runs/ingest/junit recibe el archivo XML directo y procesa todo en el servidor. Si el reporte contiene suites o casos no registrados previamente, Qably los crea de forma automática en ese proyecto.

El parámetro externalId asegura idempotencia ante reintentos de CI. Al enlazarlo con identificadores provistos por el runner (como github.run_id y github.job), reintentar un job en GitHub Actions actualiza la ejecución previa en Qably en lugar de generar registros duplicados. El parámetro commitSha permite a Qably listar los commits candidatos entre dos ejecuciones. En los pull requests la expresión usa el commit de la punta, porque github.sha es un commit de fusión temporal que ningún push contiene. Vea cómo leer una regresión.

Cada flujo se valida de forma independiente, dado que uno puede estar recibiendo datos mientras el otro requiere ajustes de configuración.

• Resultados de pruebas: abra el proyecto y verifique la ejecución recién enviada por CI. El estado general del run se deriva de sus casos: cualquier prueba fallida marca el run como fallido; casos en ejecución o pendientes lo mantienen en progreso; y se considera exitoso cuando al menos un caso pasa o se omite sin fallas acompañantes.
• Cambios de código: requiere haber completado el paso 2. La vista Repository del proyecto debe reflejar el lote de ingesta correspondiente al push o pull request más reciente.

Solución de problemas: Si los datos no se visualizan en la interfaz, consulte la página de preguntas frecuentes para diagnosticar webhooks no registrados o variables de entorno omitidas en CI.