Git Flow

Herramienta para establecer un workflow siguiendo Conventional Commits (CC), Conventional Branch (CB), y SemVer.

Esta diseñada para facilitar la creación de commits y branches en un formato estandar, que permite derivar versiones automaticamente de los merges sobre ramas principales.

Instalación

Se puede instalar con pip ejecutando el siguiente comando: pip install git-flow-envs. Sin embargo, se sugiere utilizar pipx (seguir la documentación para instalarlo), ya que aisla las dependencias de la herramienta en un venv. Una vez instalado, simplemente ejecutamos pipx install git-flow-envs

Luego podemos verificar que se haya instalado correctamente ejecutando: git-flow --help

Configuración

Para poder usar la herramienta en un repositorio, necesitamos inicializarlo:

git-flow init

El comando solicitará 2 opciones:

• Ramas principales: Ramas que representan los entornos principales del proyecto. Por ejemplo: dev,test,prod.

• Remoto (opcional): Nombre del remoto que se usará para crear PRs, y taggear merges automáticamente. Por el momento, se soportan los siguientes remotos:

  • Bitbucket
  • Github
  • Gitea
  • Gitlab

  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 para las instrucciones de cómo generar el token en cada proveedor.

  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 los siguientes comandos para guiar el workflow (ver git-flow <command> --help 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 uno de los entornos.
• tag: Crea un tag sobre el ultimo merge siguiendo SemVer (ver Tag).
• release: Prepara la rama actual para pasarse al siguiente entorno configurado.
• branch ls: Lista las ramas del repositorio, agrupadas por entorno objetivo.
• branch clean: Elimina las ramas alcanzables desde HEAD (locales por defecto, o remotas con --remote), dejando un reporte CSV (branch-clean-report.csv) con nombre, commit, autor y fecha de cada rama eliminada.

Por defecto solo se muestra cada paso que se ejecuta. Con git-flow --verbose <command> (o -v) se muestra además la salida de cada comando git y el traceback completo de los errores.

El workflow para el cual se penso la herramienta es el siguiente:

1. Sobre la primer rama principal configurada (por ejemplo, dev), se crea una nueva rama con git-flow new
2. Se realizan cambios y se commitean los mismos con git-flow commit (se repite hasta que se considere que la rama esté lista para mergear)
3. Se ejecuta git-flow merge para mergear la rama al entorno que corresponda (en este caso, dev). En caso de tener un remoto configurado, el comando crea un PR para integrar el cambio. Si no, simplemente se ejecuta un git merge simple.
4. Para versionar este último merge, se ejecuta git-flow tag, ya sea localmente o desde un pipeline para que se ejecute en cada merge.
5. Una vez que la rama fue correctamente integrada a un entorno (por ejemplo, dev), se usa git-flow release para crear una nueva rama para integrar unicamente los cambios de esa rama sobre el siguiente entorno (por ejemplo, test). Si la rama original era 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 ls para ver en qué entorno está cada rama, y cuáles están todavía en progreso (wip/) o descartadas (trash/).

Tag

git-flow tag [--target=<RAMA>] [--token=<TOKEN>] [--update-changelog]

• --target: rama principal sobre la que se taggea. Por defecto, la rama actual. Debe ser una de las ramas principales configuradas.
• --token: Access Token del remoto. Si se pasa, se asume que corre en un pipeline: los commits y el último tag se obtienen por API del remoto y el tag se crea en el remoto (y también localmente). Si no, se usa .repository-token y todo se resuelve localmente.
• --update-changelog: genera la entrada correspondiente en CHANGELOG.md y la commitea antes de taggear (en un pipeline, además hace push del commit).

Comportamiento:

• El tag se crea sobre el último merge (first-parent) de la rama. Si ese merge ya tiene un tag, no se hace nada.
• La versión se calcula a partir de los tipos de commit (CC) del último merge. Si ningún commit implica un salto de versión, se avisa y el comando termina con código de salida 1.
• Con más de un entorno configurado, cada rama versiona por separado con el nombre del entorno como sufijo (por ejemplo, v1.2.0-prod). Con un solo entorno no se agrega sufijo.
• Si el merge viene del entorno anterior (por ejemplo, dev a test), no se calcula una nueva versión: se promueve la del entorno anterior cambiando el sufijo (si dev está en v1.2.0-dev y test en v1.0.0-test, el nuevo tag es v1.2.0-test), sin importar los tipos de commit. Si ese tag ya existe en el destino, el comando falla. En un pipeline, el merge se detecta por la rama origen del PR; localmente, porque el merge trae tags del entorno anterior que el destino no tenía.

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:

# .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: 10

      - 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:

# .gitlab-ci.yml
tag:
  image: python:3.14
  variables:
    GIT_DEPTH: 10
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  script:
    - pip install uv
    # GitLab hace checkout en detached HEAD, por lo que la rama se indica explícitamente
    - uv run git-flow tag --target=$CI_COMMIT_BRANCH --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:

# bitbucket-pipelines.yml
image: python:3.14

clone:
  depth: 10

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:

# .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: 10

      - 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

En todos los casos, al pasar --token=<TOKEN> git-flow tag asume que se está ejecutando desde un pipeline: obtiene los commits del último PR / MR y el último tag por API del remoto, y usa el token tanto para crear el tag en el remoto como para pushear el commit del CHANGELOG.md generado (con --update-changelog), en vez de resolver todo en forma local.