Saltar a contenido

Capítulo 15

Git y GitHub

Control de versiones y despliegue profesional

Objetivo

Este capítulo tiene un objetivo muy claro: que el lector comprenda qué es Git, cómo funciona el control de versiones, cómo usar GitHub de forma profesional y cómo integrar ambos con Cloudflare Pages para trabajar con flujos modernos de desarrollo y despliegue continuo.[cite:108][cite:103][cite:100]

Al finalizar, el lector será capaz de administrar proyectos reales con Git, colaborar mediante ramas y pull requests, mantener un historial limpio, automatizar despliegues y organizar repositorios con una estructura profesional apta para productos modernos.[cite:108][cite:103]

¿Qué aprenderás?

  • Qué es Git y por qué transformó el desarrollo de software.
  • Qué es GitHub y en qué se diferencia de Git.[cite:108]
  • Cómo instalar Git y configurarlo correctamente.
  • Qué significan conceptos como commit, branch, merge, remote, fork o pull request.[cite:108]
  • Cómo construir un flujo moderno entre Git, GitHub y Cloudflare Pages.[cite:103][cite:100]
  • Cómo organizar repositorios serios para productos educativos, APIs, sitios y aplicaciones.

Introducción

Imagina que escribes un libro técnico con varios capítulos, pero cada vez que haces un cambio guardas un archivo nuevo con nombres como capitulo_final.md, capitulo_final_bueno.md, capitulo_final_bueno_ahora_si.md y capitulo_final_bueno_ahora_si_2.md. Muy pronto el proyecto se vuelve confuso. Ya no sabes cuál es la versión correcta, qué cambió, quién modificó qué parte ni cómo volver a un estado anterior sin destruir trabajo reciente.

Eso mismo ocurría con muchos proyectos de software antes de que el control de versiones distribuido se popularizara. Git apareció para resolver precisamente ese problema: registrar cambios como snapshots del proyecto, permitir trabajo en paralelo, facilitar fusiones de trabajo y conservar una historia verificable del código.[cite:108]

GitHub añadió encima una capa social, organizativa y operativa: repositorios remotos, colaboración, issues, pull requests, actions, releases y flujos de revisión. Si Git es el motor de control de versiones, GitHub es la plataforma que vuelve ese motor útil para equipos, productos y despliegues reales.

En un contexto moderno, Git y GitHub ya no son solo herramientas de “guardar código”. Son parte de la arquitectura operativa del proyecto. Una rama activa puede disparar un preview deployment en Cloudflare Pages; un merge a main puede publicar producción; una etiqueta puede marcar una release; y un pull request puede convertirse en la unidad natural de revisión y calidad.[cite:103][cite:100]

¿Qué es Git?

Git es un sistema de control de versiones distribuido. Su propósito es registrar cambios en archivos a lo largo del tiempo, permitir trabajar con varias líneas de desarrollo y facilitar colaboración sin depender de una única copia central del repositorio.[cite:108]

Historia

Git fue creado en 2005 por Linus Torvalds para apoyar el desarrollo del kernel de Linux. La motivación principal fue disponer de un sistema rápido, distribuido y robusto después de que el flujo anterior basado en otra herramienta dejara de ser viable.

Aunque hoy Git se usa en casi cualquier tipo de proyecto, su origen importa porque explica su filosofía: rendimiento, historial íntegro, trabajo distribuido y capacidad de operar incluso sin conexión a un servidor central.

Linus Torvalds

Linus Torvalds es también el creador de Linux. En el caso de Git, su aporte no fue solo “inventar una herramienta”, sino definir una forma de pensar el historial del software: cada commit como snapshot del proyecto, cada rama como una línea de desarrollo y cada repositorio como una copia completa del historial.

Control de versiones

El control de versiones permite responder preguntas fundamentales:

  • ¿Qué cambió?
  • ¿Cuándo cambió?
  • ¿Quién lo cambió?
  • ¿Por qué cambió?
  • ¿Cómo volver a una versión anterior?
  • ¿Cómo desarrollar una nueva característica sin romper producción?

Sin control de versiones, un proyecto mediano se vuelve frágil. Con control de versiones, el cambio se vuelve trazable.

Problemas que resuelve

Git resuelve varios problemas clásicos:

  • Sobrescritura accidental de trabajo.
  • Pérdida de historial.
  • Dificultad para colaborar entre varias personas.
  • Imposibilidad práctica de experimentar sin romper la línea principal.
  • Falta de trazabilidad entre versiones del producto.
  • Despliegues manuales opacos y poco repetibles.

Filosofía

La filosofía de Git gira alrededor de varias ideas:

  • El historial es valioso.
  • Cada desarrollador puede tener una copia completa del proyecto.
  • Los cambios deben agruparse en unidades significativas llamadas commits.
  • El trabajo experimental debe poder aislarse en ramas.
  • Fusionar trabajo forma parte natural del desarrollo.

Git no guarda el proyecto como una sucesión ingenua de archivos sueltos. Lo trata como una serie de snapshots y relaciones entre commits. Esa diferencia conceptual es la razón por la que Git resulta tan potente.

¿Qué es GitHub?

GitHub es una plataforma para alojar repositorios Git y colaborar sobre ellos. No reemplaza a Git; se construye sobre Git.

Historia

GitHub nació en 2008 y se convirtió rápidamente en el lugar dominante para compartir y colaborar en proyectos Git. Su crecimiento se apoyó en una idea poderosa: un repositorio no es solo almacenamiento remoto, sino también conversación, revisión, visibilidad y automatización.

Diferencia entre Git y GitHub

Esta distinción debe quedar grabada desde el principio:

  • Git es la herramienta de control de versiones que corre en tu equipo.
  • GitHub es una plataforma que hospeda repositorios Git y añade capacidades de colaboración.

Dicho de otra manera: puedes usar Git sin GitHub, pero no puedes entender GitHub sin Git.

Repositorios

Un repositorio es el contenedor lógico de un proyecto bajo control de versiones. Puede vivir localmente o en GitHub.

Organización

GitHub permite organizar proyectos mediante cuentas personales y organizaciones. En una organización, varios repositorios pueden agruparse bajo el mismo equipo o empresa, con permisos diferenciados por miembros y roles.

Colaboración

GitHub añade piezas fundamentales para el trabajo profesional:

  • Pull requests.
  • Issues.
  • Projects.
  • Discussions.
  • Releases.
  • Secrets.
  • Actions.

La plataforma convierte al repositorio en un espacio operativo, no solo en un respaldo remoto.

Instalación

Instalar Git no es difícil, pero hacerlo bien desde el principio evita muchos problemas posteriores.

Windows

  1. Descargar Git desde el instalador oficial para Windows.
  2. Ejecutar el instalador.
  3. Aceptar la configuración recomendada salvo que exista una necesidad concreta distinta.
  4. Abrir Git Bash o PowerShell.
  5. Verificar instalación con:
git --version

macOS

En macOS puede instalarse mediante el instalador oficial o herramientas como Homebrew.

brew install git

Verificación:

git --version

Linux

En Linux suele instalarse con el gestor de paquetes de la distribución.

Ubuntu/Debian:

sudo apt update
sudo apt install git

Fedora:

sudo dnf install git

Arch:

sudo pacman -S git

Configuración inicial

Git necesita saber al menos dos cosas: tu nombre y tu correo.

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

Para verificar:

git config --global --list

Nombre y correo

Estos datos se guardan dentro de los commits. No controlan autenticación por sí mismos, pero sí forman parte de la identidad histórica del repositorio.

Llaves SSH

Trabajar con SSH es una práctica profesional muy recomendable porque evita introducir credenciales constantemente y separa mejor la autenticación del uso interactivo simple.

Generación de llave:

ssh-keygen -t ed25519 -C "tu-correo@ejemplo.com"

Luego se agrega la clave pública a GitHub desde la configuración de claves SSH.

Para mostrar la clave pública:

cat ~/.ssh/id_ed25519.pub

Tokens

GitHub utiliza tokens para ciertos flujos de autenticación y automatización. También distingue varios tipos de secrets y tokens para repositorios, entornos y organizaciones.[cite:96] En GitHub Actions, además, existe GITHUB_TOKEN, generado automáticamente para cada ejecución y limitado al repositorio del workflow.[cite:109]

Conceptos fundamentales

Repositorio

Es la carpeta del proyecto controlada por Git, junto con su historial.

Commit

Un commit es una unidad de cambio registrada en el historial. No es solo “guardar”; es declarar un punto coherente del proyecto.

Snapshot

Git trata un commit como un snapshot del proyecto en un momento dado. Esa idea ayuda a entender por qué el historial no es una simple lista de diferencias sin contexto.

Working Directory

Es el estado actual de tus archivos en disco, donde editas normalmente.

Staging Area

Es el área intermedia donde decides qué cambios entrarán en el próximo commit.

HEAD apunta normalmente al commit actual o a la rama en la que estás trabajando.

Branch

Una rama es una línea independiente de desarrollo.

Merge

Merge combina historias de ramas distintas. Git crea un nuevo commit de fusión cuando hace falta.

Remote

Un remote es una referencia a otro repositorio, generalmente hospedado en GitHub.

Origin

origin es el nombre por defecto del remote principal cuando clonas un repositorio.

Clone

Clonar significa descargar una copia completa de un repositorio remoto.

Fork

Un fork es una copia de un repositorio bajo otra cuenta o espacio en GitHub, muy usada para colaboración abierta o cuando no se tiene acceso de escritura al original.

Pull Request

Un pull request es una solicitud para revisar e integrar cambios de una rama en otra dentro de GitHub.

Tag

Una tag marca un commit específico, a menudo para señalar versiones.

Release

Una release es una publicación formal de una versión, frecuentemente asociada a una tag.

Flujo básico

El flujo esencial puede resumirse así:

git init
   |
   v
git add
   |
   v
git commit
   |
   v
git push
   |
   v
GitHub
   |
   v
Cloudflare Pages

Explicación del flujo

  1. git init crea el repositorio local.
  2. git add selecciona qué cambios pasarán al siguiente commit.
  3. git commit registra un snapshot con mensaje.
  4. git push envía la rama al repositorio remoto.
  5. GitHub recibe la nueva versión.
  6. Si el repositorio está conectado con Cloudflare Pages, un push o un pull request puede disparar un despliegue automático o un preview deployment.[cite:103]

Si la rama es la rama principal de producción, Pages actualizará el dominio principal del proyecto. Si es una rama secundaria o un pull request, Pages generará un preview con URL propia y lo mantendrá actualizado conforme lleguen nuevos commits.[cite:103]

Comandos principales

A continuación se presentan los comandos clave, no como una lista memorizable sin contexto, sino como herramientas dentro de decisiones reales.

git init

Inicializa un repositorio en la carpeta actual.

git init

Cuándo usarlo: cuando comienzas un proyecto nuevo o conviertes una carpeta existente en repositorio Git.

git clone

Clona un repositorio remoto.

git clone git@github.com:usuario/proyecto.git

Cuándo usarlo: cuando vas a trabajar sobre un repositorio ya existente.

git status

Muestra el estado del working directory y staging area.

git status

Cuándo usarlo: constantemente. Es probablemente el comando más útil del día a día.

git add

Agrega cambios al staging area.

git add README.md
git add src/
git add .

Cuándo usarlo: cuando ya decidiste qué cambios entrarán al siguiente commit.

git commit

Registra un commit.

git commit -m "feat: agrega endpoint de credenciales"

Cuándo usarlo: cuando el conjunto de cambios representa una unidad coherente de trabajo.

git log

Muestra historial.

git log --oneline --graph --decorate --all

Cuándo usarlo: para inspeccionar historia, ramas, merges y contexto.

git diff

Muestra diferencias entre archivos o estados.

git diff
git diff --staged

Cuándo usarlo: antes de commitear y al revisar exactamente qué cambió.

git branch

Lista o crea ramas.

git branch
git branch feature/login

Cuándo usarlo: para ver la estructura de ramas o crear nuevas líneas de trabajo.

git checkout

Comando clásico para cambiar de rama o restaurar archivos.

git checkout main
git checkout -b feature/reportes

Cuándo usarlo: aún es válido, aunque en flujos modernos git switch y git restore suelen resultar más claros.

git switch

Cambia de rama con una semántica más explícita.

git switch main
git switch -c feature/api-qr

Cuándo usarlo: preferiblemente para cambio y creación de ramas.

git merge

Fusiona una rama en otra.

git switch main
git merge feature/api-qr

Cuándo usarlo: cuando se desea integrar una rama sin reescribir historial.

git rebase

Reaplica commits sobre otra base. Git lo documenta como una forma de reproducir cambios sobre otra línea de trabajo, en contraste con merge, que combina endpoints de historias.[cite:95][cite:104]

git switch feature/api-qr
git rebase main

Cuándo usarlo: para mantener una historia lineal o limpiar commits antes de integrar. GitHub advierte que no conviene reescribir historia compartida ya publicada sin cuidado.[cite:101]

git stash

Guarda cambios no comprometidos temporalmente.

git stash
git stash pop

Cuándo usarlo: cuando necesitas cambiar de contexto rápidamente sin crear un commit prematuro.

git pull

Descarga cambios del remoto y los integra.

git pull origin main

Cuándo usarlo: cuando quieres traer cambios remotos y actualizar tu rama actual.

git fetch

Descarga cambios remotos sin fusionarlos automáticamente.

git fetch origin

Cuándo usarlo: cuando quieres inspeccionar antes de integrar.

git push

Envía commits locales al remoto.

git push origin main

Cuándo usarlo: cuando ya quieres publicar trabajo en GitHub.

git remote

Gestiona remotes.

git remote -v
git remote add origin git@github.com:usuario/proyecto.git

Cuándo usarlo: al conectar o inspeccionar repositorios remotos.

git tag

Crea marcas de versión.

git tag v1.0.0
git push origin v1.0.0

Cuándo usarlo: al señalar releases importantes.

git restore

Restaura archivos desde cierto estado.

git restore README.md
git restore --staged README.md

Cuándo usarlo: cuando quieres descartar cambios o sacar un archivo del staging.

git reset

Mueve referencias y, según el modo, también staging o working directory.

git reset --soft HEAD~1
git reset --mixed HEAD~1

Cuándo usarlo: para corregir commits locales o staging antes de publicar. Debe usarse con criterio, especialmente si la historia ya fue compartida.

git revert

Crea un nuevo commit que deshace otro.

git revert HEAD

Cuándo usarlo: cuando necesitas deshacer algo ya publicado sin reescribir el historial.

Branches

Las ramas permiten desarrollar en paralelo sin romper la línea principal.

main

main suele representar la rama estable principal. En muchos equipos está asociada directamente a producción.

develop

En algunos flujos existe una rama develop como integración previa a main.

feature

Las ramas feature/* se usan para nuevas funcionalidades.

hotfix

Las ramas hotfix/* corrigen urgentemente producción.

release

Las ramas release/* ayudan a estabilizar una versión antes de publicarla en ciertos modelos de trabajo.

Buenas prácticas

  • Nombres descriptivos.
  • Ramas cortas y enfocadas.
  • Pull requests pequeños.
  • Integración frecuente.
  • Evitar ramas eternas.

Git Flow

Git Flow usa varias ramas permanentes como main y develop, más ramas auxiliares feature, release y hotfix. Es potente, pero puede resultar pesado para equipos pequeños.

GitHub Flow

GitHub Flow es más simple: una rama principal estable, ramas cortas para cambios, pull request y merge tras revisión. Para productos web modernos conectados a despliegues continuos suele ser un flujo muy natural.

Trunk Based Development

Trunk Based Development empuja integración muy frecuente sobre una rama central, con ramas extremadamente cortas o incluso trabajo directo protegido por revisiones y feature flags. Es ideal para equipos maduros con fuerte disciplina de integración continua.

Conflictos

Qué son

Un conflicto aparece cuando Git no puede reconciliar automáticamente cambios incompatibles entre dos líneas de trabajo.

Cómo se ven

<<<<<<< HEAD
console.log('versión actual');
=======
console.log('versión de otra rama');
>>>>>>> feature/login

Cómo resolverlos

  1. Identificar los archivos en conflicto.
  2. Abrirlos y decidir qué contenido conservar o combinar.
  3. Eliminar marcadores de conflicto.
  4. Guardar.
  5. git add de los archivos resueltos.
  6. Completar el merge o rebase.

Buenas prácticas

  • Hacer pull o fetch con frecuencia.
  • Mantener ramas pequeñas.
  • No acumular semanas de cambios sin integrar.
  • Revisar conflictos con calma; no resolverlos mecánicamente.

Herramientas

Editores como VS Code ofrecen herramientas visuales para aceptar, combinar o comparar cambios durante conflictos.

GitHub en profundidad

GitHub no es solo un “remoto bonito”. Es un sistema completo de trabajo profesional.

Repositorios

Cada repositorio puede contener código, documentación, historial, ramas, releases y automatizaciones.

Issues

Permiten registrar bugs, tareas, ideas y mejoras.

Projects

Sirven para organizar trabajo en tableros o vistas de planificación.

Wiki

Útil para documentación interna, aunque muchos equipos prefieren documentación versionada dentro del propio repositorio.

Actions

GitHub Actions permite automatizar tareas: pruebas, build, lint, publicación y despliegue. No conviene profundizar demasiado aquí, pero sí entender que GitHub puede ejecutar workflows basados en eventos como push o pull_request.

Releases

Las releases formalizan versiones y pueden asociarse a tags, notas de versión y artefactos descargables.

Discussions

Ayudan a separar conversación comunitaria o de producto de issues puramente operativos.

Packages

Permiten publicar paquetes y artefactos dentro del ecosistema GitHub.

Secrets

GitHub distingue secretos a nivel de repositorio, entorno u organización, cada uno con diferentes alcances y permisos.[cite:96] Esto resulta esencial para workflows, despliegues y acceso a APIs.

Deploy Keys

Las deploy keys permiten acceso restringido vía SSH a repositorios concretos, útiles para ciertos entornos automatizados.

GitHub Actions

Introducción

GitHub Actions es la capa de automatización de GitHub.

Qué son

Son workflows definidos en YAML que reaccionan a eventos del repositorio.

Cómo funcionan

Cuando sucede un evento —por ejemplo un push a main o la apertura de un pull request— GitHub puede ejecutar una secuencia de jobs y steps.

Casos de uso

  • Ejecutar pruebas.
  • Hacer lint.
  • Verificar formateo.
  • Construir artefactos.
  • Publicar paquetes.
  • Automatizar tareas administrativas.

Además, GitHub crea automáticamente un GITHUB_TOKEN para cada ejecución, con permisos limitados al repositorio del workflow.[cite:109]

Integración con Cloudflare

Aquí Git y GitHub se conectan con el mundo del despliegue profesional.

Cloudflare Pages

Cloudflare Pages puede conectarse a un repositorio GitHub y desplegar automáticamente cada cambio relevante.[cite:103][cite:100]

Deploy automático

Cuando main es la rama principal conectada al proyecto, cada commit enviado a main actualiza el sitio principal y los dominios asociados al proyecto Pages.[cite:103]

Push

Un simple git push origin main puede convertirse en un despliegue a producción. Esto cambia por completo el flujo mental: Git deja de ser solo control de versiones y se convierte en disparador operativo.

Rollback

Cloudflare Pages permite revertir instantáneamente un proyecto a un despliegue previo exitoso desde la lista de deployments. La documentación oficial aclara que solo los despliegues de producción exitosos son objetivos válidos para rollback y que los previews no lo son.[cite:100]

Preview

Cada pull request originado en el propio repositorio de GitHub puede generar un preview deployment con URL única, y esa URL se actualiza conforme llegan nuevos commits a la rama del pull request.[cite:103]

Además, Pages crea alias por nombre de rama como development.<proyecto>.pages.dev, mientras conserva disponibles las URLs hash históricas.[cite:103]

Producción

La rama principal alimenta producción. El valor de este modelo es enorme: puedes revisar una rama en preview antes de integrarla y solo publicar al merge final.

Integración con Cursor

Cursor, al estar basado en un entorno de desarrollo moderno, suele ofrecer integración Git visual y desde terminal. En la práctica esto significa:

  • Ver cambios locales.
  • Preparar archivos para commit.
  • Escribir mensajes de commit.
  • Cambiar de rama.
  • Sincronizar con remoto.

La recomendación profesional sigue siendo la misma aunque exista interfaz visual: entender siempre qué ocurre detrás. Una buena UI no sustituye comprensión del modelo Git.

Integración con VS Code

Panel Git

VS Code incluye una vista de Source Control que permite revisar archivos modificados, stagear cambios, hacer commit, resolver conflictos y trabajar con ramas.

Extensiones

Existen extensiones para visualizar historial, comparar ramas o enriquecer el flujo de revisión.

Terminal

Aun con panel visual, la terminal sigue siendo esencial. Muchos flujos avanzados, automatizaciones y diagnósticos siguen siendo más claros desde CLI.

Seguridad

La seguridad en Git y GitHub no se limita a “poner contraseña”. Se trata de credenciales, secretos y disciplina operativa.

SSH

SSH es recomendable para autenticación estable y profesional al trabajar con repositorios remotos.

HTTPS

HTTPS sigue siendo válido, especialmente con tokens personales cuando el flujo lo requiere.

Tokens

Los tokens se usan para autenticación en ciertos flujos, integraciones y automatizaciones. GitHub también ofrece GITHUB_TOKEN dentro de Actions.[cite:109]

Secrets

Los secrets deben almacenarse en GitHub Secrets cuando se usan en workflows o integraciones. GitHub distingue tipos y alcances de secretos según repositorio, entorno y organización.[cite:96]

.gitignore

.gitignore evita versionar archivos que no deben entrar al repositorio: credenciales, dependencias locales, builds temporales, logs, archivos del sistema y configuraciones sensibles.

Ejemplo:

node_modules/
.env
.env.local
dist/
coverage/
.DS_Store
.vscode/

Buenas prácticas

  • Nunca subir secretos al repositorio.
  • Usar .gitignore desde el inicio.
  • Preferir SSH o tokens bien gestionados.
  • Rotar credenciales comprometidas.
  • Limitar permisos de tokens y secrets.

Organización profesional

Un repositorio serio comunica intención, reglas y madurez.

README

Debe explicar qué es el proyecto, cómo instalarlo, cómo ejecutarlo, estructura básica y enlaces útiles.

LICENSE

Aclara condiciones legales de uso y distribución.

CHANGELOG

Registra cambios importantes por versión.

CONTRIBUTING

Explica cómo colaborar: convenciones, flujo de ramas, pruebas y revisión.

Issues

Deben usarse con criterio, no como cajón caótico de ideas sueltas.

Versionado semántico

El versionado semántico usa normalmente MAJOR.MINOR.PATCH:

  • MAJOR: cambio incompatible.
  • MINOR: funcionalidad nueva compatible.
  • PATCH: corrección sin ruptura.

Comparativa

GitHub

Fortalezas:

  • Ecosistema enorme.
  • Pull requests maduros.
  • Actions integradas.
  • Comunidad y visibilidad.

Debilidades:

  • Algunas funciones avanzadas pueden requerir planes o configuración adicional.

GitLab

Fortalezas:

  • Plataforma muy completa con fuerte integración DevOps.
  • Experiencia sólida para CI/CD y gestión centralizada.

Debilidades:

  • Puede sentirse más pesada según el equipo o el caso.

Bitbucket

Fortalezas:

  • Integración habitual con ecosistema Atlassian.

Debilidades:

  • Menor protagonismo comunitario general frente a GitHub.

Azure DevOps

Fortalezas:

  • Muy fuerte en organizaciones Microsoft y gestión empresarial amplia.

Debilidades:

  • Puede ser excesivo para proyectos pequeños o equipos que buscan simplicidad.

Casos reales

elprofe.org

Repositorio sugerido:

  • Frontend público en un repositorio principal.
  • Rama main conectada a producción en Cloudflare Pages.
  • Ramas feature/* para nuevas secciones, SEO, mejoras visuales o contenido.
  • Pull requests con preview deployments antes de publicar.[cite:103]

masterfinanzas.com

Podría estructurarse como un repositorio de sitio de contenido o marketing con:

  • Contenido y componentes bien separados.
  • Pipeline simple de despliegue por main.
  • Etiquetas por cada versión editorial importante.

NLink probablemente merece al menos:

  • Un repositorio para la API/Worker.
  • Otro para frontend si la interfaz es independiente.
  • Rama main estable, feature/* para endpoints, analítica o panel administrativo.
  • Releases etiquetadas cuando cambie el comportamiento público de la API.

Credenciales Digitales

Proyecto sensible y estructurado:

  • README muy claro.
  • CONTRIBUTING interno.
  • .gitignore estricto.
  • Releases por cada versión operacional.
  • Posible separación por dominios: frontend, workers, panel administrativo, documentación.

IA El Profe

Este proyecto probablemente requiere:

  • Módulos diferenciados para UI, API, indexación e IA.
  • Buen control de secretos.
  • Ramas cortas para prompts, retrieval, UI y panel.
  • Documentación fuerte para embeddings, fuentes y despliegues.

Escuelas Digitales

Como plataforma más amplia, puede beneficiarse de organización por monorepo o por repositorios separados según dominio: sitio institucional, plataforma académica, servicios backend, documentación y assets.

Diagramas ASCII

Git Workflow

Working Directory
      |
      v
Staging Area
      |
      v
Commit local
      |
      v
Remote (GitHub)
      |
      v
Deploy (Cloudflare Pages)

Commit

[archivo editado] --> [git add] --> [staged] --> [git commit] --> [snapshot]

Merge

A---B---C main
     \
      D---E feature
           \
            M merge

Branch

A---B---C main
     \
      D---E feature/login

Cloudflare Deploy

Developer
   |
   v
git push origin main
   |
   v
GitHub repository
   |
   v
Cloudflare Pages build
   |
   v
Production deployment

GitHub Flow

main
 |
 +--> feature/nueva-funcion
         |
         +--> commits
                 |
                 +--> pull request
                         |
                         +--> preview deployment
                                 |
                                 +--> review
                                         |
                                         +--> merge a main
                                                 |
                                                 +--> producción

Arquitectura completa

[Desarrollador]
      |
      v
[Git local]
      |
      v
[GitHub repo]
   |        \
   |         \--> [Pull Request] --> [Preview en Cloudflare Pages]
   |
   +--> [main] --> [Deploy de producción en Cloudflare Pages]

Buenas prácticas

  • Hacer commits pequeños y significativos.
  • Escribir mensajes claros.
  • Mantener main desplegable.
  • Usar pull requests incluso en equipos pequeños cuando el proyecto importa.
  • Probar antes de hacer push a producción.
  • Etiquetar versiones relevantes.
  • Documentar el repositorio desde el primer día.
  • Evitar subir archivos generados o secretos.

Errores comunes

  • Hacer commits gigantescos con cambios sin relación.
  • Trabajar siempre directo en main.
  • No usar .gitignore.
  • Confundir git fetch con git pull.
  • Reescribir historia compartida sin entender consecuencias.
  • Resolver conflictos “a ciegas”.
  • No revisar preview deployments antes de mergear.[cite:103]

Curiosidades

  • GitHub genera automáticamente un GITHUB_TOKEN para cada ejecución de Actions y ese token expira al finalizar el job.[cite:109]
  • Cloudflare Pages crea preview deployments con URLs hash únicas para ramas y pull requests, y además alias por nombre de rama en minúsculas y saneados.[cite:103]
  • Los preview deployments de Pages incluyen por defecto la cabecera X-Robots-Tag: noindex, lo cual ayuda a evitar problemas de SEO por contenido duplicado.[cite:103]
  • Pages permite rollback instantáneo a despliegues previos exitosos de producción, pero no a previews.[cite:100]

Resumen

Git resuelve el problema del historial y el trabajo paralelo. GitHub convierte ese historial en colaboración, revisión y automatización. Cloudflare Pages transforma el repositorio en un punto de despliegue continuo.[cite:108][cite:103][cite:100]

Cuando estas tres piezas se combinan correctamente, el flujo de trabajo cambia de nivel: ya no se suben archivos manualmente a un hosting, sino que se desarrolla por ramas, se revisa por pull requests, se prueba en previews y se publica por merge a producción.[cite:103]

Esa es una forma profesional de construir software, no solo una costumbre de equipo.

Glosario

  • Git: sistema de control de versiones distribuido.
  • GitHub: plataforma para alojar repositorios Git y colaborar sobre ellos.
  • Repositorio: contenedor de un proyecto y su historial.
  • Commit: snapshot registrado del proyecto.
  • Working Directory: archivos actuales en edición.
  • Staging Area: área intermedia previa al commit.
  • HEAD: referencia al punto actual del historial.
  • Branch: línea de desarrollo independiente.
  • Merge: integración de dos ramas.
  • Rebase: reaplicación de commits sobre otra base.[cite:95][cite:104]
  • Remote: repositorio remoto asociado.
  • Origin: nombre por defecto del remote principal.
  • Clone: copia local completa de un repositorio remoto.
  • Fork: copia de un repositorio bajo otra cuenta o espacio.
  • Pull Request: propuesta de integración revisable en GitHub.
  • Tag: marca de un commit específico.
  • Release: publicación formal de una versión.
  • Preview Deployment: despliegue de prueba con URL propia en Pages.[cite:103]
  • Rollback: reversión a un despliegue previo de producción.[cite:100]
  • Secret: dato sensible almacenado de forma segura en GitHub.[cite:96]

20 preguntas de autoevaluación

  1. ¿Qué es Git y qué problema fundamental resuelve?
  2. ¿Quién creó Git y en qué contexto histórico?
  3. ¿Qué diferencia hay entre Git y GitHub?
  4. ¿Qué es un commit y por qué se considera un snapshot?
  5. ¿Qué función cumple el staging area?
  6. ¿Qué representa HEAD?
  7. ¿Qué diferencia hay entre git fetch y git pull?
  8. ¿Cuándo conviene usar git merge y cuándo git rebase?[cite:95][cite:101]
  9. ¿Qué riesgos tiene reescribir historia ya publicada?[cite:101]
  10. ¿Qué es una rama feature/*?
  11. ¿Qué diferencia hay entre Git Flow y GitHub Flow?
  12. ¿Qué es un conflicto de merge y cómo se resuelve?
  13. ¿Para qué sirve .gitignore?
  14. ¿Qué papel cumplen los secrets en GitHub?[cite:96]
  15. ¿Qué es GITHUB_TOKEN y cuándo aparece?[cite:109]
  16. ¿Qué ocurre en Cloudflare Pages cuando se hace push a main en un repositorio conectado?[cite:103]
  17. ¿Cómo funcionan los preview deployments de Pages para ramas o pull requests?[cite:103]
  18. ¿Qué limitación importante tiene el rollback en Pages?[cite:100]
  19. ¿Cómo organizarías profesionalmente el repositorio de una plataforma educativa?
  20. ¿Por qué Git y GitHub son parte del despliegue profesional, y no solo del almacenamiento de código?

Proyecto práctico

El proyecto práctico consiste en crear desde cero un repositorio profesional para una plataforma educativa moderna y conectarlo con Cloudflare Pages.

Objetivo del proyecto

Construir un flujo real de trabajo que incluya inicialización local, publicación en GitHub, autenticación por SSH, estructura documental mínima, estrategia de ramas y despliegue automático.

1. Crear carpeta del proyecto

mkdir plataforma-educativa-moderna
cd plataforma-educativa-moderna

2. Inicializar Git

git init

3. Crear estructura mínima profesional

touch README.md LICENSE .gitignore CHANGELOG.md CONTRIBUTING.md
mkdir src public docs

4. Crear README básico

# Plataforma Educativa Moderna

Proyecto base para una plataforma educativa desplegada con Cloudflare Pages.

## Desarrollo

1. Instalar dependencias.
2. Ejecutar entorno local.
3. Crear ramas `feature/*` para cambios.
4. Abrir Pull Request antes de integrar a `main`.

5. Crear .gitignore

node_modules/
.env
.env.local
dist/
coverage/
.DS_Store
.vscode/

6. Configurar identidad Git

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

7. Configurar SSH

ssh-keygen -t ed25519 -C "tu-correo@ejemplo.com"
cat ~/.ssh/id_ed25519.pub

Copiar la clave pública y agregarla en GitHub.

8. Primer commit

git add .
git commit -m "chore: inicializa repositorio profesional"

9. Crear repositorio en GitHub

En GitHub:

  1. Crear nuevo repositorio.
  2. Elegir nombre, por ejemplo plataforma-educativa-moderna.
  3. No inicializar con README si ya existe localmente.

10. Conectar remoto

git remote add origin git@github.com:usuario/plataforma-educativa-moderna.git
git branch -M main
git push -u origin main

11. Crear estrategia de ramas

Modelo sugerido para este proyecto:

  • main: producción.
  • feature/auth: autenticación.
  • feature/dashboard: panel.
  • feature/credenciales: módulo de credenciales.
  • hotfix/login: correcciones urgentes.

Ejemplo:

git switch -c feature/credenciales

12. Hacer trabajo real y commitear

git add src/
git commit -m "feat: agrega módulo inicial de credenciales"
git push -u origin feature/credenciales

13. Abrir Pull Request en GitHub

Desde GitHub:

  1. Comparar feature/credenciales contra main.
  2. Crear pull request.
  3. Revisar cambios.
  4. Esperar preview deployment en Cloudflare Pages si el repositorio ya está conectado.[cite:103]

14. Conectar con Cloudflare Pages

Flujo conceptual:

  1. Entrar a Cloudflare Pages.
  2. Crear proyecto nuevo.
  3. Conectar cuenta GitHub.
  4. Seleccionar el repositorio.
  5. Elegir main como rama de producción.
  6. Configurar comandos de build si hacen falta.
  7. Desplegar.

Una vez conectado, cualquier push a main actualizará producción y los pull requests del repositorio podrán generar previews automáticos.[cite:103]

15. Verificar despliegue automático

  • Hacer merge del pull request.
  • Confirmar que main dispara despliegue a producción.[cite:103]
  • Comprobar la URL principal del proyecto.
  • Verificar preview URL histórica y alias de rama si aplica.[cite:103]

16. Probar rollback

Si una versión falla:

  1. Entrar al proyecto Pages.
  2. Ir a Deployments.
  3. Elegir un despliegue de producción previo exitoso.
  4. Ejecutar rollback.[cite:100]

17. Estrategia profesional recomendada

Para una plataforma educativa moderna, una estrategia razonable es GitHub Flow reforzado:

  • main siempre desplegable.
  • Todo cambio en feature/*.
  • Pull request obligatorio.
  • Preview deployment antes de merge.
  • Tags para versiones relevantes.
  • Releases para hitos de producto.

18. Diagrama del proyecto práctico

[Desarrollador]
      |
      v
[Repositorio local Git]
      |
      +--> feature/credenciales --> commit --> push
                                   |
                                   v
                             [GitHub Pull Request]
                                   |
                                   v
                      [Cloudflare Pages Preview Deployment]
                                   |
                                   v
                                 review
                                   |
                                   v
                                 merge
                                   |
                                   v
                                  main
                                   |
                                   v
                    [Cloudflare Pages Production Deployment]

Lección final del proyecto

La meta del proyecto no es aprender a “subir código a GitHub”. La meta es dominar un flujo profesional completo: historial claro, ramas sanas, revisión visible, despliegue repetible y posibilidad de rollback. Cuando ese flujo existe, el repositorio deja de ser una carpeta remota y se convierte en la columna vertebral operativa del producto.[cite:103][cite:100]