Use variáveis e parâmetros com segurança em seu pipeline

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2020

Saiba como utilizar variáveis e parâmetros com segurança para coletar informações de usuários do pipeline. Para obter mais informações, consulte os seguintes artigos:

• Definir variáveis
• Definir variáveis secretas
• Usar variáveis predefinidas
• Usar parâmetros de runtime
• Usar tipos de modelo

Tenha cuidado com variáveis secretas. Os métodos recomendados para definir variáveis secretas incluem usar a interface do usuário, criar um grupo de variáveis ou utilizar um grupo de variáveis originado do Azure Key Vault. Para obter mais informações, consulte definir variáveis de ambiente.

Variáveis

As variáveis servem como um método conveniente para coletar informações do usuário antecipadamente e facilitar a transferência de dados entre as etapas do pipeline. No entanto, tenha cuidado ao trabalhar com variáveis. Por padrão, as variáveis recém-criadas, definidas em YAML ou com script, são de leitura e gravação. As etapas downstream podem modificar valores de variáveis inesperadamente.

Por exemplo, considere o seguinte snippet de script:

msbuild.exe myproj.proj -property:Configuration=$(MyConfig)

Se uma etapa anterior for definida MyConfig como Debug & deltree /y c:, isso pode levar a consequências não intencionais. Embora este exemplo apenas exclua o conteúdo do seu agente de build, ele destaca o perigo potencial de tais configurações.

Você pode tornar as variáveis somente leitura. Variáveis do sistema como Build.SourcesDirectory, variáveis de saída de tarefa e variáveis de tempo de espera são sempre somente leitura. Variáveis criadas no YAML ou criadas em tempo de execução por um script podem ser designadas como somente leitura. Quando um script ou tarefa cria uma variável, ele pode passar o sinalizador isReadonly=true no próprio comando de registro em log para tornar a variável somente leitura.

No YAML, você pode especificar variáveis somente leitura usando a seguinte chave específica:

variables:
- name: myReadOnlyVar
  value: myValue
  readonly: true

Variáveis de tempo de espera

Ao definir uma variável no editor de interface do usuário do Pipelines, você pode permitir que os usuários substituam seu valor durante a execução do pipeline. Essas variáveis são chamadas de variáveis de tempo de fila e são sempre definidas no editor de interface do usuário do Pipelines.

As variáveis de tempo de espera são expostas ao usuário final quando executam manualmente um pipeline e podem alterar seus valores.

Os usuários precisam de permissão para editar a configuração de enfileiramento de builds no pipeline e especificar as variáveis definidas de tempo de espera.

Limitar as variáveis que podem ser definidas no momento da colocação na fila

A interface do usuário e a API REST usadas para executar um pipeline fornecem meios para os usuários definirem novas variáveis durante o tempo de espera.

Nos primeiros dias do Azure Pipelines, essa funcionalidade tinha os seguintes problemas:

• Ele permitiu que os usuários definissem novas variáveis ainda não definidas pelo autor do pipeline na definição.
• Ela permitia que os usuários substituíssem as variáveis do sistema.

Para resolver esses problemas, definimos uma configuração para limitar as variáveis que podem ser definidas no tempo da fila. Com essa configuração ativada, somente as variáveis explicitamente marcadas como "Settable no momento da fila" podem ser definidas. Em outras palavras, você pode definir qualquer variável no momento da fila, a menos que essa configuração esteja ativada.

O cenário foi projetado para funcionar nos níveis de organização e projeto.

• Nível da organização:
  • Quando a configuração está ativada, ela impõe que apenas variáveis explicitamente marcadas como "Settable no momento da fila" possam ser modificadas para todos os pipelines em todos os projetos dentro da organização.
  • Os Administradores de Coleção de Projetos podem habilitar ou desabilitar essa configuração.
  • Acesse essa configuração em Configurações da>organização Configurações de pipelines>.
• Nível do projeto:
  • Semelhante ao nível da organização, habilitar essa configuração garante que apenas as variáveis marcadas como "Settable no momento da fila" possam ser modificadas para todos os pipelines dentro do projeto específico.
  • Se a configuração no nível da organização estiver habilitada, ela se aplicará a todos os projetos e não poderá ser desativada.
  • Os administradores de projeto podem ativar ou desativar essa configuração.
  • Acesse essa configuração em Configurações do>projeto Configurações de pipelines>.

O exemplo a seguir mostra que a configuração está ativada e seu pipeline define uma variável chamada my_variable que não é configurável no momento da fila.

Em seguida, suponha que você deseja executar o pipeline. O painel Variáveis não mostra nenhuma variável e o botão Adicionar variável está ausente.

O uso das chamadas de API REST Builds – Queue e Runs – Run Pipeline para enfileirar uma execução de pipeline e definir o valor de my_variable ou de uma nova variável falha com um erro semelhante ao seguinte.

{
  "$id": "1",
  "innerException": null,
  "message": "You can't set the following variables (my_variable). If you want to be able to set these variables, then edit the pipeline and select Settable at queue time on the variables tab of the pipeline editor.",
  "typeName": "Microsoft.Azure.Pipelines.WebApi.PipelineValidationException, Microsoft.Azure.Pipelines.WebApi",
  "typeKey": "PipelineValidationException",
  "errorCode": 0,
  "eventId": 3000
}

Parâmetros

Ao contrário das variáveis, um pipeline em execução não pode modificar os parâmetros do pipeline. Os parâmetros têm tipos de dados como number e string, e podem ser restritos a subconjuntos de valores específicos. Essa restrição é valiosa quando um aspecto configurável pelo usuário do pipeline deve aceitar apenas valores de uma lista predefinida, garantindo que o pipeline não aceite dados arbitrários.

Habilitar a validação de parâmetros de argumentos de tarefas do shell

Os pipelines podem fazer referência a tarefas executadas no pipeline. Algumas tarefas incluem um arguments parâmetro que permite especificar mais opções para a tarefa.

Quando a configuração Habilitar validação de parâmetro de argumentos de tarefas do shell está habilitada, o parâmetro arguments passa por revisão para garantir que o shell execute corretamente caracteres como ponto e vírgula, aspas e parênteses. Semelhante à opção Limitar variáveis que podem ser definidas no tempo de fila, você pode configurar Habilitar validação de parâmetro de argumentos de tarefas do shell no nível da organização ou do projeto em Configurações>Configurações Configurações de Pipelines.>

Quando esse recurso é ativado, qualquer problema de validação relacionado ao arguments parâmetro aciona uma mensagem de erro como a seguinte:

Detected characters in arguments that may not be executed correctly by the shell. Please escape special characters using backtick (`).

Para resolver esse problema, ajuste os argumentos escapando caracteres especiais, conforme indicado na mensagem de erro. Essa validação se aplica ao arguments parâmetro nas seguintes tarefas específicas:

• PowerShell
• BatchScript
• Bash
• SSH
• AzureFileCopy
• WindowsMachineFileCopy

Próximas etapas

Proteja sua infraestrutura compartilhada