From d64160bfbd156d88dfd8daddf5b9d543d12f948b Mon Sep 17 00:00:00 2001 From: Admin-Alphas Date: Thu, 8 Oct 2026 21:48:24 +0000 Subject: [PATCH] =?UTF-8?q?A=C3=B1adir=20README.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 217 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 217 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..a3320e7 --- /dev/null +++ b/README.md @@ -0,0 +1,217 @@ +# Guía definitiva: Personal Access Token (PAT) en Git para Linux, Windows y macOS + +Este manual explica cómo generar un **Personal Access Token (PAT)** en Forgejo, Gitea o GitHub y configurar el almacenamiento de credenciales de forma segura en los tres principales sistemas operativos: **Linux, Windows y macOS**. + +## 1. Generación del Personal Access Token (PAT) + +Antes de configurar tu sistema operativo, debes generar el token desde la plataforma web. + +1. Inicia sesión en tu servidor **Forgejo, Gitea o GitHub**. +2. Dirígete a tu foto de perfil, ubicada en la esquina superior derecha, y accede a **Configuración (Settings)**. +3. Selecciona **Aplicaciones (Applications)** o **Developer settings**, según la plataforma, y busca **Personal Access Tokens**. +4. Haz clic en **Generar nuevo token**. +5. Asigna un nombre descriptivo, por ejemplo, `laptop-desarrollo`, y selecciona los permisos necesarios. Aplica el principio de mínimo privilegio y concede únicamente los permisos requeridos para tus operaciones Git. +6. Copia el token generado y guárdalo en un lugar seguro. + +> **Importante:** El token sustituye a tu contraseña habitual cuando Git solicita autenticación mediante HTTPS. No lo compartas ni lo incluyas directamente en scripts o repositorios. + +## 2. Configuración en Linux + +En Linux, puedes almacenar las credenciales utilizando **Git Credential Manager**, `git-credential-libsecret` o una caché temporal en memoria. + +### Opción A: Libsecret (recomendado para entornos con interfaz gráfica) + +Libsecret permite integrar Git con los gestores de secretos del entorno de escritorio, como GNOME Keyring. + +#### Paso 1. Instalar las dependencias + +**Ubuntu/Debian:** + +```bash +sudo apt update +sudo apt install libsecret-1-0 libsecret-1-dev make gcc +``` + +**Fedora/RHEL:** + +```bash +sudo dnf install libsecret-devel make gcc +``` + +> Los nombres de los paquetes pueden variar según la distribución y su versión. + +#### Paso 2. Compilar el helper de Git + +En sistemas Debian o Ubuntu donde se encuentre disponible el código fuente del helper: + +```bash +sudo make --directory=/usr/share/doc/git/contrib/credential/libsecret +``` + +Si la ruta no existe, comprueba dónde está instalado Git y si tu distribución proporciona el código fuente de sus herramientas auxiliares. + +#### Paso 3. Configurar Git + +Si el ejecutable compilado se encuentra en la ruta indicada, configura el helper: + +```bash +git config --global credential.helper \ + /usr/share/doc/git/contrib/credential/libsecret/git-credential-libsecret +``` + +Verifica la configuración: + +```bash +git config --global --get credential.helper +``` + +### Opción B: Caché temporal en memoria + +Esta opción es útil para servidores o entornos de línea de comandos sin interfaz gráfica. + +El siguiente comando mantiene las credenciales en memoria durante ocho horas: + +```bash +git config --global credential.helper 'cache --timeout=28800' +``` + +El valor `28800` representa ocho horas en segundos. + +> **Nota de seguridad:** La caché es temporal y no equivale a un almacén persistente cifrado. Cuando expire, Git volverá a solicitar las credenciales. Para servidores, considera también Git Credential Manager u otro mecanismo seguro compatible con el entorno. + +## 3. Configuración en Windows + +En Windows, **Git Credential Manager (GCM)** permite almacenar y recuperar credenciales mediante los mecanismos seguros del sistema operativo. + +### Paso 1. Verificar la instalación + +Instala Git para Windows desde su [sitio oficial](https://git-scm.com/downloads/win). Git Credential Manager suele estar incluido en las instalaciones actuales. + +### Paso 2. Configurar el administrador de credenciales + +Abre PowerShell o Git Bash y ejecuta: + +```powershell +git config --global credential.helper manager +``` + +Comprueba el valor configurado: + +```powershell +git config --global --get credential.helper +``` + +### Paso 3. Autenticarse + +Ejecuta una operación Git sobre un repositorio remoto HTTPS: + +```bash +git fetch +``` + +Si todavía no existen credenciales almacenadas, Git Credential Manager iniciará el proceso de autenticación correspondiente. + +Cuando se soliciten credenciales: + +* **Usuario:** tu nombre de usuario en Forgejo, Gitea o GitHub. +* **Contraseña:** tu Personal Access Token (PAT), si la plataforma utiliza autenticación mediante token. + +Dependiendo de la plataforma y de la configuración de GCM, es posible que se abra una ventana de inicio de sesión en lugar de solicitar el token directamente. + +## 4. Configuración en macOS + +En macOS, Git puede utilizar **Keychain Access (Acceso a Llaveros)** para almacenar las credenciales de forma persistente. + +### Paso 1. Activar el helper de Keychain + +Abre Terminal y ejecuta: + +```bash +git config --global credential.helper osxkeychain +``` + +Verifica la configuración: + +```bash +git config --global --get credential.helper +``` + +### Paso 2. Autenticarse por primera vez + +Desde un repositorio local, ejecuta: + +```bash +git fetch +``` + +Cuando Git solicite las credenciales: + +* **Username:** tu nombre de usuario en Forgejo, Gitea o GitHub. +* **Password:** tu Personal Access Token (PAT), si corresponde a la autenticación configurada. + +Una vez almacenadas, las credenciales podrán reutilizarse en operaciones posteriores, según la configuración del servidor y del llavero. + +## 5. Matriz de comandos por sistema operativo + +| Sistema operativo | Comando de configuración global | Almacenamiento | +| -------------------- | ------------------------------------------------------------------------- | --------------------------------------- | +| Linux (GUI) | `git config --global credential.helper /ruta/al/git-credential-libsecret` | GNOME Keyring u otro almacén compatible | +| Linux (CLI/servidor) | `git config --global credential.helper 'cache --timeout=28800'` | Memoria RAM temporal | +| Windows | `git config --global credential.helper manager` | Gestor de credenciales mediante GCM | +| macOS | `git config --global credential.helper osxkeychain` | Llavero de macOS | + +> **Importante:** En Linux, reemplaza `/ruta/al/git-credential-libsecret` por la ruta real del ejecutable instalado. La ruta puede variar entre distribuciones. + +## 6. Mantenimiento: borrar o actualizar credenciales + +Si tu token expira, se revoca o necesitas sustituirlo, debes eliminar las credenciales almacenadas para que Git vuelva a solicitarlas. + +### Linux: Libsecret + +Si tienes disponible el helper `git-credential-libsecret`, puedes enviarle una solicitud para borrar las credenciales del servidor: + +```bash +printf 'protocol=https\nhost=git.alphas.team\n\n' \ + | git credential-libsecret erase +``` + +### Windows: Administrador de credenciales + +1. Abre el menú Inicio. +2. Busca **Administrador de credenciales**. +3. Accede a **Credenciales de Windows**. +4. Busca la entrada asociada a `git.alphas.team`. +5. Selecciona la entrada correspondiente y haz clic en **Quitar**. + +El nombre exacto de la entrada puede variar según la versión de Git y el método de autenticación utilizado. + +### macOS: Keychain + +Para eliminar las credenciales HTTPS almacenadas mediante el helper `osxkeychain`, ejecuta: + +```bash +printf 'protocol=https\nhost=git.alphas.team\n\n' \ + | git credential-osxkeychain erase +``` + +Git volverá a solicitar las credenciales cuando sean necesarias. + +## 7. Buenas prácticas de seguridad + +* **Mínimo privilegio:** concede al PAT únicamente los permisos que necesites. +* **Tokens individuales:** utiliza un token por equipo, aplicación o propósito cuando sea viable. +* **Expiración:** configura una fecha de vencimiento y renueva los tokens antes de que expiren. +* **Protección de secretos:** no guardes tokens en archivos de configuración compartidos, repositorios, capturas de pantalla ni scripts. +* **Revocación:** revoca inmediatamente cualquier token que sospeches que ha sido expuesto. +* **HTTPS:** utiliza URLs HTTPS para los repositorios cuando autentiques mediante PAT. +* **Verificación:** revisa el helper activo con `git config --show-origin --get-all credential.helper` si Git no utiliza el mecanismo esperado. + +## 8. Referencias oficiales + +* [Documentación de Git: almacenamiento de credenciales](https://git-scm.com/docs/gitcredentials) +* [Documentación de Git Credential Manager](https://github.com/git-ecosystem/git-credential-manager) +* [Documentación de GitHub: administración de Personal Access Tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) + +--- + +**Fin de la guía.**