Merge pull request 'docs: actualizar README con secciones por remoto y ejemplos de pipeline' (#16) from worktree-kind-watching-hearth into main

Reviewed-on: #16

README.md

@@ -15,7 +15,7 @@ carpeta local, y lo instalamos:
 
 ```sh
 cd ~/Downloads
-git clone git@bitbucket.org:sushi2717/git-flow.git
+git clone ssh://git@git.jonathanteran.dev:59169/jt/git-flow.git
 cd git-flow
 pipx install .
 ```
@@ -51,23 +51,25 @@ El comando solicitará 2 opciones:
     - [x] Gitea
     - [x] Gitlab
 
-  La configuración del remoto requiere tener un Access Token para poder crear los PRs automáticamente.
-  El mismo se puede crear desde el repositorio al que se quiere dar acceso: *"Repository settings" >
-  "Access Tokens" > "Create access token"*. El token necesita permiso para *Write* en *Pull Requests*.
+  La configuración del remoto requiere tener un Access Token para poder crear los PRs y tags
+  automáticamente. Ver la sección [Remotos soportados](#remotos-soportados) para las instrucciones
+  de cómo generar el token en cada proveedor.
 
-  Luego se debe guardar el token dentro del repositorio a configurar, en el archivo
+  Una vez generado, el token se debe guardar dentro del repositorio a configurar, en el archivo
   `.repository-token`. De no especificarse, los merges y tags se harán de forma local.
 
 ## Utilización
 
-Git Flow cuenta con 5 comandos principales para guiar el workflow (ver `git-flow <command> -h` para
+Git Flow cuenta con los siguientes comandos para guiar el workflow (ver `git-flow <command> -h` para
 más información):
 
+- `init`: Inicializa el repositorio para utilizar git-flow (ramas principales y remoto).
 - `new`: Crea una nueva rama siguiendo CB.
 - `commit`: Crea un commit siguiendo CC.
 - `merge`: Mergea la rama actual a una de las ramas principales.
 - `tag`: Crea un tag sobre el ultimo merge siguiendo SemVer.
-- `release`: Prepara la rama actual para pasarse al siguiente entorno configurado
+- `release`: Prepara la rama actual para pasarse al siguiente entorno configurado.
+- `branch`: Lista las ramas del repositorio, agrupadas por entorno objetivo.
 
 El workflow para el cual se penso la herramienta es el siguiente:
 
@@ -86,9 +88,147 @@ El workflow para el cual se penso la herramienta es el siguiente:
    `feature/my-new-feature`, se crea la rama `release/test/feature/my-new-feature` sobre `test` que
    tiene los cambios de la rama original.
 
+En cualquier momento se puede usar `git-flow branch` para ver en qué entorno está cada rama, y cuáles
+están todavía en progreso (`wip/`) o descartadas (`trash/`).
+
+## Remotos soportados
+
+Cada remoto necesita un Access Token con permisos para crear Pull/Merge Requests y tags. El token se
+guarda en el archivo `.repository-token` en la raíz del repositorio (una única línea con el valor del
+token), o se pasa por parámetro con `--token=<TOKEN>` al comando `git-flow tag` (útil para no
+commitear el token y usarlo solo desde un pipeline mediante una variable secreta).
+
+### Github
+
+1. Ir a *Settings* del repositorio (o de la organización) > *Developer settings* > *Personal access
+   tokens* > *Fine-grained tokens* > *Generate new token*.
+2. Seleccionar el repositorio sobre el que se va a usar `git-flow`.
+3. En *Repository permissions*, otorgar:
+   - **Contents**: Read and write (necesario para crear tags).
+   - **Pull requests**: Read and write (necesario para crear PRs).
+4. Generar el token y guardarlo en `.repository-token`.
+
+Ejemplo de pipeline (GitHub Actions) para taggear automáticamente en cada push a una rama principal:
+
+```yaml
+# .github/workflows/tag.yml
+name: Tag and publish
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  tag:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v3
+
+      - run: uv run git-flow tag --token=${{ secrets.GIT_FLOW_TOKEN }}
+
+      - run: uv build
+      - run: uv publish --token=${{ secrets.PYPI_TOKEN }}
+```
+
+### Gitlab
+
+1. Ir a *Settings* > *Access Tokens* del proyecto (o *Group access tokens* si se quiere usar a nivel
+   grupo).
+2. Crear un token con rol **Developer** o superior, y los scopes:
+   - **api** (o al menos `write_repository` para tags y `api` para Merge Requests).
+3. Generar el token y guardarlo en `.repository-token`.
+
+Ejemplo de pipeline (GitLab CI) para taggear automáticamente en cada push a una rama principal:
+
+```yaml
+# .gitlab-ci.yml
+tag:
+  image: python:3.14
+  rules:
+    - if: $CI_COMMIT_BRANCH == "main"
+  script:
+    - pip install uv
+    - uv run git-flow tag --token=$GIT_FLOW_TOKEN
+    - uv build
+    - uv publish --token=$PYPI_TOKEN
+```
+
+El token debe guardarse como variable protegida y enmascarada (`GIT_FLOW_TOKEN`) en *Settings* >
+*CI/CD* > *Variables*.
+
+### Bitbucket
+
+1. Ir a *Repository settings* > *Access Tokens* > *Create access token* (o *Workspace settings* >
+   *Access Tokens* para un token a nivel workspace).
+2. Otorgar permiso de **Write** en *Pull requests* y *Repositories* (necesario para crear tags).
+3. Generar el token y guardarlo en `.repository-token`.
+
+Este mismo repositorio usa Git Flow para el taggeo automático usando Bitbucket Pipelines, se puede
+ver el archivo `bitbucket-pipelines.yml` como ejemplo:
+
+```yaml
+# bitbucket-pipelines.yml
+image: python:3.14
+
+pipelines:
+  branches:
+    'main':
+      - step:
+          name: "Tag and publish package"
+          caches:
+            - pip
+          script:
+            - pip install uv
+            - uv run git-flow tag --token=$BEARER
+            - uv build
+            - uv publish --token=$PYPI_TOKEN
+```
+
+El token se configura como variable segura del repositorio (`BEARER`) en *Repository settings* >
+*Repository variables*.
+
+### Gitea
+
+1. Ir a *Settings* del usuario (o de la organización) > *Applications* > *Manage Access Tokens* >
+   *Generate New Token*.
+2. Otorgar permiso de escritura sobre:
+   - **repository** (necesario para crear tags).
+   - **issue** (necesario para crear PRs, ya que Gitea expone los PRs bajo el mismo scope).
+3. Generar el token y guardarlo en `.repository-token`.
+
+Ejemplo de pipeline (Gitea Actions) para taggear automáticamente en cada push a una rama principal:
+
+```yaml
+# .gitea/workflows/tag.yml
+name: Tag and publish
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  tag:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v3
+
+      - run: uv run git-flow tag --token=${{ secrets.GIT_FLOW_TOKEN }}
+
+      - run: uv build
+      - run: uv publish --token=${{ secrets.PYPI_TOKEN }}
+```
+
 ## Taggeo automático por pipeline
 
-Éste repositorio utiliza Git Flow para el taggeo automático usando pipelines, se puede ver el
-archivo `bitbucket-pipelines.yml` como ejemplo. El comando `git-flow tag` soporta el pasaje del
-token mediante la opción `--token=<TOKEN>`. Ver la sección [Configuración](#configuracion) para las
-instrucciones de como generar este token. El mismo necesita scope `write:repository:bitbucket`.
+En todos los casos, `git-flow tag` detecta que se está ejecutando desde un pipeline (no encuentra
+`.repository-token` en el repositorio) y usa el token pasado por `--token=<TOKEN>` tanto para crear
+el tag en el remoto como para pushear el commit del `CHANGELOG.md` generado, en vez de crear el tag
+únicamente en forma local como sucede al ejecutarlo manualmente sin remoto configurado.