Em pipelines de CI/CD, a gestão de variáveis é essencial para adaptar o comportamento dos jobs conforme o ambiente, o estado da build ou a entrada do usuário. Entre as técnicas mais poderosas está o uso do comando de logging ##vso task.setvariable, que permite criar e atualizar variáveis em tempo de execução durante a execução de uma tarefa. Neste artigo, exploramos o que é o ##vso task.setvariable, como utilizá-lo corretamente, exemplos práticos, boas práticas de segurança e várias variações que ajudam a tornar seus pipelines mais robustos, reutilizáveis e fáceis de manter.
O que é ##vso task.setvariable e por que é importante
O comando de logging ##vso task.setvariable funciona como uma forma de comunicação entre as etapas de um pipeline. Ao emitir essa linha durante a execução, uma tarefa pode definir o valor de uma variável que será lida por etapas subsequentes. Isso permite encadear decisões, compartilhar resultados intermediários, configurar caminhos dinâmicos e adaptar o comportamento da execução sem precisar recompor o pipeline inteiro.
Entre as vantagens, destacam-se:
- Flexibilidade para propagar informações entre etapas sem depender de parâmetros estáticos;
- Possibilidade de marcar variáveis como secretas para que seus conteúdos não apareçam nos logs;
- Capacidade de controlar fluxos condicionais com base em valores calculados ao longo da execução;
- Facilidade de manutenção: variáveis definidas dinamicamente reduzem a necessidade de duplicar configurações.
Ao trabalhar com o ##vso task.setvariable, você aproveita o poder dos logs de pipeline para ajustar o comportamento de tarefas futuras, tornando o fluxo de entrega mais inteligente e responsivo às mudanças que ocorrem durante a execução.
Sintaxe e forma correta de usar ##vso task.setvariable
Formato padrão com notação de log
A forma mais comum de definir uma variável com o recurso de logging é através da expressão entre colchetes, conhecida como logging command:
##vso[task.setvariable variable=NOME_DA_VARIAVEL;]VALORNeste formato, o valor VALOR fica disponível para as etapas subsequentes sob o nome NOME_DA_VARIAVEL. Se a intenção for ocultar o conteúdo gerado, é possível marcar a variável como secreta.
Exemplo prático:
echo "Compilação concluída com sucesso"
echo "##vso[task.setvariable variable=BUILD_STATUS;]SUCESSO"Depois disso, uma etapa seguinte pode ler BUILD_STATUS e decidir o próximo passo com base no valor definido.
Formato alternativo de logs: a expressão ##vso task.setvariable
Alguns ambientes ou documentação utilizam a expressão textual sem os colchetes para referenciar o comando. Em contextos de leitura humana, você pode encontrar menções a ##vso task.setvariable como forma de descrever o que a linha faz. No entanto, para a execução real, o formato com brackets é o reconhecido pelo pipeline. Ainda assim, o uso textual pode aparecer em tutoriais, logs explicativos ou notas de configuração para facilitar a compreensão do papel do comando.
Variáveis secretas com issecret
Para evitar a exposição de informações sensíveis nos logs, é comum marcar a variável como secreta. O exemplo abaixo mostra como definir uma variável secreta com o ajuste issecret:
echo "##vso[task.setvariable variable=API_TOKEN;issecret=true]valor_do_token"Observação: quando issecret=true é usado, o conteúdo não é exibido nos logs, mesmo que a tarefa o tenha impresso acidentalmente. Assim, você protege segredos como tokens de API, senhas temporárias e chaves de acesso.
Exemplos práticos de uso de ##vso task.setvariable em pipelines
Exemplo 1: propagação de resultados de testes
Imagine uma etapa que executa testes unitários. O resultado pode definir uma variável para acionar passos condicionais seguintes.
npm test
echo "##vso[task.setvariable variable=TESTS_PASSED;]true"Em etapas subsequentes, você pode avaliar o valor TESTS_PASSED para decidir se deve empurrar a build para o próximo estágio ou falhar a pipeline com uma mensagem personalizada.
Exemplo 2: configuração dinâmica de caminhos
Durante a implantação, pode ser necessário construir caminhos de saída com base no ambiente. Defina uma variável com o caminho calculado e utilize-a nas etapas seguintes.
OUTPUT_DIR="dist/production"
echo "##vso[task.setvariable variable=OUTPUT_DIR;]$OUTPUT_DIR"Depois, em etapas de cópia ou upload, use a variável OUTPUT_DIR para referenciar o destino correto.
Exemplo 3: a leitura de valor de segredo em uma etapa de API
Considere uma sequência em que uma API precisa de um token. Defina o token como segredo e utilize-o apenas na chamada API da etapa seguinte, sem expor o valor.
echo "##vso[task.setvariable variable=API_TOKEN;issecret=true]TOKEN_AQUI"Chame a API com a variável API_TOKEN na etapa de execução subsequente sem revelar o token nos logs.
Exemplo 4: múltiplas variáveis em cadeia
É comum criar várias variáveis em uma única etapa para facilitar a construção de mensagens ou comandos subsequentes.
echo "##vso[task.setvariable variable=BUILD_NUMBER;]1234"
echo "##vso[task.setvariable variable=BUILD_TAG;]release-1234"Variáveis BUILD_NUMBER e BUILD_TAG passam a ser consumidas pelas tarefas seguintes, mantendo o pipeline limpo e previsível.
Boas práticas de segurança com ##vso task.setvariable
Marcar conteúdo sensível como secret
Quando o valor gerado é confidencial, utilize issecret=true para evitar vazamento nos logs. Além disso, minimize a exposição de segredos em mensagens de commit, mensagens de build e logs de console.
Menor alcance possível para variáveis
Defina variáveis apenas com o escopo necessário. Em pipelines complexos, evite declarar variáveis globais quando uma variável com escopo de job já resolve o objetivo.
Auditoria e governança
Documente os nomes das variáveis criadas por meio de ##vso task.setvariable e associe-as a passos específicos do fluxo de entrega. Isso facilita auditorias, revisões e a manutenção futura do pipeline.
Integração com YAML: definindo variáveis com ##vso task.setvariable
Uso em pipelines declarativos
Em pipelines YAML, você pode chamar logging commands dentro de etapas de script para introduzir variáveis dinâmicas para as etapas seguintes. A ideia é manter o fluxo declarativo, mas com adaptabilidade programática.
trigger:
- main
jobs:
- job: Build
steps:
- script: |
echo "Calculando versão..."
VERSION=$(date +%Y%m%d)
echo "##vso[task.setvariable variable=BUILD_VERSION;]$VERSION"
displayName: "Gerar Build Version"
- script: |
echo "Versão da build: $(BUILD_VERSION)"
displayName: "Exibir Build Version"Neste exemplo, BUILD_VERSION é definida na etapa anterior e pode ser consumida pela etapa subsequente dentro do mesmo job.
Boas práticas ao combinar YAML com variáveis dinâmicas
- Sequencie etapas de forma lógica, garantindo que a variável esteja disponível antes de ser lida;
- Nomeie variáveis de forma descritiva para facilitar a leitura e a manutenção;
- Combine issecret quando for necessário manter segredos fora do log;
- Documente a finalidade de cada variável nos comentários do arquivo YAML;
Erros comuns ao usar ##vso task.setvariable e como evitá-los
Atenção à grafia e à sintaxe
Erros frequentes incluem grafia incorreta do comando ou uso inadequado de aspas. Verifique se a forma correta de definir a variável é a linha de comando com brackets:
##vso[task.setvariable variable=NAME;]VALUEUsar variações sem brackets pode não ser interpretado pelo runner de pipeline, resultando na ausência da variável nas etapas seguintes.
Esquecer de consumir a variável
Definir a variável não garante que ela esteja disponível imediatamente. Em alguns cenários, é necessário referenciar a variável com a sintaxe apropriada da plataforma (por exemplo, $(NAME) em YAML) e assegurar que o momento de leitura seja posterior à definição.
Confusão entre variável de ambiente e variável de pipeline
Entenda que as variáveis criadas com ##vso task.setvariable são específicas do pipeline de execução corrente. Elas não devem substituir variáveis definidas no nível de projeto ou globalmente, a menos que haja necessidade explícita.
Casos de uso adicionais: secrets, condições, e fluxos de decisão
Condições baseadas em variáveis dinâmicas
Variáveis definidas com ##vso task.setvariable podem ser usadas para conduzir decisões condicionais em etapas, como disparar deploys para ambientes específicos apenas quando certas condições são atendidas.
Fluxos de decisão com múltiplos outcomes
Ao definir variáveis intermediárias, você pode criar caminhos alternativos de execução com base nos valores calculados durante a pipeline, enriquecendo a lógica de entrega.
Integração com ações de aprovação e verificação
Variáveis dinâmicas ajudam a padronizar mensagens de aprovação, a passar informações para tarefas de verificação ou a ativar/desativar etapas de teste com base em métricas coletadas durante a build.
Reversão de ordem e variações de uso: leitura e leitura inversa
Variações com ordem invertida do termo-chave
Para fins de SEO e leitura humana, você pode encontrar referências que colocam o termo-chave em ordem inversa, como “task.setvariable ##vso” ou “variável ##vso task.setvariable” em textos de contextualização. Embora a forma padrão no pipeline seja com a sintaxe de logging, explorar essas variações ajuda a cobrir diferentes maneiras pelas quais leitores buscam o tema.
Sinônimos e relembranças do conceito
Além de manter o termo principal, é útil mencionar “definir variável em tempo de execução”, “passar valor entre etapas” e “variáveis dinâmicas em pipelines” para enriquecer o conteúdo sem perder o foco no comando de logging.
Conclusão: maximizando o potencial de ##vso task.setvariable
O comando ##vso task.setvariable representa uma ferramenta poderosa para tornar pipelines do Azure DevOps mais adaptáveis, seguras e fáceis de manter. Ao utilizá-lo com cuidado — definindo variáveis de forma clara, protegendo segredos com issecret, respeitando o escopo e consumindo as variáveis nas etapas seguintes — você obtém um fluxo de entrega mais previsível, com menos ruídos e menos duplicação de configuração.
Ao combinar o uso de ##vso task.setvariable com práticas modernas de CI/CD, como pipelines YAML bem estruturados, testes automáticos, e validação contínua, você constrói uma base sólida para entregas rápidas e confiáveis. É uma estratégia essencial para equipes que buscam agressivamente automação, consistência e governança em seus ambientes de desenvolvimento, teste e produção.
Recursos adicionais para aprofundar o tema
Para estender seu conhecimento, recomendamos explorar a documentação oficial de logs de pipeline, guias sobre variáveis de ambiente, e tutoriais sobre integração entre etapas de build, teste e deploy. A prática constante com exemplos reais de suas próprias pipelines ajudará a internalizar o uso eficaz do ##vso task.setvariable e a aplicar as melhores soluções para casos específicos de negócio.
Resumo rápido das principais dicas
- Use o formato padrão com brackets: ##vso[task.setvariable variable=NOME;]VALOR;
- Marque conteúdos sensíveis com issecret=true quando necessário;
- Defina o escopo da variável para o menor alcance possível;
- Leia as variáveis com a sintaxe apropriada na etapa seguinte
- Documente o uso de variáveis dinâmicas para facilitar manutenção e auditoria