在GitLab CI中如何正确映射Git分支到Kubernetes命名空间？

需求背景 #

需要实现Git分支与Kubernetes命名空间的固定映射，让GitLab CI流水线自动根据分支将Helm Chart部署到对应命名空间，例如：

master branch  -> prd namespace
devel branch   -> dev namespace

此前使用bash逻辑或零散CI变量的方式属于临时方案，需采用标准化、可维护的实现方式，同时明确：Helm的values文件无法直接指定部署的命名空间——命名空间是通过Helm命令的--namespace（或-n）参数指定的，values文件仅用于配置Chart内部的应用参数（如资源限制、镜像版本等）。

标准化实现方案 #

1. GitLab环境（Environments）+ 变量组（推荐） #

这是GitLab官方推荐的最佳实践，将环境配置与变量分离，便于权限管理和审计：

• 在GitLab项目中创建对应环境：比如production对应master分支，development对应devel分支
• 为每个环境创建独立的变量组，例如：
  • prod_vars组定义变量K8S_NAMESPACE=prd
  • dev_vars组定义变量K8S_NAMESPACE=dev
• 在.gitlab-ci.yml中为不同分支的部署任务绑定对应环境，自动加载变量：

deploy_prod:
  stage: deploy
  environment:
    name: production
  only:
    - master
  script:
    # 确保命名空间存在（可选）
    - kubectl create namespace $K8S_NAMESPACE --dry-run=client -o yaml | kubectl apply -f -
    - helm upgrade --install my-app ./chart --namespace $K8S_NAMESPACE --values values_prd.yaml

deploy_dev:
  stage: deploy
  environment:
    name: development
  only:
    - devel
  script:
    - kubectl create namespace $K8S_NAMESPACE --dry-run=client -o yaml | kubectl apply -f -
    - helm upgrade --install my-app ./chart --namespace $K8S_NAMESPACE --values values_dev.yaml

该方案支持环境保护规则（如生产部署需审批），符合企业级运维规范。

2. 配置文件集中管理分支映射 #

采用「配置即代码」的思路，将分支与命名空间的映射规则集中存储，避免零散的脚本逻辑：

• 在项目根目录创建branch-namespace-map.yaml配置文件：

master: prd
devel: dev
feature/*: dev-feature

• 在CI脚本中使用yq（或jq）读取配置，动态获取命名空间：

deploy:
  stage: deploy
  only:
    - master
    - devel
    - /feature\/.*/
  script:
    # 读取分支对应的命名空间，默认用dev作为降级方案
    - export K8S_NAMESPACE=$(yq eval ".\"$CI_COMMIT_BRANCH\"" branch-namespace-map.yaml || echo "dev")
    # 匹配对应环境的values文件
    - export VALUES_FILE="values_${K8S_NAMESPACE#dev-}.yaml"
    - kubectl create namespace $K8S_NAMESPACE --dry-run=client -o yaml | kubectl apply -f -
    - helm upgrade --install my-app ./chart --namespace $K8S_NAMESPACE --values $VALUES_FILE

该方案便于统一修改映射规则，无需改动CI脚本。

3. CI规则（Rules）绑定分支与变量 #

使用GitLab CI的rules关键字，直接在CI配置中定义分支到变量的映射，逻辑清晰直观：

deploy:
  stage: deploy
  rules:
    - if: '$CI_COMMIT_BRANCH == "master"'
      variables:
        K8S_NAMESPACE: prd
        VALUES_FILE: values_prd.yaml
    - if: '$CI_COMMIT_BRANCH == "devel"'
      variables:
        K8S_NAMESPACE: dev
        VALUES_FILE: values_dev.yaml
    - if: '$CI_COMMIT_BRANCH =~ /feature\/.*/'
      variables:
        K8S_NAMESPACE: dev-feature
        VALUES_FILE: values_dev.yaml
  script:
    - kubectl create namespace $K8S_NAMESPACE --dry-run=client -o yaml | kubectl apply -f -
    - helm upgrade --install my-app ./chart --namespace $K8S_NAMESPACE --values $VALUES_FILE

该方案无需额外配置文件，所有映射逻辑集中在CI配置中，适合小型项目或规则简单的场景。

内容的提问来源于stack exchange，提问作者emivespa