Azure DevOps Pipelines: crie branches com parâmetros em uma pipeline manual (Parte 1)

Toda equipe que trabalha com Git no Azure DevOps repete, dia após dia, o mesmo ritual: criar uma branch com o nome no padrão certo antes de começar uma atividade. Quando isso vira tarefa manual, aparecem os “feature/ajuste-final-2” da vida e a rastreabilidade some. A boa notícia é que dá para transformar essa criação de branch em uma pipeline com um clique, padronizando o nome a partir de parâmetros como projeto, atividade e squad.

Este é o primeiro post (Parte 1) de uma série de dois sobre Azure DevOps Pipelines. Aqui vamos montar uma pipeline em YAML, executada manualmente (sem gatilho automático), que recebe parâmetros de entrada e cria uma branch no repositório.

Objetivo da Parte 1: sair do “cada um cria a branch como quer” para uma pipeline que gera o nome padronizado automaticamente, com governança e histórico de quem rodou o quê.

O que são parâmetros de runtime

No Azure Pipelines, os runtime parameters permitem que quem executa a pipeline informe valores antes da execução. Diferente das variables, os parâmetros são tipados (string, number, boolean, object, entre outros), podem ter valores restritos a uma lista e são resolvidos no momento em que a pipeline é enfileirada — antes de rodar. É exatamente o que precisamos para pedir projeto, atividade e squad.

• name: identificador usado no YAML via ${{ parameters.nome }}.
• displayName: rótulo amigável exibido na tela de execução.
• type: tipo do parâmetro (aqui usamos string).
• default: valor padrão (opcional, mas recomendado).
• values: lista fechada de opções — útil para restringir a squad a valores válidos.

Rodando sem trigger automático

Como não queremos que a pipeline dispare a cada push ou pull request, definimos trigger: none (e pr: none). Assim ela só roda quando alguém clica em Run pipeline. A própria documentação da Microsoft usa esse padrão nos exemplos de parâmetros: com trigger: none, você consegue escolher os valores manualmente na hora de executar.

A pipeline: criando a branch via git CLI

A forma mais direta de criar a branch é usar o próprio Git no agente. O passo checkout: self com persistCredentials: true mantém o token de autenticação disponível para o push. Repare como os parâmetros são interpolados com ${{ parameters.x }} para montar o nome da branch.

: # azure-pipelines.yml
: # Pipeline MANUAL que cria uma branch a partir de parametros de entrada

parameters:
  - name: projeto
    displayName: Projeto
    type: string
    default: meu-projeto
  - name: atividade
    displayName: Numero ou nome da atividade
    type: string
  - name: squad
    displayName: Squad responsavel
    type: string
    values:            # lista fechada: so aceita estas squads
      - squad-alpha
      - squad-bravo
      - squad-charlie

# Sem gatilho automatico: so roda no "Run pipeline"
trigger: none
pr: none

pool:
  vmImage: ubuntu-latest

steps:
  - checkout: self
    persistCredentials: true   # mantem o token git p/ conseguir dar push

  - script: |
      set -e
      # Monta o nome padronizado com os parametros
      NOVA_BRANCH="feature/${{ parameters.squad }}/${{ parameters.projeto }}-${{ parameters.atividade }}"
      echo "Criando a branch: $NOVA_BRANCH"

      # Cria a branch localmente e envia para o repositorio remoto
      git checkout -b "$NOVA_BRANCH"
      git push origin "$NOVA_BRANCH"
    displayName: "Criar branch via git CLI"

Alternativa: criar a branch pela REST API

Se você prefere não depender do checkout completo, dá para criar a referência (branch) direto pela REST API do Azure DevOps, autenticando com a variável predefinida System.AccessToken. Segundo a documentação, o token deve ser mapeado explicitamente como variável de ambiente usando a chave env. Para criar uma nova ref, o corpo envia oldObjectId como uma sequência de 40 zeros e o newObjectId com o commit de origem.

  - script: |
      set -e
      NOVA_BRANCH="feature/${{ parameters.squad }}/${{ parameters.projeto }}-${{ parameters.atividade }}"
      BASE_SHA=$(git rev-parse HEAD)   # commit atual como ponto de partida

      # POST /_apis/git/repositories/{repo}/refs?api-version=7.1
      curl -sf -X POST \
        -H "Authorization: Bearer $SYSTEM_ACCESSTOKEN" \
        -H "Content-Type: application/json" \
        "$(System.CollectionUri)$(System.TeamProject)/_apis/git/repositories/$(Build.Repository.Name)/refs?api-version=7.1" \
        -d "[{\"name\":\"refs/heads/$NOVA_BRANCH\",\"oldObjectId\":\"0000000000000000000000000000000000000000\",\"newObjectId\":\"$BASE_SHA\"}]"
    displayName: "Criar branch via REST API"
    env:
      SYSTEM_ACCESSTOKEN: $(System.AccessToken)   # obrigatorio mapear o token

As variáveis usadas são todas predefinidas pelo Azure Pipelines: System.CollectionUri (URI da organização), System.TeamProject (nome do projeto) e Build.Repository.Name (nome do repositório). Não invente nomes — confira sempre na referência de variáveis predefinidas.

Importante: para o push ou a REST API funcionarem, a identidade de build do projeto precisa ter permissão de Contribute / criar branch no repositório. Sem isso, o retorno traz status como createBranchPermissionRequired.

Como executar manualmente

Depois de commitar o arquivo YAML e criar a pipeline apontando para ele, o fluxo é:

1. Vá em Pipelines e selecione a pipeline recém-criada.
2. Clique em Run pipeline.
3. O painel de execução mostra os campos Projeto, Numero ou nome da atividade e Squad responsavel — exatamente os displayName definidos. A squad aparece como uma lista suspensa por causa de values.
4. Preencha os valores e confirme em Run.

Se você não informar um valor, o default é usado (quando existir). Vale lembrar que os parâmetros só aparecem nessa tela ao rodar a pipeline pela interface — pelo editor YAML eles não são exibidos.

Continua na Parte 2

A base está pronta — e é só metade do caminho. Padronizar o nome da branch resolve a rastreabilidade da criação, não a do ciclo de vida: a branch nasce certinha e some, o board fica desatualizado e o repositório acumula branches órfãs.

Na Parte 2, que fecha a série, a mesma pipeline passa a abrir o Pull Request automaticamente, vincular o Work Item da atividade pela relação ArtifactLink, ligar o auto-complete em nome de quem executou — e criar, também por API, as branch policies (build de validação e aprovação obrigatória) que fazem o merge automático significar alguma coisa.

Na Parte 1 saímos do zero: uma pipeline manual, com parâmetros tipados e trigger: none, capaz de criar branches padronizadas por git CLI ou pela REST API. Um clique, nome no padrão certo, rastreabilidade garantida.

Fontes

• Use runtime and type-safe parameters — Azure Pipelines (Microsoft Learn)
• Predefined variables — Azure Pipelines (Microsoft Learn)
• Git Refs – Update Refs — Azure DevOps REST API (Microsoft Learn)