# El reporter de Jest en tu CI

> Pipelines completos para @probara/jest-reporter en GitHub Actions, GitLab CI, Jenkins, CircleCI, Azure Pipelines, Bitbucket Pipelines y Buildkite, con secretos, sharding, detección del CI y seguridad frente a forks.

El reporter se ejecuta dentro de `npx jest`: pasa el token al paso que ejecuta tus pruebas, y cada
resultado se envía cuando termina el comando. No hay un paso de envío aparte. Todos los ejemplos
suponen que el reporter está registrado en `jest.config.js` como en
[Primeros pasos](https://docs.probara.net/es/developers/ci-integrations/jest/#3-añádelo-a-la-configuración-de-jest).

## En cualquier CI

- **El token es un secreto, el ID del Proyecto no.** Guarda el token de aplicación (de la tarjeta
  **Jest** en **Workspace › Integraciones**) como un secreto llamado `PROBARA_API_TOKEN`. Pon el ID
  del Proyecto en `jest.config.js` (`projectId`) o en el pipeline (`PROBARA_PROJECT`).
- **Node.js 22.12 o posterior** en el agente, como la ejecución de Jest de la que forma parte el
  reporter.
- **Las pruebas fallidas hacen fallar el paso, los problemas al reportar no**: el código de salida de
  Jest sigue siendo el de las pruebas.
- **`npm test` también funciona** cuando tu script `test` ejecuta `jest`: el reporter sale de la
  configuración, no del comando.
- **Fija la versión** en `package.json` (o en el lockfile), para que una versión nueva nunca cambie un
  pipeline por sorpresa. La CLI no es una dependencia del reporter: los pasos de abajo que la usan
  fijan su versión en el propio comando (`npx --yes @probara/cli@0.2`). Con `@probara/cli` en tus
  `devDependencies`, `npx @probara/cli` después de `npm ci` ejecuta la versión del lockfile.
- **Los builds de forks no reportan nada**: sin el secreto, el reporter no envía nada (si el
  proyecto está definido, registra que falta el token) y las pruebas se ejecutan como siempre. La
  CLI termina con código 2 sin token, así que las recetas desactivan el envío
  (`PROBARA_ENABLED=false`) donde la ejecutaría el build de un fork: entonces termina con código 0.
  Cada sección de abajo explica cómo mantener el secreto fuera de los builds de forks en ese CI.
- **Los jobs con sharding** crean una ejecución por shard salvo que compartan una. En GitHub Actions los
  jobs de un mismo workflow comparten una ejecución automáticamente
  ([jobs en paralelo](#jobs-en-paralelo-una-ejecución-cerrada-por-el-job-final)). Fuera de GitHub
  Actions, créala primero, pasa su ULID a cada shard, y ciérrala al final
  ([sharding](https://docs.probara.net/es/developers/ci-integrations/jest/sharding/)).

### Lo que rellena la detección del CI

Salvo que una opción o una variable `PROBARA_*` los defina, la ejecución toma su nombre y su origen
del CI:

| CI                  | Se detecta por           | Nombre de la ejecución                            |
| ------------------- | ------------------------ | ------------------------------------------------- |
| GitHub Actions      | `GITHUB_ACTIONS=true`    | `GITHUB_WORKFLOW #GITHUB_RUN_NUMBER`              |
| GitLab CI           | `GITLAB_CI=true`         | `CI_PROJECT_NAME #CI_PIPELINE_IID`                |
| Jenkins             | `JENKINS_URL`            | `JOB_NAME #BUILD_NUMBER`                          |
| CircleCI            | `CIRCLECI=true`          | `CIRCLE_PROJECT_REPONAME #CIRCLE_BUILD_NUM`       |
| Azure Pipelines     | `TF_BUILD=True`          | `BUILD_DEFINITIONNAME #BUILD_BUILDNUMBER`         |
| Bitbucket Pipelines | `BITBUCKET_BUILD_NUMBER` | `BITBUCKET_REPO_SLUG #BITBUCKET_BUILD_NUMBER`     |
| Buildkite           | `BUILDKITE=true`         | `BUILDKITE_PIPELINE_SLUG #BUILDKITE_BUILD_NUMBER` |

La rama, el commit y la URL del build de cada uno figuran en su sección, y en la
[detección del CI de `@probara/core`](https://github.com/cynch-me/probara-sdk/blob/main/packages/core/README.md#ci-detection).
Sustitúyelos con `PROBARA_BRANCH`, `PROBARA_COMMIT` y `PROBARA_BUILD_URL`.

## GitHub Actions

### 1. Añade el secreto

En el repositorio (o en la organización): **Settings → Secrets and variables → Actions → New
repository secret**, con el nombre `PROBARA_API_TOKEN` y el token de aplicación como valor.

### 2. Pasa el token al paso de pruebas

```yaml
name: Jest

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v5
        with:
          node-version: 22
      - run: npm ci
      - name: Run Jest tests
        run: npx jest --ci
        env:
          PROBARA_API_TOKEN: ${{ secrets.PROBARA_API_TOKEN }}
          PROBARA_PROJECT: SHOP
```

### Jobs en paralelo: una ejecución, cerrada por el job final

En GitHub Actions los jobs de un mismo workflow envían a una misma ejecución: el origen de la
ejecución identifica la ejecución del workflow por su repositorio, su id y su intento, y el primer job
que envía crea la ejecución. Por defecto, cada job cierra su ejecución al terminar, así que los jobs
en paralelo definen `PROBARA_CLOSE_RUN: false`. Un job final cierra la ejecución con
`probara run close`, que no necesita aquí el ULID: `needs` hace que espere a todos los jobs de
pruebas, y `if: always()` lo ejecuta aunque fallen.

```yaml
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        shard: [1, 2]
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v5
        with:
          node-version: 22
      - run: npm ci
      - run: npx jest --ci --shard=${{ matrix.shard }}/2
        env:
          PROBARA_API_TOKEN: ${{ secrets.PROBARA_API_TOKEN }}
          PROBARA_PROJECT: SHOP
          # A shard leaves the run open for the others.
          PROBARA_CLOSE_RUN: false

  probara:
    needs: test
    if: always()
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v5
        with:
          node-version: 22
      - run: npx --yes @probara/cli@0.6 run close
        env:
          PROBARA_API_TOKEN: ${{ secrets.PROBARA_API_TOKEN }}
          PROBARA_PROJECT: SHOP
```

- **Un job tras el cierre** recibe `409 ci_run_closed`: el reporter registra el motivo, no envía nada
  más, y las pruebas conservan su código de salida
  ([solución de problemas](https://docs.probara.net/es/developers/ci-integrations/jest/troubleshooting/#un-job-envía-después-de-cerrarse-su-ejecución)).
  Mantén cada job que envía en `needs`.
- **Una nueva ejecución del workflow** (re-run) es otro intento: envía a una ejecución propia.
- **Un solo job** no necesita nada de esto: su ejecución se cierra al terminar, como en cualquier otro caso.

### Detección del CI

| Campo            | De dónde sale                                                                                |
| ---------------- | -------------------------------------------------------------------------------------------- |
| Nombre           | `GITHUB_WORKFLOW #GITHUB_RUN_NUMBER`, por ejemplo `Jest #42`                                 |
| Rama             | `GITHUB_HEAD_REF` (la rama de la pull request), si no `GITHUB_REF_NAME`; ninguna para un tag |
| Commit           | `GITHUB_SHA`                                                                                 |
| URL del build    | `GITHUB_SERVER_URL/GITHUB_REPOSITORY/actions/runs/GITHUB_RUN_ID`                             |
| Repositorio      | `GITHUB_REPOSITORY`                                                                          |
| Autor del commit | `GITHUB_ACTOR`                                                                               |
| Pull request     | `<n>` de `GITHUB_REF` `refs/pull/<n>/merge`                                                  |
| Workflow         | `GITHUB_WORKFLOW`                                                                            |
| Ejecución de CI  | `GITHUB_RUN_ID`, intento `GITHUB_RUN_ATTEMPT`                                                |
| Job de CI        | `GITHUB_JOB`                                                                                 |

En los eventos `pull_request`, `GITHUB_SHA` es el commit de merge que creó GitHub, no el último commit
de la rama. Para registrar este último, añade
`PROBARA_COMMIT: ${{ github.event.pull_request.head.sha }}`. En GitHub Actions el commit debe ser un
SHA hexadecimal de 7 a 40 caracteres: otro valor se descarta con una advertencia.

### Pull requests desde forks

Los workflows que lanza una pull request desde un fork reciben los secretos vacíos. Sin token, el
reporter queda desactivado, así que los builds de forks ejecutan sus pruebas y no
reportan nada, sin ningún ajuste adicional. No uses `pull_request_target` para llevar el secreto a un
build de un fork: ejecuta el código del fork con tus secretos.

## GitLab CI

### 1. Añade la variable

**Settings → CI/CD → Variables → Add variable**: clave `PROBARA_API_TOKEN`, el token como valor, con
**Mask variable** activado. **Protect variable** la limita a ramas y tags protegidos: actívalo solo si
reportas únicamente desde ellos.

### 2. El job de pruebas

```yaml
stages:
  - test

jest:
  stage: test
  image: node:22
  variables:
    PROBARA_PROJECT: SHOP
  script:
    - npm ci
    - npx jest --ci
```

- Un job sin la variable (el pipeline de un fork, una rama no protegida con una variable protegida)
  ejecuta sus pruebas y no reporta nada.
- Para conservar lo que no se pudo enviar, define `PROBARA_RESULTS_FILE` y guarda el archivo como
  artefacto
  ([archivo de resultados](https://docs.probara.net/es/developers/ci-integrations/jest/results-and-retries/#en-ci)).
- Los shards `parallel:` que comparten una ejecución, con un job `.pre` que la crea y un job `.post`
  que la cierra, están en [sharding](https://docs.probara.net/es/developers/ci-integrations/jest/sharding/#gitlab-ci).

### Detección del CI

| Campo         | De dónde sale                                                                                                                    |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Nombre        | `CI_PROJECT_NAME #CI_PIPELINE_IID`, por ejemplo `shop #42`                                                                       |
| Rama          | `CI_MERGE_REQUEST_SOURCE_BRANCH_NAME` en un pipeline de merge request, si no `CI_COMMIT_REF_NAME`; ninguna en un pipeline de tag |
| Commit        | `CI_COMMIT_SHA`                                                                                                                  |
| URL del build | `CI_PIPELINE_URL`                                                                                                                |

### Merge requests desde forks

Una merge request desde un fork ejecuta su pipeline en el proyecto del fork, que no tiene tus
variables de CI/CD: el reporter queda desactivado ahí. Si los maintainers ejecutan pipelines de forks
en el proyecto principal, esos pipelines sí reciben la variable, así que revisa el cambio antes de
ejecutarlo.

## Jenkins

### 1. Añade la credencial

**Manage Jenkins → Credentials → (un dominio) → Add Credentials**: tipo **Secret text**, ID
`probara-api-token`, el token como secreto.

### 2. El pipeline

Un `Jenkinsfile` declarativo con Node.js 22 en el agente enlaza el token en la etapa de pruebas con
`withCredentials`:

```groovy
pipeline {
  agent any
  environment {
    PROBARA_PROJECT = 'SHOP'
  }
  stages {
    stage('Test') {
      steps {
        sh 'npm ci'
        withCredentials([string(credentialsId: 'probara-api-token', variable: 'PROBARA_API_TOKEN')]) {
          sh 'npx jest --ci'
        }
      }
    }
  }
}
```

Jenkins enmascara el secreto enlazado en el log del build.

### Etapas en paralelo: una ejecución

Las etapas en paralelo que ejecutan `--shard` crean una ejecución cada una salvo que compartan una:
créala en una primera etapa, pásala a cada una y ciérrala en un bloque `post { always { ... } }`:

```groovy
pipeline {
  agent any
  environment {
    PROBARA_PROJECT = 'SHOP'
  }
  stages {
    stage('Create the Probara run') {
      steps {
        sh 'npm ci'
        withCredentials([string(credentialsId: 'probara-api-token', variable: 'PROBARA_API_TOKEN')]) {
          sh 'npx --yes @probara/cli@0.2 run create > probara-run-ulid'
        }
        script {
          env.PROBARA_RUN_ULID = readFile('probara-run-ulid').trim()
        }
      }
    }
    stage('Test') {
      parallel {
        stage('Shard 1') {
          steps {
            withCredentials([string(credentialsId: 'probara-api-token', variable: 'PROBARA_API_TOKEN')]) {
              sh 'npx jest --ci --shard=1/2'
            }
          }
        }
        stage('Shard 2') {
          steps {
            withCredentials([string(credentialsId: 'probara-api-token', variable: 'PROBARA_API_TOKEN')]) {
              sh 'npx jest --ci --shard=2/2'
            }
          }
        }
      }
    }
  }
  post {
    always {
      withCredentials([string(credentialsId: 'probara-api-token', variable: 'PROBARA_API_TOKEN')]) {
        sh 'npx --yes @probara/cli@0.2 run close'
      }
    }
  }
}
```

Aquí ambos shards comparten un workspace, instalado una sola vez antes de que empiecen (dos `npm ci`
a la vez en una misma carpeta se estorbarían); en agentes separados, cada uno hace su propio checkout
e instalación.

### Pull requests desde forks

Jenkins no oculta por sí solo las credenciales a los builds de pull requests: un job multibranch que
construye forks puede entregar el token a su código. Configura **Discover pull requests from forks →
Trust** para que una pull request de cualquier otra persona se construya con el `Jenkinsfile` de su
rama destino: en el branch source de GitHub, **From users with Admin or Write permission** (o
**Nobody**); en el branch source de Bitbucket, **Nobody**, o **Forks in the same account** a partir
de la versión 871 del plugin (la corrección de CVE-2024-28152). **Everyone** construye un fork con su
propio `Jenkinsfile`, que puede enlazar la credencial por sí mismo, y deja inútil la protección con
`env.CHANGE_FORK` de abajo.

En el `Jenkinsfile` de la rama destino, enlaza la credencial solo cuando `env.CHANGE_FORK` no está
definida (Jenkins la define para una pull request desde un fork), y desactiva el envío en un build de
un fork:

```groovy
pipeline {
  agent any
  environment {
    PROBARA_PROJECT = 'SHOP'
  }
  stages {
    stage('Test') {
      steps {
        sh 'npm ci'
        script {
          if (env.CHANGE_FORK) {
            withEnv(['PROBARA_ENABLED=false']) {
              sh 'npx jest --ci'
            }
          } else {
            withCredentials([string(credentialsId: 'probara-api-token', variable: 'PROBARA_API_TOKEN')]) {
              sh 'npx jest --ci'
            }
          }
        }
      }
    }
  }
}
```

En el pipeline en paralelo, envuelve cada `withCredentials` de la misma forma: con el envío
desactivado, `run create` no escribe ningún ULID y `run close` termina con 0 sin token.

### Detección del CI

Con `JENKINS_URL` definida, la ejecución se llama `JOB_NAME #BUILD_NUMBER`, y su rama, su commit y la
URL del build salen de `BRANCH_NAME` (o `GIT_BRANCH`), `GIT_COMMIT` y `BUILD_URL`.

## CircleCI

### 1. Añade el token

**Organization Settings → Contexts → Create Context** (por ejemplo `probara-reporting`), y después
añade la variable de entorno `PROBARA_API_TOKEN`. Una variable de entorno de proyecto (**Project
Settings → Environment Variables**) también sirve; en ese caso quita `context:` del ejemplo.

### 2. El job

Un `.circleci/config.yml` en una imagen de Node.js, con sharding mediante `parallelism` en una
ejecución creada al principio. Sin `parallelism`, deja solo el job `test` y ejecuta `npx jest --ci`:

```yaml
version: 2.1

jobs:
  create-run:
    docker:
      - image: cimg/node:22.12
    environment:
      PROBARA_PROJECT: SHOP
    steps:
      - run: |
          # Without the token (a fork's build), turn reporting off: run create prints nothing.
          [ -n "$PROBARA_API_TOKEN" ] || export PROBARA_ENABLED=false
          PROBARA_RUN_ULID=$(npx --yes @probara/cli@0.2 run create)
          echo "PROBARA_RUN_ULID=$PROBARA_RUN_ULID" > probara.env
      - persist_to_workspace:
          root: .
          paths: [probara.env]
  test:
    docker:
      - image: cimg/node:22.12
    parallelism: 4
    environment:
      PROBARA_PROJECT: SHOP
    steps:
      - checkout
      - attach_workspace:
          at: .
      - run: npm ci
      - run: |
          export $(cat probara.env)
          npx jest --ci --shard=$((CIRCLE_NODE_INDEX + 1))/$CIRCLE_NODE_TOTAL
  close-run:
    docker:
      - image: cimg/node:22.12
    environment:
      PROBARA_PROJECT: SHOP
    steps:
      - attach_workspace:
          at: .
      - run:
          when: always
          command: |
            export $(cat probara.env)
            [ -n "$PROBARA_API_TOKEN" ] || export PROBARA_ENABLED=false
            npx --yes @probara/cli@0.2 run close

workflows:
  jest:
    jobs:
      - create-run:
          context: probara-reporting
      - test:
          context: probara-reporting
          requires: [create-run]
      - close-run:
          context: probara-reporting
          requires:
            - test: [success, failed]
```

`CIRCLE_NODE_INDEX` empieza en 0, los shards de Jest en 1.

### Forks y detección del CI

CircleCI no pasa contextos ni variables de proyecto a los builds de pull requests desde forks, salvo
que **Pass secrets to builds from forked pull requests** esté activado: déjalo desactivado. Los jobs
de un fork que usan un contexto no llegan a ejecutarse (CircleCI muestra un error de autorización).
Con variables del proyecto se ejecutan sin el token: el reporter no envía nada, y la línea
`PROBARA_ENABLED=false` de `create-run` y `close-run` hace que `run create` no imprima nada y que
ambos terminen con código 0.

Con `CIRCLECI=true`, la ejecución se llama `CIRCLE_PROJECT_REPONAME #CIRCLE_BUILD_NUM`, con la rama
`CIRCLE_BRANCH`, el commit `CIRCLE_SHA1` y la URL del build `CIRCLE_BUILD_URL`.

## Azure Pipelines

### 1. Añade la variable

**Pipelines → tu pipeline → Edit → Variables → New variable**: nombre `PROBARA_API_TOKEN`, el token
como valor, con **Keep this value secret** activado. Un grupo de variables de la biblioteca también
sirve. Las variables secretas nunca llegan solas a los scripts: asigna la variable en el `env` del
paso, como abajo.

### 2. El job

```yaml
variables:
  # Off in a fork's build, which gets no secrets (see forks below).
  PROBARA_ENABLED: $[ ne(variables['System.PullRequest.IsFork'], 'True') ]

pool:
  vmImage: ubuntu-latest

steps:
  - task: NodeTool@0
    inputs:
      versionSpec: '22.x'
  - script: npm ci
  - script: npx jest --ci
    env:
      PROBARA_API_TOKEN: $(PROBARA_API_TOKEN)
      PROBARA_PROJECT: SHOP
```

### Jobs con sharding: una ejecución

Con sharding mediante `parallel` en una ejecución que crea un primer job y cierra un último job que se
ejecuta incluso después de shards fallidos:

```yaml
variables:
  PROBARA_ENABLED: $[ ne(variables['System.PullRequest.IsFork'], 'True') ]

jobs:
  - job: create_run
    pool:
      vmImage: ubuntu-latest
    steps:
      - task: NodeTool@0
        inputs:
          versionSpec: '22.x'
      - script: |
          set -e
          ulid=$(npx --yes @probara/cli@0.2 run create)
          echo "##vso[task.setvariable variable=ulid;isOutput=true]$ulid"
        name: probara
        env:
          PROBARA_API_TOKEN: $(PROBARA_API_TOKEN)
          PROBARA_PROJECT: SHOP

  - job: test
    dependsOn: create_run
    strategy:
      parallel: 4
    variables:
      PROBARA_RUN_ULID: $[ dependencies.create_run.outputs['probara.ulid'] ]
    pool:
      vmImage: ubuntu-latest
    steps:
      - task: NodeTool@0
        inputs:
          versionSpec: '22.x'
      - script: npm ci
      - script: npx jest --ci --shard=$(System.JobPositionInPhase)/$(System.TotalJobsInPhase)
        env:
          PROBARA_API_TOKEN: $(PROBARA_API_TOKEN)
          PROBARA_PROJECT: SHOP
          PROBARA_RUN_ULID: $(PROBARA_RUN_ULID)

  - job: close_run
    dependsOn: [create_run, test]
    condition: always()
    variables:
      PROBARA_RUN_ULID: $[ dependencies.create_run.outputs['probara.ulid'] ]
    pool:
      vmImage: ubuntu-latest
    steps:
      - task: NodeTool@0
        inputs:
          versionSpec: '22.x'
      - script: npx --yes @probara/cli@0.2 run close
        env:
          PROBARA_API_TOKEN: $(PROBARA_API_TOKEN)
          PROBARA_PROJECT: SHOP
          PROBARA_RUN_ULID: $(PROBARA_RUN_ULID)
```

`System.JobPositionInPhase` empieza en 1, como los shards de Jest.

### Forks y detección del CI

Los builds de pull requests desde forks no reciben variables secretas salvo que **Make secrets
available to builds of forks** esté activado: déjalo desactivado. Azure deja tal cual una macro que
no puede resolver, así que en el build de un fork `$(PROBARA_API_TOKEN)` llega al paso como ese
texto literal, un token que Probara rechaza con 401: el reporter registraría el 401 en cada
ejecución (el código de salida de Jest sigue siendo el de las pruebas), y `run create` haría fallar
el primer job. La variable `PROBARA_ENABLED` del pipeline vale `False` cuando
`System.PullRequest.IsFork` es `True`, así que el build de un fork ejecuta sus pruebas con el envío
desactivado, y `run create` y `run close` terminan con código 0.

Con `TF_BUILD=True`, la ejecución se llama `BUILD_DEFINITIONNAME #BUILD_BUILDNUMBER`, y su rama, su
commit y la URL del build salen de las variables del pipeline.

## Bitbucket Pipelines

### 1. Añade la variable

**Repository settings → Pipelines → Repository variables**: nombre `PROBARA_API_TOKEN`, el token como
valor, con **Secured** activado. Bitbucket pasa las variables del repositorio a cada paso, así que el
reporter la encuentra en `npx jest`.

### 2. El pipeline

```yaml
image: node:22

pipelines:
  default:
    - step:
        name: Jest
        script:
          - npm ci
          - export PROBARA_PROJECT=SHOP
          - npx jest --ci
```

### Pasos en paralelo: una ejecución

Los pasos en paralelo que ejecutan cada uno un `--shard` reportan en una ejecución que crea un primer
paso y cierra un último paso:

```yaml
image: node:22

pipelines:
  default:
    - step:
        name: Create the Probara run
        script:
          - export PROBARA_PROJECT=SHOP
          # Without the token (a fork's build), turn reporting off: run create prints nothing.
          - test -n "$PROBARA_API_TOKEN" || export PROBARA_ENABLED=false
          - PROBARA_RUN_ULID=$(npx --yes @probara/cli@0.2 run create)
          - echo "PROBARA_RUN_ULID=$PROBARA_RUN_ULID" > probara.env
        artifacts:
          - probara.env
    - parallel:
        - step:
            name: Shard 1
            script:
              - npm ci
              - export PROBARA_PROJECT=SHOP $(cat probara.env)
              - npx jest --ci --shard=1/2 || touch shard-1.failed
            artifacts:
              - shard-*.failed
        - step:
            name: Shard 2
            script:
              - npm ci
              - export PROBARA_PROJECT=SHOP $(cat probara.env)
              - npx jest --ci --shard=2/2 || touch shard-2.failed
            artifacts:
              - shard-*.failed
    - step:
        name: Close the Probara run
        script:
          - export PROBARA_PROJECT=SHOP $(cat probara.env)
          - test -n "$PROBARA_API_TOKEN" || export PROBARA_ENABLED=false
          - npx --yes @probara/cli@0.2 run close
          - if ls shard-*.failed >/dev/null 2>&1; then echo "Tests failed in a shard" >&2; exit 1; fi
```

Bitbucket no ejecuta ningún paso después de uno fallido, así que un shard que hiciera fallar su paso
dejaría la ejecución abierta. En su lugar, cada shard deja constancia de las pruebas fallidas en un
artefacto `shard-<n>.failed`, y el último paso cierra la ejecución y luego hace fallar el pipeline si
algún shard dejó uno: los shards aparecen como correctos, y el fallo lo muestra el último paso. Si
aun así el cierre nunca se ejecutó, cierra la ejecución en Probara, o
[a mano](https://docs.probara.net/es/developers/ci-integrations/jest/sharding/#si-el-cierre-nunca-se-ejecutó).

### Forks y detección del CI

Las pull requests desde forks no reciben variables protegidas (**Secured**): el reporter no envía
nada ahí. Con `BITBUCKET_BUILD_NUMBER` definida, la ejecución se llama
`BITBUCKET_REPO_SLUG #BITBUCKET_BUILD_NUMBER`, con la rama `BITBUCKET_BRANCH`, el commit
`BITBUCKET_COMMIT` y un enlace al pipeline.

## Buildkite

### 1. Añade el token

Expón `PROBARA_API_TOKEN` a los pasos desde un almacén de secretos: un hook `environment` del agente
que lo lea de tu gestor de secretos, o
[Buildkite secrets](https://buildkite.com/docs/pipelines/security/secrets/buildkite-secrets).

### 2. El pipeline

Un `pipeline.yml` cuyos jobs en paralelo reportan en una ejecución que crea un primer paso y que se
cierra después de ellos, aunque hayan fallado. Sin `parallelism`, basta con un paso que ejecute
`npx jest --ci`:

```yaml
env:
  PROBARA_PROJECT: SHOP

steps:
  - label: Create the Probara run
    key: create-run
    command: |
      PROBARA_RUN_ULID="$(npx --yes @probara/cli@0.2 run create)"
      if [ -n "$$PROBARA_RUN_ULID" ]; then buildkite-agent meta-data set probara-run "$$PROBARA_RUN_ULID"; fi

  - label: Jest
    depends_on: create-run
    parallelism: 4
    command: |
      npm ci
      export PROBARA_RUN_ULID="$(buildkite-agent meta-data get probara-run --default '')"
      npx jest --ci --shard=$((BUILDKITE_PARALLEL_JOB + 1))/$$BUILDKITE_PARALLEL_JOB_COUNT

  - wait: ~
    continue_on_failure: true

  - label: Close the Probara run
    command: PROBARA_RUN_ULID="$(buildkite-agent meta-data get probara-run --default '')" npx --yes @probara/cli@0.2 run close
```

- `buildkite-agent pipeline upload` sustituye `$NAME` y `${NAME}` al subir el pipeline, y una
  variable que en ese momento no conoce, como `BUILDKITE_PARALLEL_JOB_COUNT`, que solo reciben los
  jobs en paralelo, queda vacía; un `$$` se deja como un `$` para la shell del job, mientras que
  `$(...)` y `$((...))` se dejan tal cual.
- La ejecución se crea en una línea propia, así que un `run create` fallido hace fallar el primer
  paso en lugar de guardar un ULID vacío. Con el envío desactivado (un build de un fork en un agente que define `PROBARA_ENABLED=false`, como se explica abajo),
  `run create` no imprime ningún ULID y termina con 0: no se guarda nada,
  `meta-data get --default ''` da a los demás pasos un ULID vacío en lugar de un error, y también
  se ejecutan con el envío desactivado.
- `BUILDKITE_PARALLEL_JOB` empieza en 0, los shards de Jest en 1.

Con `BUILDKITE=true`, la ejecución se llama `BUILDKITE_PIPELINE_SLUG #BUILDKITE_BUILD_NUMBER`, con la
rama `BUILDKITE_BRANCH`, el commit `BUILDKITE_COMMIT` y la URL del build `BUILDKITE_BUILD_URL`.

### Pull requests desde forks

Buildkite construye pull requests desde forks solo si el pipeline lo permite (desactivado por
defecto). Esos builds se ejecutan en tus agentes, y `pipeline upload` lee el propio `pipeline.yml`
del fork, que también elige la cola de los agentes. El código del fork se ejecuta en la shell del job
como el usuario del agente, así que en un agente que puede leer el token de tu almacén de secretos,
el código del fork también puede leerlo: ningún hook ni paso lo impide.

Mantén desactivados los builds de forks, o mantenlos lejos de esos agentes: su hook `environment`
rechaza un build de un fork (`BUILDKITE_PULL_REQUEST_REPO` lo identifica), y los forks solo se
construyen en una cola o un cluster aparte cuyos agentes no pueden leer el almacén de secretos:

```bash
# The environment hook of the agents that can read the token: no build of a fork runs there.
if [ -n "$BUILDKITE_PULL_REQUEST_REPO" ]; then
  case "${BUILDKITE_PULL_REQUEST_REPO#*://}" in
    github.com/acme/shop.git) ;;
    *)
      echo "Refusing a build of a fork: $BUILDKITE_PULL_REQUEST_REPO" >&2
      exit 1
      ;;
  esac
fi
export PROBARA_API_TOKEN="$(your-secrets-manager get probara-api-token)"
```

`BUILDKITE_PULL_REQUEST_REPO` está vacía fuera de las pull requests, y es una URL `https://` desde
2022 (antes, una `git://`), así que el hook la compara sin el esquema: pon tu repositorio en lugar de
`github.com/acme/shop.git`. Si no coincide, tus propias pull requests también fallan en estos agentes,
lo que la primera de ellas pondrá de manifiesto. En los agentes que construyen forks, define
`PROBARA_ENABLED=false` en su hook `environment`: las pruebas del fork se ejecutan y `npx jest` no
reporta nada, y `run create` y `run close` terminan con 0 sin token.

Relacionado: [Sharding y proyectos](https://docs.probara.net/es/developers/ci-integrations/jest/sharding/) ·
[Archivo de resultados en CI](https://docs.probara.net/es/developers/ci-integrations/jest/results-and-retries/#en-ci) ·
[Solución de problemas](https://docs.probara.net/es/developers/ci-integrations/jest/troubleshooting/) · Fuente:
[docs/ci](https://github.com/cynch-me/probara-sdk/tree/main/packages/jest-reporter/docs/ci)