GitHub Actions - Guía Completa

Guía completa para configurar y usar GitHub Actions en joko-security para CI/CD automatizado.

📋 Tabla de Contenidos

Configuración Inicial
Workflows Disponibles
Inicio Rápido - Publicar Versión
Verificar Publicación
Consumir Packages
Troubleshooting
Avanzado

⚙️ Configuración Inicial

1. Habilitar Permisos en GitHub (Una sola vez)

CRÍTICO: Sin estos permisos, los workflows no podrán publicar packages.

Ve a: https://github.com/jokoframework/security/settings/actions
En "Workflow permissions":
- ✅ Selecciona "Read and write permissions"
- ✅ Marca "Allow GitHub Actions to create and approve pull requests"
Click "Save"

2. Estructura de Archivos

.github/
└── workflows/
    ├── ci.yml.template              # CI - Build y tests automáticos
    ├── publish.yml         # Publicación a GitHub Packages
    └── settings.xml        # Configuración Maven para workflows

3. Verificar Workflows Activos

Ve a la pestaña "Actions" en GitHub
Deberías ver:
- ✅ CI - Build and Test
- ✅ Publish to GitHub Packages

🔧 Workflows Disponibles

1. CI - Build and Test

Archivo: .github/workflows/ci.yml

Se ejecuta automáticamente en:

Push a develop, main, o branches feature/**
Pull requests a develop o main

Acciones:

Checkout código
Setup JDK 17
Build con Maven
Ejecutar tests
OWASP Dependency Check
Upload artifacts (test results, reports)

Duración: ~3-5 minutos

Outputs:

Test results en artifacts
OWASP report en artifacts
Build summary en GitHub

2. Publish to GitHub Packages

Archivo: .github/workflows/publish.yml

Se ejecuta en:

Tags con formato v*.*.* (ej: v2.0.0, v2.0.1)
Manual desde GitHub UI (workflow_dispatch)

Acciones:

Checkout código
Setup JDK 17
Configurar Maven settings
Extraer versión del tag
Actualizar pom.xml con versión del tag
Build con Maven
Ejecutar tests
Deploy a GitHub Packages

Duración: ~5-8 minutos

Outputs:

5 packages publicados:
- joko-security-core
- joko-security-storage-postgres
- joko-security-web
- joko-security-autoconfigure
- joko-security-starter

Permisos configurados:

permissions:
  contents: read # Leer código del repositorio
  packages: write # Publicar en GitHub Packages

🚀 Inicio Rápido - Publicar Versión

Opción A: Automática con Git Tag (Recomendada)

# 1. Asegúrate de estar en la rama correcta
git checkout develop
git pull origin develop

# 2. (Opcional) Actualizar versión en pom.xml
# Si la versión ya es correcta, saltar este paso
./mvnw versions:set -DnewVersion=2.0.1 -DgenerateBackupPoms=false

# Commit cambios de versión
git add pom.xml */pom.xml
git commit -m "chore: Bump version to 2.0.1"
git push origin develop

# 3. Crear tag y publicar
git tag -a v2.0.1 -m "Release 2.0.1 - Descripción de cambios"
git push origin develop --tags

# 4. ✨ GitHub Actions publicará automáticamente
# Ve a: https://github.com/jokoframework/security/actions

Nota: El tag DEBE seguir el formato v*.*.* (con la 'v' al inicio).

Opción B: Manual desde GitHub UI

Ve a: https://github.com/jokoframework/security/actions
Click en "Publish to GitHub Packages"
Click en "Run workflow"
Selecciona el branch (develop o feature/modular-refactor)
Click "Run workflow"
Espera ~5-8 minutos

Nota: La versión publicada será la del pom.xml del branch seleccionado.

✅ Verificar Publicación

1. Ver el Workflow

Ve a: https://github.com/jokoframework/security/actions
Click en el último run de "Publish to GitHub Packages"
Verifica que todos los steps estén en verde ✅
En "Summary" verás los artefactos publicados

2. Ver los Packages

Ve a: https://github.com/jokoframework/packages
Deberías ver 5 packages:
- joko-security-core
- joko-security-storage-postgres
- joko-security-web
- joko-security-autoconfigure
- joko-security-starter
Click en cada uno para ver las versiones publicadas

3. Re-ejecutar Workflow Fallido

Si un workflow falla:

GitHub → Actions → Seleccionar el run fallido
Click "Re-run jobs"
Selecciona "Re-run failed jobs" o "Re-run all jobs"

📦 Consumir Packages

1. Configurar Autenticación

Generar GitHub Token

GitHub → Settings → Developer settings → Personal access tokens
Generate new token (classic)
Nombre: "Maven GitHub Packages"
Permisos: ✅ read:packages
Generate token
Copiar el token (ghp_xxxxx)

Para Maven

Crear/editar ~/.m2/settings.xml:

<settings>
    <servers>
        <server>
            <id>github</id>
            <username>TU_USUARIO_GITHUB</username>
            <password>ghp_TuTokenPersonalDeGitHub</password>
        </server>
    </servers>
</settings>

Para Gradle

Crear ~/.gradle/gradle.properties:

gpr.user=tu-usuario-github
gpr.token=ghp_TuTokenPersonalDeGitHub

O usar variables de entorno:

export GITHUB_USERNAME=tu-usuario-github
export GITHUB_TOKEN=ghp_TuTokenPersonalDeGitHub

2. Agregar Dependencia

Maven (pom.xml)

<repositories>
    <repository>
        <id>github</id>
        <url>https://maven.pkg.github.com/jokoframework/security</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>io.github.jokoframework</groupId>
        <artifactId>joko-security-starter</artifactId>
        <version>2.0.1</version>
    </dependency>
</dependencies>

Gradle (build.gradle)

repositories {
    mavenCentral()
    maven {
        url = uri("https://maven.pkg.github.com/jokoframework/security")
        credentials {
            username = project.findProperty("gpr.user") ?: System.getenv("GITHUB_USERNAME")
            password = project.findProperty("gpr.token") ?: System.getenv("GITHUB_TOKEN")
        }
    }
}

dependencies {
    implementation 'io.github.jokoframework:joko-security-starter:2.0.1'
}

3. Compilar Proyecto

# Maven
mvn clean install

# Gradle
./gradlew build

🐛 Troubleshooting

Error: "Resource not accessible by integration"

Causa: Falta configurar permisos de workflow.

Solución: Ve a Configuración Inicial y configura "Read and write permissions".

Error: "401 Unauthorized" al consumir packages

Causa: Falta configurar GitHub token en settings.xml o gradle.properties.

Solución:

Genera un GitHub token con permiso read:packages
Agrégalo a ~/.m2/settings.xml (Maven) o ~/.gradle/gradle.properties (Gradle)
Verifica que el <id> en settings.xml coincida con el del pom.xml (github)

Error: "409 Conflict" al publicar

Causa: La versión ya existe en GitHub Packages.

Solución: GitHub Packages no permite sobrescribir versiones. Opciones:

Incrementar versión y publicar nueva
Eliminar el package existente en GitHub y volver a publicar

Workflow no se ejecuta al hacer push de tag

Causa: El tag no sigue el patrón v*.*.*.

Solución: El tag debe ser:

✅ v2.0.1
✅ v2.1.0
❌ 2.0.1 (sin la 'v')
❌ release-2.0.1

Tests fallan en CI pero pasan localmente

Causa: Diferencias en entorno (BD, configuración, etc.)

Solución:

Verificar que los tests usen H2 in-memory
Revisar configuración en application-test.properties
Ver logs del workflow para detalles del error

Error: "Failed to execute goal" en Maven

Causa: Dependencias faltantes o problemas de compilación.

Solución:

Verificar que todas las dependencias estén disponibles
Limpiar caché: mvn clean
Revisar logs detallados en el workflow

🔍 Avanzado

Autenticación en CI/CD

Los workflows usan GITHUB_TOKEN automático (no requiere configuración):

settings.xml (.github/workflows/settings.xml):

<server>
    <id>github</id>
    <username>${env.GITHUB_ACTOR}</username>
    <password>${env.GITHUB_TOKEN}</password>
</server>

Variables disponibles automáticamente:

GITHUB_ACTOR: Usuario que ejecuta el workflow
GITHUB_TOKEN: Token con permisos del workflow
GITHUB_REF: Referencia git (branch o tag)
GITHUB_SHA: Commit SHA
GITHUB_REPOSITORY: Nombre del repo (jokoframework/security)
GITHUB_WORKSPACE: Directorio de trabajo

Monitoreo

Ver Estado de Workflows

GitHub → Actions
Verás lista de todos los workflow runs con:
- Estado (success, failure, in progress)
- Duración
- Branch/tag que lo disparó

Badges de Estado

Agregar al README.md:

![CI](https://github.com/jokoframework/security/workflows/CI%20-%20Build%20and%20Test/badge.svg)
![Publish](https://github.com/jokoframework/security/workflows/Publish%20to%20GitHub%20Packages/badge.svg)

Debug de Workflows

Ver logs detallados

GitHub → Actions → Select run
Click on job → View logs
Expandir steps para ver output detallado

Agregar variables de debug

En el workflow, agregar:

- name: Debug info
  run: |
    echo "GitHub Actor: $GITHUB_ACTOR"
    echo "GitHub Ref: $GITHUB_REF"
    echo "GitHub SHA: $GITHUB_SHA"
    echo "Workspace: $GITHUB_WORKSPACE"
    mvn --version
    java -version

Mantenimiento

Actualizar Versión de Java

En ambos workflows (publish.yml):

- name: Set up JDK 17
  uses: actions/setup-java@v4
  with:
    java-version: "17" # Cambiar aquí

Actualizar Actions

# Antes
- uses: actions/checkout@v3

# Después
- uses: actions/checkout@v4

Agregar Nuevos Workflows

Crear archivo en .github/workflows/nombre.yml
Definir triggers y jobs
Commit y push
El workflow estará disponible inmediatamente

Testing Local de Workflows

Antes de publicar:

# Simular lo que hace el workflow
mvn clean install
mvn test
mvn org.owasp:dependency-check-maven:check

📋 Checklist de Publicación

Antes de publicar, verifica:

Tests pasan localmente: mvn test
Versión actualizada en pom.xml (si corresponde)
Cambios commiteados y pusheados
Tag creado con formato vX.Y.Z
Permisos de workflow configurados en GitHub
Workflow ejecutado sin errores
Packages visibles en GitHub

🎯 Flujo Completo de Desarrollo

Desarrollo Diario

# Crear feature branch
git checkout -b feature/nueva-funcionalidad

# Hacer cambios...
git add .
git commit -m "feat: Nueva funcionalidad"
git push origin feature/nueva-funcionalidad

# CI ejecutará automáticamente tests

# Cuando esté listo, merge a develop
git checkout develop
git merge feature/nueva-funcionalidad
git push origin develop

Publicar Release

# 1. Actualizar versión
./mvnw versions:set -DnewVersion=2.0.1 -DgenerateBackupPoms=false

# 2. Commit y push
git add pom.xml */pom.xml
git commit -m "chore: Release 2.0.1"
git push origin develop

# 3. Crear y push tag
git tag -a v2.0.1 -m "Release 2.0.1 - Nueva funcionalidad agregada"
git push origin develop --tags

# 4. ✨ GitHub Actions publicará automáticamente
# Verificar en: https://github.com/jokoframework/security/actions

📚 Referencias

GitHub Actions Docs
GitHub Packages Maven
setup-java Action
Maven Deploy Plugin
Guía de empaquetado: PACKAGING_GUIDE.md
Integración: INTEGRATION_GUIDE.md

🚀 Próximos Pasos (Mejoras Futuras)

Última actualización: 2024-12-22 Repositorio: jokoframework/security Versión actual: 2.0.0

Uh oh!

FilesExpand file tree

GITHUB_ACTIONS.md

Latest commit

History

GITHUB_ACTIONS.md

File metadata and controls

GitHub Actions - Guía Completa

📋 Tabla de Contenidos

⚙️ Configuración Inicial

1. Habilitar Permisos en GitHub (Una sola vez)

2. Estructura de Archivos

3. Verificar Workflows Activos

🔧 Workflows Disponibles

1. CI - Build and Test

2. Publish to GitHub Packages

🚀 Inicio Rápido - Publicar Versión

Opción A: Automática con Git Tag (Recomendada)

Opción B: Manual desde GitHub UI

✅ Verificar Publicación

1. Ver el Workflow

2. Ver los Packages

3. Re-ejecutar Workflow Fallido

📦 Consumir Packages

1. Configurar Autenticación

Generar GitHub Token

Para Maven

Para Gradle

2. Agregar Dependencia

Maven (pom.xml)

Gradle (build.gradle)

3. Compilar Proyecto

🐛 Troubleshooting

Error: "Resource not accessible by integration"

Error: "401 Unauthorized" al consumir packages

Error: "409 Conflict" al publicar

Workflow no se ejecuta al hacer push de tag

Tests fallan en CI pero pasan localmente

Error: "Failed to execute goal" en Maven

🔍 Avanzado

Autenticación en CI/CD

Monitoreo

Ver Estado de Workflows

Badges de Estado

Debug de Workflows

Ver logs detallados

Agregar variables de debug

Mantenimiento

Actualizar Versión de Java

Actualizar Actions

Agregar Nuevos Workflows

Testing Local de Workflows

📋 Checklist de Publicación

🎯 Flujo Completo de Desarrollo

Desarrollo Diario

Publicar Release

📚 Referencias

🚀 Próximos Pasos (Mejoras Futuras)