# 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.**