GitHub Actions para Repositorios Go

Q: ¿Debería la CI usar la misma versión de Go que producción?

La CI debe cumplir o superar la directiva go en go.mod. La versión de tiempo de ejecución de producción es independiente de la toolchain utilizada para compilar.

Q: ¿Cómo ejecutar pruebas con el detector de carreras (race detector)?

Añade un trabajo: go test -race ./... en Linux de 64 bits. Más lento; a menudo nocturno o solo en la rama principal para ahorrar tiempo en PR.

Q: ¿Necesito un trabajo separado por módulo en monorepos?

Usa matrix sobre directorios de módulos o un trabajo desde la raíz del repo con go work en CI. Valida con GOWORK=off antes de las etiquetas de lanzamiento.

Q: ¿Cómo cachear módulos en Actions?

actions/setup-go con cache: true usa hashes de go.sum. Para workspaces, lista cada go.sum en cache-dependency-path.

Q: ¿Cómo probar lanzamientos de etiquetas en CI?

Desencadena el flujo de trabajo en push: tags: ['v*'], ejecuta pruebas completas, y luego adjunta artefactos o ejecuta goreleaser.

Q: ¿Qué permisos necesita la CI?

contents: read para trabajos de prueba. write o id-token solo para trabajos de lanzamiento, firma o despliegue.

Q: ¿Pueden los flujos de trabajo actualizar go.mod automáticamente?

Posible con bots, pero la revisión es esencial. Los PRs de tidy ciegos pueden ocultar dependencias transitivas maliciosas.

GitHub Actions ejecuta las mismas comprobaciones de go test, lint y de higiene de módulos en cada push y pull request.

Los flujos de trabajo bien diseñados almacenan módulos en caché, fijan versiones de Go y bloquean las fusiones antes de que los cambios incorrectos en go.mod lleguen al trunk.

Resumen

Un flujo de trabajo mínimo de Go CI configura Go, descarga módulos con caché, ejecuta pruebas y vet, y falla si go mod tidy cambiara archivos.

Añade golangci-lint, detección de carreras y trabajos de lanzamiento que crean etiquetas semver cuando los mantenedores necesitan automatización.

Mantén los secretos limitados a la obtención de dependencias privadas (GOPRIVATE) y las credenciales de publicación.

Receta

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

# .github/workflows/ci.yml
name: CI
on:
  push:
    branches: [main]
  pull_request:
permissions:
  contents: read
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: '1.26.x'
          cache: true
      - run: go test ./...
      - run: go vet ./...
      - run: go mod tidy && git diff --exit-code go.mod go.sum

Cuándo usar esto:

Repositorio de módulos Go nuevo que necesita comprobaciones de PR antes de fusionar.
Reemplazo de la cultura ad hoc de go test solo local.
Adición de automatización de lanzamientos después de la deriva manual de git tag.
Aplicación de gráficos de módulos limpios en monorepos con filtros de ruta.

Ejemplo de Trabajo

CI completa más trabajo de linting para github.com/myorg/widget:

# .github/workflows/ci.yml
name: CI
on:
  push:
    branches: [main]
  pull_request:
 
permissions:
  contents: read
 
env:
  GOTOOLCHAIN: local
 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
          cache-dependency-path: |
            go.sum
            **/go.sum
 
      - name: Test
        run: go test -count=1 ./...
 
      - name: Vet
        run: go vet ./...
 
      - name: Mod tidy check
        run: go mod tidy && git diff --exit-code go.mod go.sum
 
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
          cache: true
      - uses: golangci/golangci-lint-action@v6
        with:
          version: latest

Lo que esto demuestra:

go-version-file: go.mod alinea la CI con la versión mínima de la toolchain declarada en el módulo.
Las rutas de caché incluyen archivos go.sum anidados para repositorios multi-módulo.
El trabajo de linting separado mantiene la retroalimentación en paralelo sin bloquear el inicio de las pruebas.

Análisis Profundo

Cómo Funciona

actions/checkout clona la referencia de fusión del PR o el SHA del push.
setup-go instala la toolchain y calienta la caché de módulos y compilación.
El trabajo de pruebas compila todos los paquetes (./...) bajo la raíz del módulo.
La comprobación de tidy asegura que los go.mod / go.sum confirmados coincidan con las importaciones.
Los trabajos opcionales publican etiquetas, binarios o índices de módulos.

Desencadenadores del Flujo de Trabajo

Desencadenador	Uso Típico
`pull_request`	Bloquear fusiones al trunk
`push` a `main`	Validación post-fusión + lanzamiento
`push` de etiquetas `v*`	Artefactos de lanzamiento o pruebas de humo de proxy
`workflow_dispatch`	Reconstrucción manual o pipeline de hotfix

Módulos Privados

env:
  GOPRIVATE: github.com/myorg/*
steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-go@v5
    with:
      go-version-file: go.mod
  - run: git config --global url."https://${{ secrets.GH_PAT }}@github.com/".insteadOf "https://github.com/"
    if: env.GOPRIVATE != ''

Usa un PAT con ámbito reducido o un token de GitHub App legible solo por dependencias privadas.

Documenta el mismo prefijo GOPRIVATE para los desarrolladores localmente.

Esquema del Trabajo de Lanzamiento

  release:
    if: github.ref_type == 'tag' && startsWith(github.ref_name, 'v')
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
      - run: go test ./...
      - run: goreleaser release --clean
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

El push de etiquetas activa la compilación después de que las pruebas pasen; goreleaser es opcional pero común para binarios de Go.

Filtros de Ruta de Monorepo

on:
  pull_request:
    paths:
      - '**.go'
      - 'go.mod'
      - 'go.sum'
      - '.github/workflows/**'

Omite trabajos de documentación cuando no cambian rutas que afectan al módulo, pero nunca omitas cuando cambian go.mod.

Errores Comunes

Fijar un parche antiguo de Go en CI mientras go.mod dice 1.26 - Errores de desajuste de toolchain. Solución: usa go-version-file: go.mod o un parche explícito coincidente.
Falta la comprobación de tidy - El trunk acumula requisitos huérfanos. Solución: siempre go mod tidy && git diff --exit-code.
Caché sin clave go.sum - Caché de módulos obsoleta después de incrementos de dependencias. Solución: incluye go.sum en cache-dependency-path.
GOPRIVATE demasiado amplio - Omite accidentalmente sumdb para módulos públicos. Solución: limita solo a prefijos de organización.
Ejecutar pruebas sin -count=1 - La caché a nivel de paquete inestable oculta fallos. Solución: usa -count=1 en CI o un paso de limpieza de caché de pruebas.

Alternativas

Alternativa	Usar Cuando	No Usar Cuando
GitLab CI / CircleCI	El estándar de la organización no es GitHub	Ya te has estandarizado en Actions para Go
Nightly completo con race/matriz	Cobertura profunda de concurrencia	Cada PR (demasiado lento)
Runners autoalojados	Hardware personalizado, aislado	Biblioteca pública simple
Solo hooks de pre-commit	Retroalimentación local rápida	Necesitas compuertas forzadas en el servidor

Preguntas Frecuentes

¿Debería la CI usar la misma versión de Go que producción?

La CI debe cumplir o superar la directiva go en go.mod.

La versión de tiempo de ejecución de producción es independiente de la toolchain utilizada para compilar.

¿Cómo ejecutar pruebas con el detector de carreras (race detector)?

Añade un trabajo: go test -race ./... en Linux de 64 bits.

Más lento; a menudo nocturno o solo en la rama principal para ahorrar tiempo en PR.

¿Necesito un trabajo separado por módulo en monorepos?

Usa matrix sobre directorios de módulos o un trabajo desde la raíz del repo con go work en CI.

Valida con GOWORK=off antes de las etiquetas de lanzamiento.

¿Cómo cachear módulos en Actions?

actions/setup-go con cache: true usa hashes de go.sum.

Para workspaces, lista cada go.sum en cache-dependency-path.

¿Debería el lint fallar ante advertencias?

Decisión del equipo.

Empieza solo con errores; aprieta a medida que se reduce la deuda.

¿Cómo probar lanzamientos de etiquetas en CI?

Desencadena el flujo de trabajo en push: tags: ['v*'], ejecuta pruebas completas, y luego adjunta artefactos o ejecuta goreleaser.

¿Qué permisos necesita la CI?

contents: read para trabajos de prueba.

write o id-token solo para trabajos de lanzamiento, firma o despliegue.

¿Pueden los flujos de trabajo actualizar `go.mod` automáticamente?

Posible con bots, pero la revisión es esencial.

Los PRs de tidy ciegos pueden ocultar dependencias transitivas maliciosas.

¿Cuánto tiempo debería tardar la CI?

Menos de 10 minutos para un PR mediano mantiene el flujo del trunk saludable.

Divide el lint/matriz si es más largo; usa filtros de ruta con cuidado.

¿Deberían las pruebas de integración conectarse a servicios reales?

Usa contenedores de servicios o flujos de trabajo dedicados.

Mantén el trabajo de PR por defecto hermético con go test -short cuando sea aplicable.

¿Cómo alinear la versión de Go del flujo de trabajo con `GOTOOLCHAIN`?

Establece GOTOOLCHAIN: local o auto explícitamente en env para evitar descargas sorpresa en CI.

¿Necesitan los PRs de forks un manejo especial?

Usa pull_request con permisos de solo lectura predeterminados de GITHUB_TOKEN.

Evita pasar secretos a flujos de trabajo de forks no confiables sin compuertas de aprobación.

Relacionado

Estrategias de Ramificación y Flujo Basado en Trunk - Las compuertas de CI que espera el trunk
Etiquetas Firmadas y Lanzamientos de Módulos Go - Pipelines de lanzamiento activados por etiquetas
Revisión de Código con PRs de GitHub - Lo que los revisores esperan de una CI en verde
Patrones Git de Monorepo con go work - Rutas de flujo de trabajo multi-módulo
Mejores Prácticas de Git y GitHub - Hábitos de Git y CI para todo el equipo

Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado de Green Tea GC, go fix modernizadores - 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 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).

Los flujos de trabajo bien diseñados almacenan módulos en caché, fijan versiones de Go y bloquean las fusiones antes de que los cambios incorrectos en go.mod lleguen al trunk.

Resumen

Un flujo de trabajo mínimo de Go CI configura Go, descarga módulos con caché, ejecuta pruebas y vet, y falla si go mod tidy cambiara archivos.

Añade golangci-lint, detección de carreras y trabajos de lanzamiento que crean etiquetas semver cuando los mantenedores necesitan automatización.

Mantén los secretos limitados a la obtención de dependencias privadas (GOPRIVATE) y las credenciales de publicación.

Receta

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

# .github/workflows/ci.yml
name: CI
on:
  push:
    branches: [main]
  pull_request:
permissions:
  contents: read
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: '1.26.x'
          cache: true
      - run: go test ./...
      - run: go vet ./...
      - run: go mod tidy && git diff --exit-code go.mod go.sum

Cuándo usar esto:

Repositorio de módulos Go nuevo que necesita comprobaciones de PR antes de fusionar.
Reemplazo de la cultura ad hoc de go test solo local.
Adición de automatización de lanzamientos después de la deriva manual de git tag.
Aplicación de gráficos de módulos limpios en monorepos con filtros de ruta.

Ejemplo de Trabajo

CI completa más trabajo de linting para github.com/myorg/widget:

# .github/workflows/ci.yml
name: CI
on:
  push:
    branches: [main]
  pull_request:
 
permissions:
  contents: read
 
env:
  GOTOOLCHAIN: local
 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
          cache-dependency-path: |
            go.sum
            **/go.sum
 
      - name: Test
        run: go test -count=1 ./...
 
      - name: Vet
        run: go vet ./...
 
      - name: Mod tidy check
        run: go mod tidy && git diff --exit-code go.mod go.sum
 
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
          cache: true
      - uses: golangci/golangci-lint-action@v6
        with:
          version: latest

Lo que esto demuestra:

go-version-file: go.mod alinea la CI con la versión mínima de la toolchain declarada en el módulo.
Las rutas de caché incluyen archivos go.sum anidados para repositorios multi-módulo.
El trabajo de linting separado mantiene la retroalimentación en paralelo sin bloquear el inicio de las pruebas.

Análisis Profundo

Cómo Funciona

actions/checkout clona la referencia de fusión del PR o el SHA del push.
setup-go instala la toolchain y calienta la caché de módulos y compilación.
El trabajo de pruebas compila todos los paquetes (./...) bajo la raíz del módulo.
La comprobación de tidy asegura que los go.mod / go.sum confirmados coincidan con las importaciones.
Los trabajos opcionales publican etiquetas, binarios o índices de módulos.

Desencadenadores del Flujo de Trabajo

Desencadenador	Uso Típico
`pull_request`	Bloquear fusiones al trunk
`push` a `main`	Validación post-fusión + lanzamiento
`push` de etiquetas `v*`	Artefactos de lanzamiento o pruebas de humo de proxy
`workflow_dispatch`	Reconstrucción manual o pipeline de hotfix

Módulos Privados

env:
  GOPRIVATE: github.com/myorg/*
steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-go@v5
    with:
      go-version-file: go.mod
  - run: git config --global url."https://${{ secrets.GH_PAT }}@github.com/".insteadOf "https://github.com/"
    if: env.GOPRIVATE != ''

Usa un PAT con ámbito reducido o un token de GitHub App legible solo por dependencias privadas.

Documenta el mismo prefijo GOPRIVATE para los desarrolladores localmente.

Esquema del Trabajo de Lanzamiento

  release:
    if: github.ref_type == 'tag' && startsWith(github.ref_name, 'v')
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
      - run: go test ./...
      - run: goreleaser release --clean
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

El push de etiquetas activa la compilación después de que las pruebas pasen; goreleaser es opcional pero común para binarios de Go.

Filtros de Ruta de Monorepo

on:
  pull_request:
    paths:
      - '**.go'
      - 'go.mod'
      - 'go.sum'
      - '.github/workflows/**'

Omite trabajos de documentación cuando no cambian rutas que afectan al módulo, pero nunca omitas cuando cambian go.mod.

Errores Comunes

Fijar un parche antiguo de Go en CI mientras go.mod dice 1.26 - Errores de desajuste de toolchain. Solución: usa go-version-file: go.mod o un parche explícito coincidente.
Falta la comprobación de tidy - El trunk acumula requisitos huérfanos. Solución: siempre go mod tidy && git diff --exit-code.
Caché sin clave go.sum - Caché de módulos obsoleta después de incrementos de dependencias. Solución: incluye go.sum en cache-dependency-path.
GOPRIVATE demasiado amplio - Omite accidentalmente sumdb para módulos públicos. Solución: limita solo a prefijos de organización.
Ejecutar pruebas sin -count=1 - La caché a nivel de paquete inestable oculta fallos. Solución: usa -count=1 en CI o un paso de limpieza de caché de pruebas.

Alternativas

Alternativa	Usar Cuando	No Usar Cuando
GitLab CI / CircleCI	El estándar de la organización no es GitHub	Ya te has estandarizado en Actions para Go
Nightly completo con race/matriz	Cobertura profunda de concurrencia	Cada PR (demasiado lento)
Runners autoalojados	Hardware personalizado, aislado	Biblioteca pública simple
Solo hooks de pre-commit	Retroalimentación local rápida	Necesitas compuertas forzadas en el servidor

Preguntas Frecuentes

¿Debería la CI usar la misma versión de Go que producción?

La CI debe cumplir o superar la directiva go en go.mod.

La versión de tiempo de ejecución de producción es independiente de la toolchain utilizada para compilar.

¿Cómo ejecutar pruebas con el detector de carreras (race detector)?

Añade un trabajo: go test -race ./... en Linux de 64 bits.

Más lento; a menudo nocturno o solo en la rama principal para ahorrar tiempo en PR.

¿Necesito un trabajo separado por módulo en monorepos?

Usa matrix sobre directorios de módulos o un trabajo desde la raíz del repo con go work en CI.

Valida con GOWORK=off antes de las etiquetas de lanzamiento.

¿Cómo cachear módulos en Actions?

actions/setup-go con cache: true usa hashes de go.sum.

Para workspaces, lista cada go.sum en cache-dependency-path.

¿Debería el lint fallar ante advertencias?

Decisión del equipo.

Empieza solo con errores; aprieta a medida que se reduce la deuda.

¿Cómo probar lanzamientos de etiquetas en CI?

Desencadena el flujo de trabajo en push: tags: ['v*'], ejecuta pruebas completas, y luego adjunta artefactos o ejecuta goreleaser.

¿Qué permisos necesita la CI?

contents: read para trabajos de prueba.

write o id-token solo para trabajos de lanzamiento, firma o despliegue.

¿Pueden los flujos de trabajo actualizar `go.mod` automáticamente?

Posible con bots, pero la revisión es esencial.

Los PRs de tidy ciegos pueden ocultar dependencias transitivas maliciosas.

¿Cuánto tiempo debería tardar la CI?

Menos de 10 minutos para un PR mediano mantiene el flujo del trunk saludable.

Divide el lint/matriz si es más largo; usa filtros de ruta con cuidado.

¿Deberían las pruebas de integración conectarse a servicios reales?

Usa contenedores de servicios o flujos de trabajo dedicados.

Mantén el trabajo de PR por defecto hermético con go test -short cuando sea aplicable.

¿Cómo alinear la versión de Go del flujo de trabajo con `GOTOOLCHAIN`?

Establece GOTOOLCHAIN: local o auto explícitamente en env para evitar descargas sorpresa en CI.

¿Necesitan los PRs de forks un manejo especial?

Usa pull_request con permisos de solo lectura predeterminados de GITHUB_TOKEN.

Evita pasar secretos a flujos de trabajo de forks no confiables sin compuertas de aprobación.

Relacionado

Estrategias de Ramificación y Flujo Basado en Trunk - Las compuertas de CI que espera el trunk
Etiquetas Firmadas y Lanzamientos de Módulos Go - Pipelines de lanzamiento activados por etiquetas
Revisión de Código con PRs de GitHub - Lo que los revisores esperan de una CI en verde
Patrones Git de Monorepo con go work - Rutas de flujo de trabajo multi-módulo
Mejores Prácticas de Git y GitHub - Hábitos de Git y CI para todo el equipo

Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado de Green Tea GC, go fix modernizadores - 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 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).

GitHub Actions para Repositorios Go

Buscar en la documentación

GitHub Actions para Repositorios Go