From e8c0c0b777d31fa94cd3f01fbf9c68b165d77015 Mon Sep 17 00:00:00 2001 From: Jonathan Teran Carballo Date: Sun, 13 Sep 2026 23:18:47 -0300 Subject: [PATCH] docs: actualizar README con secciones por remoto y ejemplos de pipeline Documenta como generar tokens de acceso para Github, Gitlab, Bitbucket y Gitea, y agrega ejemplos de pipeline para taggeo automatico en cada uno. Co-Authored-By: Claude Sonnet 5 --- README.md | 162 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 151 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index e846040..2484fbf 100644 --- a/README.md +++ b/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 -h` para +Git Flow cuenta con los siguientes comandos para guiar el workflow (ver `git-flow -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=` 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=`. 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=` 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. -- 2.54.0