Git y GitHub para Proyectos Laravel

Introducción

Este tutorial explica cómo usar Git y GitHub en el contexto específico de un proyecto Laravel. Laravel utiliza Git para el control de versiones y se integra con GitHub para facilitar la colaboración y el despliegue .

---

Paso 1: Configuración inicial de Git

1.1 Verificar que Git está instalado

bash

git --version

Si no está instalado, descárgalo desde git-scm.com .

1.2 Configurar identidad

bash

git config --global user.name "Tu Nombre"
git config --global user.email "tu.email@ejemplo.com"

1.3 Configurar editor por defecto (VS Code)

bash

git config --global core.editor "code --wait"

---

Paso 2: Inicializar Git en un proyecto Laravel

2.1 Inicializar el repositorio

bash

# Navegar a tu proyecto Laravel
cd ruta/de/tu/proyecto-laravel

# Inicializar Git
git init

2.2 Configurar el archivo .gitignore

Laravel incluye un .gitignore por defecto que evita subir archivos innecesarios o sensibles :

text

/vendor/
/node_modules/
.env
.env.testing
storage/*.key
/public/hot
/public/storage
*.log
npm-debug.log
yarn-error.log

Nota: El archivo .env no debe subirse a GitHub ya que contiene información sensible como credenciales de base de datos .

2.3 Agregar archivos y hacer commit inicial

bash

# Agregar todos los archivos
git add .

# Hacer commit inicial
git commit -m "Initial commit"

---

Paso 3: Crear repositorio en GitHub

3.1 Crear repositorio en GitHub

1. Inicia sesión en GitHub.com

2. Haz clic en el botón "+" → "New repository"

3. Asigna un nombre al repositorio (ej: chirper)

4. No inicialices con README, .gitignore o licencia (ya los tienes localmente) 

5. Haz clic en "Create repository"

3.2 Conectar repositorio local con GitHub

bash

# Conectar con el repositorio remoto
git remote add origin https://github.com/tu-usuario/tu-repositorio.git

# Cambiar a la rama main (si no existe)
git branch -M main

# Subir el código inicial
git push -u origin main

Después de refrescar la página de GitHub, verás todo tu código Laravel allí .

---

Paso 4: Estructura de ramas para proyectos Laravel

Un flujo de trabajo recomendado para Laravel es el siguiente :

4.1 Ramas principales

Rama	Propósito
main	Código estable, listo para producción
develop	Rama de integración para desarrollo continuo

4.2 Ramas de funcionalidad y correcciones

Tipo de rama	Nombre	Propósito
Feature	feature/nombre-funcionalidad	Desarrollo de nuevas funcionalidades
Bugfix	bugfix/descripcion-error	Corrección de errores en desarrollo
Hotfix	hotfix/descripcion-error	Corrección urgente en producción

4.3 Crear ramas

bash

# Crear rama develop desde main
git checkout -b develop main

# Crear rama feature
git checkout -b feature/autenticacion develop

# Crear rama hotfix (desde main)
git checkout -b hotfix/error-login main

---

Paso 5: Flujo de trabajo con GitHub Issues

5.1 Crear issues en GitHub

Usa GitHub Issues para gestionar tareas y errores. Asigna un número de issue a cada tarea .

5.2 Vincular commits con issues

bash

git add .
git commit -m "Implementa autenticación de usuarios resolves #3"

Beneficio: En GitHub, el issue #3 mostrará automáticamente el commit relacionado .

5.3 Abrir Pull Requests

1. Terminado el trabajo en feature/autenticacion, haz push:

   bash

   git push origin feature/autenticacion

2. En GitHub, abre un Pull Request (PR) de feature/autenticacion a develop

3. El PR permite:

   • Revisión de código por otros desarrolladores

   • Ejecución automática de tests (CI/CD)

   • Discusión sobre los cambios

---

Paso 6: CI/CD con GitHub Actions

6.1 Configurar pruebas automáticas

Crea el archivo .github/workflows/laravel.yml para ejecutar tests en cada push o PR :

yaml

name: Laravel Tests

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
      
      - name: Install Dependencies
        run: composer install --prefer-dist --no-progress
      
      - name: Copy Environment
        run: cp .env.example .env
      
      - name: Generate Key
        run: php artisan key:generate
      
      - name: Run Tests
        run: php artisan test

6.2 Despliegue automático a Laravel Cloud

Para desplegar automáticamente a Laravel Cloud con un deploy hook :

1. Crear archivo .github/workflows/deploy.yml:

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 }}"

2. Agregar el deploy hook como secreto:

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

• Añade LARAVEL_CLOUD_DEPLOY_HOOK con la URL de tu deploy hook de Laravel Cloud 

6.3 Protección de ramas

Configura reglas de protección para main y develop:

• ✅ Requerir que los tests pasen antes de fusionar un PR

• ✅ Requerir que la rama esté actualizada

• ✅ Requerir revisión de al menos 1 aprobación 

---

Paso 7: Despliegue a servidor

7.1 Script de despliegue manual

Crea un script deploy.sh para despliegues manuales en el servidor :

bash

#!/bin/bash
git pull origin main
composer install --no-interaction --prefer-dist --optimize-autoloader
php artisan migrate --force
php artisan config:cache
php artisan route:cache
php artisan view:cache

7.2 Despliegue con GitHub Actions a VPS

Para despliegue automático a un VPS, usa esta configuración de GitHub Actions :

Secretos necesarios:

• VPS_HOST - IP del servidor

• VPS_USER - Usuario SSH

• SSH_PRIVATE_KEY - Clave privada SSH

• APP_URL - URL de la aplicación

• DB_DATABASE, DB_USERNAME, DB_PASSWORD

---

Paso 8: Buenas prácticas para Laravel con Git

✅ Lo que debes hacer

• Usa .gitignore: Laravel ya viene con uno, no lo modifiques innecesariamente 

• Commits pequeños y descriptivos: Cambios lógicos, fáciles de entender

• Ramas para cada funcionalidad: No trabajes directamente en main o develop

• Actualiza antes de hacer push: git pull antes de git push

• Usa tags para versiones: git tag -a v1.0.0 -m "Release 1.0.0"

❌ Lo que debes evitar

• No subir .env a GitHub (contiene secrets y credenciales) 

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

• No hacer commits gigantes que mezclan múltiples cambios

• No usar --force en ramas compartidas

• No ignorar los tests antes de fusionar un PR

---

Resumen de comandos

Acción	Comando
Crear repositorio	git init
Ver estado	git status
Preparar cambios	git add .
Hacer commit	git commit -m "mensaje"
Conectar remoto	git remote add origin url
Subir código	git push origin main
Bajar código	git pull origin main
Crear rama	git checkout -b feature/nombre
Cambiar rama	git switch nombre-rama
Fusionar rama	git merge feature/nombre
Ver historial	git log --oneline
Crear tag	git tag -a v1.0.0 -m "Release"

---

¡Felicidades! 🎉 Ahora puedes gestionar tu proyecto Laravel con Git y GitHub usando las mejores prácticas específicas para el ecosistema Laravel