Puertas de Calidad de CI: Lint, Test, Race, Vuln

Los servicios Go de producción necesitan una plantilla de pipeline de CI que bloquee la fusión hasta que pasen el formato, el análisis estático, las pruebas, la detección de carreras y los escaneos de vulnerabilidades.

Esta página es un punto de partida para copiar y pegar que los equipos pueden adaptar para GitHub Actions, GitLab CI o Buildkite.

Receta

Tarjeta de receta de referencia rápida, lista para copiar y pegar.

# .github/workflows/go-quality.yml
name: go-quality
on: [pull_request]
jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: '1.26.x'
          cache: true
      - run: test -z "$(gofmt -l .)"
      - run: go vet ./...
      - run: go test -race -count=1 ./...
      - uses: golangci/golangci-lint-action@v6
        with:
          version: v2.1.6
      - run: go install golang.org/x/vuln/cmd/govulncheck@latest
      - run: govulncheck ./...

Cuándo usar esto:

• Crear el primer flujo de trabajo para un nuevo microservicio Go.
• Auditar si los escaneos de carreras y vulnerabilidades son opcionales cuando deberían ser obligatorios.
• Equipo de plataforma publicando un pipeline de referencia para docenas de repos.
• Elemento de acción posterior al incidente: "añadir govulncheck a CI".

Ejemplo de Trabajo

Flujo de trabajo completo de GitHub Actions con verificación de module tidy:

name: go-quality
on:
  pull_request:
  push:
    branches: [main]
 
permissions:
  contents: read
 
jobs:
  gate:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v4
 
      - uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
          cache-dependency-path: go.sum
 
      - name: Verificar module tidy
        run: |
          go mod tidy
          git diff --exit-code go.mod go.sum
 
      - name: Formato
        run: test -z "$(gofmt -l .)"
 
      - name: Vet
        run: go vet ./...
 
      - name: Probar con detector de carreras
        run: go test -race -count=1 -timeout=10m ./...
 
      - name: golangci-lint
        uses: golangci/golangci-lint-action@v6
        with:
          version: v2.1.6
          args: --timeout=5m ./...
 
      - name: govulncheck
        run: |
          go install golang.org/x/vuln/cmd/govulncheck@latest
          govulncheck ./...

Protección de ramas (documentar para administradores):

• Requerir el estado go-quality / gate antes de fusionar.
• Descartar revisiones obsoletas en nuevos pushes.
• Requerir historial lineal si tu equipo usa squash merge.

Lo que esto demuestra:

• Verificación de Tidy previene la deriva de dependencias sin revisión.
• Race se ejecuta en cada PR, no solo nocturnamente.
• govulncheck usa el mismo grafo de módulos que las pruebas.
• go-version-file rastrea go.mod automáticamente.

Inmersión Profunda

Cómo Funciona

• La CI clona un árbol limpio (sin omisiones de hooks locales).
• go test -race instrumenta los accesos a memoria; los fallos incluyen pilas de goroutines.
• golangci-lint carga .golangci.yml desde la raíz del repositorio.
• govulncheck informa de símbolos vulnerables alcanzables, no de todos los titulares de CVE transitivos.

Orden de Puertas y Paralelismo

        +--> format + vet (rápido)
        |
PR ----+--> go test -race
        |
        +--> golangci-lint
        |
        +--> govulncheck

Ejecuta trabajos independientes en una matriz paralela para monorepos:

strategy:
  matrix:
    module: [services/api, services/worker, libs/auth]
steps:
  - run: cd ${{ matrix.module }} && go test -race ./...

Tabla de Referencia de Puertas

Notas de Go

# Divide las pruebas en repositorios grandes
go test -race -count=1 $(go list ./... | head -20)
 
# Guarda los módulos en CI (setup-go se encarga en GitHub)
GOMODCACHE=$RUNNER_TEMP/gomodcache go test ./...

Establece GOTOOLCHAIN=local o fija go-version explícitamente para reproducibilidad.

Trampas Comunes

• Race solo en la rama principal - Los PR fusionan carreras en producción. Solución: Requerir -race en cada trabajo de PR.
• Advertencias de govulncheck ignoradas - Los equipos las silencian sin ruta de actualización. Solución: Clasifica por severidad; actualiza módulos o documenta el riesgo aceptado con fecha de caducidad.
• Timeout predeterminado de golangci-lint de 1m - Los monorepos grandes fallan de forma inestable. Solución: --timeout=5m y división de módulos.
• Omitir vet porque lint incluye govet - Se rompe cuando el trabajo de lint se omite. Solución: Mantén vet en el trabajo rápido o exige lint como verificación requerida.
• Las pruebas de integración necesitan Docker - El trabajo solo pasa las pruebas unitarias. Solución: Separa el trabajo integration con servicios; aún así bloquea la fusión.
• govulncheck@latest sin fijar - El comportamiento de la CI cambia silenciosamente. Solución: Fija la versión en el flujo de trabajo o en tools.go.

Alternativas

Preguntas Frecuentes

Relacionado

• Conceptos Básicos de Calidad de Código - equivalentes locales de las puertas de CI
• Configuración de golangci-lint - configuración del trabajo de lint
• govulncheck para Vulnerabilidades de Dependencias - clasificación de vulnerabilidades
• Hooks de Pre-commit y Listas de Verificación de Revisión - ruta rápida local
• staticcheck y golangci-lint en CI - profundidad del analizador

Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado Green Tea GC, modernizadores de go fix - verifica el parche en la compilación), chi (última versión - verifica en la compilación), gin (última versión - verifica en la compilación), echo (última versión - verifica en la compilación), google.golang.org/grpc (última versión - verifica en la compilación), sigs.k8s.io/controller-runtime (última versión - verifica en la compilación), kubebuilder (última versión - verifica en la compilación), tinygo (última versión - verifica los objetivos de la placa en la compilación), wazero (última versión - verifica en la compilación), y golangci-lint (última versión - verifica el conjunto de linters en la compilación).