Git y GitHub para Proyectos Laravel con Docker

Introducción

Este tutorial integra Git, GitHub y Docker para gestionar el ciclo de vida completo de un proyecto Laravel, desde el entorno de desarrollo hasta el despliegue automático con integración continua (CI/CD). Cubriremos la configuración inicial, el control de versiones con Docker, las buenas prácticas para entornos containerizados y la automatización con GitHub Actions.

---

Paso 1: Configuración inicial del repositorio

1.1 Crear un nuevo repositorio en GitHub

1. Inicia sesión en GitHub.com y haz clic en el botón "+" → "New repository"

2. Asigna un nombre descriptivo al repositorio

3. No inicialices el repositorio con README, .gitignore o licencia (los añadirás localmente)

4. Haz clic en "Create repository"

1.2 Inicializar el repositorio local con el entorno Docker

bash

# Crear la estructura del proyecto con Docker
mkdir mi-proyecto-laravel
cd mi-proyecto-laravel

# Inicializar Git
git init

1.3 Crear el archivo .gitignore

El archivo .gitignore es crucial en proyectos Dockerizados. Excluye los siguientes elementos del control de versiones :

text

# Dependencias
/vendor/
/node_modules/
.docker/

# Archivos de entorno
.env
.env.backup
docker-compose.override.yml

# Datos de Docker (base de datos persistente)
db_data/
/.docker/

# Archivos de Laravel generados
/public/hot
/public/storage
/storage/*.key

# Logs y caché
*.log
.phpunit.result.cache
npm-debug.log
yarn-error.log

# Configuración de IDE
/.idea/
/.vscode/

Importante: El directorio .docker/ que contiene datos persistentes de la base de datos debe excluirse del control de versiones, ya que puede contener información sensible y su sincronización entre equipos no es práctica .

1.4 Commit inicial

bash

git add .
git commit -m "Initial commit with Docker setup"

1.5 Conectar con el repositorio remoto

bash

git remote add origin https://github.com/tu-usuario/tu-repositorio.git
git branch -M main
git push -u origin main

Después de actualizar GitHub, verás todos tus archivos de configuración Docker junto con la estructura del proyecto .

---

Paso 2: Estructura del proyecto Dockerizado

Para mantener el repositorio limpio y organizado, utiliza esta estructura :

text

mi-proyecto-laravel/
├── .github/
│   └── workflows/          # CI/CD con GitHub Actions
│       ├── ci.yml
│       └── deploy.yml
├── docker/
│   ├── php/
│   │   ├── Dockerfile      # Multi-stage para dev/prod
│   │   ├── php.dev.ini
│   │   └── php.prod.ini
│   └── nginx/
│       ├── nginx-dev.conf
│       └── nginx-prod.conf
├── src/                    # Código fuente de Laravel
├── docker-compose.yml      # Configuración de servicios
├── .env.example            # Plantilla de variables de entorno
├── .gitignore
└── README.md

---

Paso 3: Variables de entorno con Git

El archivo .env nunca debe subirse a GitHub, ya que contiene credenciales y secretos . En su lugar:

3.1 Crear .env.example

bash

cp .env .env.example

Edita .env.example para reemplazar valores sensibles con placeholders:

env

APP_NAME=Laravel
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost

DB_CONNECTION=mysql
DB_HOST=db
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=laravel
DB_PASSWORD=your_password_here

3.2 Documentar variables de entorno

En tu README.md, documenta todas las variables necesarias, para que cada desarrollador pueda crear su propio .env .

3.3 Configuración de UID/GID para Docker

En equipos con Linux, el usuario del contenedor debe coincidir con el del host para evitar problemas de permisos :

bash

echo "UID=$(id -u)" >> .env
echo "GID=$(id -g)" >> .env
echo "USERNAME=$(whoami)" >> .env

Nota: .env se genera localmente y nunca se sube a GitHub .

---

Paso 4: Flujo de trabajo con ramas

Utiliza una estrategia de ramificación eficiente para tu proyecto Dockerizado :

4.1 Estructura de ramas

Rama	Propósito
main	Código estable para producción
develop	Integración de funcionalidades
feature/*	Desarrollo de nuevas características
bugfix/*	Corrección de errores
hotfix/*	Correcciones urgentes en producción

4.2 Crear una nueva funcionalidad

bash

# Desde develop
git checkout -b feature/autenticacion develop

# Hacer cambios, probar con Docker
docker compose up -d

# Commit con mensaje semántico
git add .
git commit -m "feat: implement autenticación de usuarios"

# Subir la rama
git push origin feature/autenticacion

4.3 Crear Pull Request

1. En GitHub, abre un Pull Request de feature/autenticacion a develop

2. Asegura que los tests de CI pasen

3. Solicita revisión de al menos un compañero

Recomendación: Configura protección de ramas en GitHub para requerir aprobación y tests antes de fusionar .

---

Paso 5: CI/CD con GitHub Actions

5.1 Workflow de Integración Continua (CI)

Crea .github/workflows/ci.yml para ejecutar tests automáticamente en cada push o PR :

yaml

name: Laravel CI

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

jobs:
  tests:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'
          extensions: sqlite3, pdo_sqlite, pdo_mysql
      
      - name: Copy Environment
        run: cp .env.example .env
      
      - name: Install Dependencies
        run: composer install --prefer-dist --no-progress
      
      - name: Generate Key
        run: php artisan key:generate
      
      - name: Run Tests
        run: php artisan test
      
      - name: Static Analysis
        run: vendor/bin/phpstan analyse --level=5

5.2 Workflow de Deployment

Crea .github/workflows/deploy.yml para despliegues automáticos a Laravel Cloud :

yaml

name: Deploy to Laravel Cloud

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to Laravel Cloud
        run: |
          curl -X POST "${{ secrets.LARAVEL_CLOUD_DEPLOY_HOOK }}?commit_hash=${{ github.sha }}"

Configuración previa:

1. Ve a Settings → Secrets and variables → Actions en tu repositorio de GitHub

2. Añade el secreto LARAVEL_CLOUD_DEPLOY_HOOK con la URL de tu deploy hook de Laravel Cloud 

5.3 Workflow con Docker Build

Para proyectos que requieran construir y pushear imágenes Docker :

yaml

name: Build and Deploy Docker Image

on:
  push:
    branches: [ main ]

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
      
      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_TOKEN }}
      
      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: tu-usuario/mi-app:latest

---

Paso 6: Buenas prácticas para Git + Docker

✅ Lo que debes hacer

• Subir archivos de configuración Docker al repositorio, ya que definen el entorno de desarrollo y producción 

• Excluir datos de volúmenes (db_data/, .docker/) del control de versiones 

• Usar .env.example para documentar variables de entorno 

• Incluir pasos de build de Docker en CI para validar que la imagen se construye correctamente 

• Documentar comandos Docker en el README para facilitar la incorporación de nuevos miembros al equipo 

❌ Lo que debes evitar

• No subir .env (contiene credenciales y secrets) 

• No subir vendor/ ni node_modules/ (se regeneran con Composer/NPM)

• No subir datos de la base de datos desde volúmenes Docker 

• No usar --force en ramas compartidas

• No ignorar los tests antes de fusionar un PR

---

Paso 7: Comandos esenciales para el flujo de trabajo

Iniciar un nuevo proyecto Dockerizado

bash

git clone https://github.com/tu-usuario/tu-repositorio.git
cd tu-repositorio

# Configurar variables de entorno
cp .env.example .env

# Ajustar UID/GID para Linux
echo "UID=$(id -u)" >> .env
echo "GID=$(id -g)" >> .env

# Levantar contenedores
docker compose up -d

# Instalar dependencias de Laravel
docker compose exec app composer install

# Generar clave
docker compose exec app php artisan key:generate

Comandos de Git con contexto Docker

Acción	Comando
Verificar estado de contenedores	docker compose ps
Commit de cambios	git add . && git commit -m "feat: description"
Subir cambios	git push origin feature/nombre
Ver historial	git log --oneline

Seguridad y secrets en GitHub

Para almacenar de forma segura las credenciales necesarias para el despliegue automatizado:

1. Ve a Settings → Secrets and variables → Actions en tu repositorio de GitHub

2. Añade los siguientes secretos según tu proveedor de despliegue :

Secreto	Uso
SSH_HOST	IP/servidor para despliegue SSH
SSH_USER	Usuario SSH
SSH_PRIVATE_KEY	Clave privada SSH
LARAVEL_CLOUD_DEPLOY_HOOK	URL de deploy hook de Laravel Cloud