Subir un proyecto a GitHub paso a paso

01¿Qué necesita antes de empezar?

Subir un proyecto a GitHub significa convertir una carpeta de su ordenador en un repositorio Git y conectarla a un repositorio remoto en internet. Para ello deben estar listas tres cosas: Git instalado y configurado, una cuenta de GitHub y un método de autenticación.

Si todavía no ha instalado Git o no ha configurado su nombre, su correo electrónico y su clave SSH, siga primero nuestra guía de instalación de Git. Los comandos de este artículo dan por hecho que esa configuración ya está hecha.

• Git: al ejecutar git --version en la terminal debe aparecer un número de versión.
• Cuenta de GitHub: se abre gratis en github.com.
• Autenticación: una clave SSH o, para HTTPS, Git Credential Manager o un token de acceso personal. GitHub no acepta la contraseña de la cuenta en las operaciones de Git.
• Una carpeta de proyecto limpia: con un archivo .gitignore para excluir los archivos innecesarios y confidenciales.

02Cómo crear un repositorio en GitHub

Inicie sesión en GitHub, pulse el icono más de la esquina superior derecha y elija New repository. Escriba el nombre del repositorio corto y en minúsculas (por ejemplo, web-empresa), añada una descripción y seleccione la visibilidad.

Si ya tiene un proyecto en su ordenador, no añada README, .gitignore ni licencia; cree el repositorio completamente vacío. De lo contrario, se crea en el repositorio remoto un commit que no existe en local y tendrá un conflicto en el primer push.

03Filtre los archivos innecesarios con .gitignore

Lo más importante antes del primer commit es decidir qué archivos no deben entrar en el repositorio. node_modules, las carpetas de compilación, los archivos del sistema operativo y, sobre todo, los archivos .env con contraseñas o claves de API no deben subirse nunca a GitHub.

Cree en la carpeta raíz del proyecto un archivo llamado .gitignore y añada líneas como las siguientes. En nuestro artículo sobre comandos de npm explicamos por qué las dependencias no entran en el repositorio y qué papel cumple package.json.

• Si ha hecho commit de un archivo confidencial por error, no basta con borrarlo después: el archivo permanece en el historial. Cambie de inmediato la clave o la contraseña afectada.
• Para dejar de rastrear una carpeta que ya se estaba rastreando, use el comando git rm -r --cached nombre-carpeta, añádala después a .gitignore y haga commit.

node_modules/
dist/
build/
.env
.env.*
.DS_Store
Thumbs.db
*.log

04Primera subida desde la línea de comandos

En la terminal, entre en la carpeta del proyecto y ejecute los comandos siguientes por orden. La dirección del repositorio remoto aparece en la página del repositorio vacío de GitHub, bajo el botón Code; copie la dirección SSH si ha configurado una clave SSH y la dirección HTTPS si no.

1. Convierta la carpeta en un repositorio Git con git init.
2. Añada todos los archivos al área de preparación con git add ..
3. Cree el primer registro con git commit.
4. Fije el nombre de la rama como main.
5. Conecte el repositorio remoto con git remote add origin.
6. Envíelo con git push -u origin main; la opción -u permite escribir solo git push en los siguientes envíos.

cd proje-klasoru
git init
git add .
git commit -m "Primer commit"
git branch -M main

# SSH adresi
git remote add origin git@github.com:kullanici-adi/depo-adi.git
# ya da HTTPS adresi
# git remote add origin https://github.com/kullanici-adi/depo-adi.git

git push -u origin main

git remote -v
git status
git log --oneline

05Subir el proyecto con GitHub Desktop y gh CLI

La línea de comandos no es la única vía. Para quien prefiere una interfaz gráfica está GitHub Desktop, y para quien quiere trabajar más rápido en la terminal, la herramienta oficial de línea de comandos de GitHub, gh, hace lo mismo en pocos pasos.

GitHub Desktop

Instale GitHub Desktop e inicie sesión con su cuenta. En el menú File, elija la carpeta de su proyecto con Add local repository; si la carpeta aún no es un repositorio, la aplicación le propone crearlo. Verá los cambios en el panel izquierdo, escribirá un mensaje en el cuadro inferior y pulsará el botón Commit. Por último, el botón Publish repository crea el repositorio en GitHub y lo envía.

gh CLI

Con gh, crear, conectar y enviar el repositorio se resume en un solo comando. La primera vez, inicie sesión desde el navegador con gh auth login.

gh auth login

# Cuando la carpeta ya tiene al menos un commit
gh repo create depo-adi --private --source=. --remote=origin --push

Con VS Code

El botón Publish to GitHub del panel de control de código fuente de VS Code ofrece el mismo flujo. Para la instalación del editor y la integración con Git, consulte nuestra guía de instalación de VS Code.

06¿Cómo envío las actualizaciones?

Tras la primera subida, el flujo diario se reduce a tres comandos: preparar los cambios, guardarlos y enviarlos. Si trabaja en otro ordenador o si un compañero de equipo ha hecho cambios, descargue antes la versión actualizada con git pull antes de empezar a trabajar.

Escriba los mensajes de commit breves y con sentido: en lugar de «actualización», algo como «añadido el campo de teléfono al formulario de contacto». Dentro de seis meses, al revisar el historial, esos mensajes le dirán qué cambio se hizo y por qué.

git pull
git add .
git commit -m "Añadido el campo de teléfono al formulario de contacto"
git push

Trabajar con ramas

En lugar de hacer un cambio grande directamente en la rama main, abra una rama nueva: git switch -c nueva-funcion. Envíe la rama con git push -u origin nueva-funcion y abra un pull request en GitHub. Así el cambio se revisa antes de fusionarse y la rama main siempre se mantiene en estado funcional.

07Errores de push frecuentes y sus soluciones

La mayoría de los errores de los primeros intentos de push tienen que ver con la autenticación, el nombre de la rama o commits inesperados en el repositorio remoto.

• src refspec main does not match any: todavía no hay ningún commit o su rama se llama master. Haga un git commit o cambie el nombre de la rama con git branch -M main.
• remote origin already exists: el repositorio remoto ya está definido. Para cambiar la dirección, use git remote set-url origin nueva-direccion.
• rejected (fetch first / non-fast-forward): el repositorio remoto tiene commits que no están en local, normalmente el README creado en GitHub. Descárguelos con git pull --rebase origin main y vuelva a hacer push. Si los historiales no tienen nada que ver, puede hacer falta git pull origin main --allow-unrelated-histories.
• Permission denied (publickey): su clave SSH no se ha añadido a la cuenta; compruébelo con ssh -T git@github.com.
• Error por archivo grande: GitHub no acepta archivos individuales de más de 100 MB. Saque del repositorio los vídeos y las copias de seguridad, o utilice Git LFS.

08¿Qué aporta GitHub a los proyectos de una empresa?

Tener el código en GitHub evita que el proyecto se pierda ante una avería del ordenador o una pérdida. Y, lo que es más importante, como cada cambio queda registrado, cuando un error llega al sitio en producción se encuentra rápidamente qué commit lo causó y se puede revertir.

Si las mejoras de velocidad y rendimiento de un sitio web, como la compresión de imágenes o la minificación del código, se guardan además como commits independientes, resulta fácil medir cuánto aportó cada una. Trabajamos con esta disciplina en nuestros proyectos de web corporativa y de diseño web.

No olvide añadir al repositorio un archivo README bien redactado. Unos pocos párrafos que expliquen qué hace el proyecto, cómo se instala y con qué comando se ejecuta ahorran horas a un nuevo miembro del equipo, o a usted mismo cuando vuelva al proyecto meses después. Escriba la lista de variables de entorno solo con sus nombres, nunca con sus valores.

Para otras explicaciones paso a paso, consulte la categoría de guías de instalación.