CLI e API: acesso e verificação controlados

Preparar o cliente

Obtenha a distribuição do seu sistema operacional em Developer Tools e compare o checksum com o valor publicado. Use a ajuda dessa distribuição como referência dos comandos. A versão da CLI pode ser diferente da versão da plataforma; o nome do pacote, sozinho, não comprova compatibilidade nem integridade.

A CLI usa uma chave pessoal da API do Dova. Crie-a pela interface autorizada de API Keys e guarde o valor em um mecanismo privado. Ela não é uma chave OpenAI. Evite colocar chaves ou senhas em argumentos de comandos, capturas, arquivos compartilhados ou históricos. O login interativo solicita a chave sem exibi-la. Utilize uma conta do sistema operacional adequada ao trabalho realizado.

Consultar antes de modificar

Estes comandos não contêm segredos e consultam o contexto atual:

dova --version
dova --help
dova login
dova status --output json
dova repository list --output json
dova mapping list --output json
dova workflow list --output json
dova run list --output json
dova logout

dova login utiliza o serviço público configurado pela distribuição. Confira se status mostra o tenant esperado antes de executar operações com efeitos. A CLI salva a configuração de autenticação localmente; proteja a conta do sistema e execute logout quando necessário. Fechar o terminal não revoga uma chave pessoal.

Executar um teste autorizado

A ajuda de dova workflow run --help descreve entradas, parâmetros e espera. Selecione primeiro um Workflow de laboratório publicado, com dependências aceitas. A opção --wait observa a tentativa; atingir o tempo limite do cliente não comprova que a execução terminou. Consulte Monitor antes de reenviar. Os comandos cancel, terminate, rerun e recover têm consequências e verificações de estado diferentes.

Distinguir os fluxos de autenticação

A API com sessão web mantém login, MFA quando exigido, cookie e proteção CSRF para alterações. Se login retornar authenticated:false com mfaRequired:true, ainda falta concluir o MFA; HTTP 200 não significa autenticação concluída. Após verificar o MFA, consulte a sessão e utilize o CSRF atual no fluxo web correspondente.

Uma chave pessoal Bearer da CLI não se transforma em sessão web e não substitui o MFA para configurar o provedor global do DovaAI. Essa configuração pertence ao superusuário único autorizado, por seu fluxo protegido. Não copie cookies do navegador para comandos.

Conferir resultados e erros

Para 401, revise credencial ou sessão; para 403, revise função e tenant. Um erro de validação exige corrigir o recurso indicado, não repetir gravações sem análise. Preserve identificadores seguros da tentativa para diagnóstico, sem registrar cabeçalhos de autenticação. Confira uma resposta aceita no objeto ou na tentativa de execução correspondente.

Exportar uma promoção para Git/DevOps

Configuration → Environment promotions permite exportar o manifesto de uma release aplicada. O kit GitOps acrescenta promotion-export --release-id <id> --output dova/promotion-release.json por app/bin/dova_gitops.py, usando configuração e autenticação autorizadas. O comando consulta a release, verifica seu digest e grava um arquivo local; não promove, executa nem modifica Dova ou Git.

Execute no repositório local preparado para o kit. Revise o manifesto antes de registrá-lo no controle de versões: preserva artefatos publicados, dependências e procedência; referências secretas viram placeholders. Registrar repository, commit e tag não autentica um repositório remoto nem faz push. GitHub permanece como repositório e GitHub Actions não é ativado.

Contexto de ambiente

Antes de usar este módulo, confirme Tenant, Domain e Environment no menu do usuário. O ambiente inicial é Development. As capacidades do módulo, Domain e ambiente se aplicam juntas; Production fica somente leitura sem autorização explícita. Mudar o seletor não transfere artefatos nem publica ou executa seus dados. Consulte ambientes e recuperação e promoção entre ambientes.

GitOps 1.1.2: fixar origem e destino

Baixe o kit GitOps 1.1.2 em uma sessão autorizada de Developer Tools e compare o SHA-256 publicado. Extraia dova_gitops.py, dova-gitops.example.json e README.md no repositório local. Use Python 3.12 ou posterior e chaves pessoais pelas variáveis protegidas indicadas em apiKeyEnv; mantenha os valores fora do Git.

Em dova-gitops.json, source.environment e source.domainId selecionam a origem da exportação. target.environment seleciona o ambiente de destino e bindings.domainId é seu Domain autoritativo. Quando informado, target.domainId deve coincidir com bindings.domainId. O tenant continua sendo o autorizado pela chave pessoal e deve corresponder à configuração; esses campos não trocam de tenant nem concedem acesso.

Ambientes omitidos usam development; o Domain padrão é General (dom_general). Declare o contexto explicitamente ao trabalhar em outro Domain. A versão 1.1.2 fixa o Domain de bindings antes da primeira consulta e preserva o mesmo Tenant, Domain e Environment em leituras, reservas de draft, gravações, publicações e obtenção ou liberação do lease de edição. Não altere o contexto de um cliente que já enviou solicitações.

Exemplo sintético: Finance em Test

Este fragmento complementa o exemplo do kit. Substitua os IDs por Domain e Folder existentes e autorizados; ele não cria Finance nem seus recursos:

{
  "source": {"environment": "development", "domainId": "dom_finance"},
  "target": {"environment": "test", "domainId": "dom_finance"},
  "bindings": {"domainId": "dom_finance", "folderId": "fld_REPLACE_WITH_EXISTING_FINANCE_FOLDER"},
  "statePath": "dova/target-state-finance-test.json"
}

Configure também URL, tenant, nomes das variáveis de chaves e bindings de Connections, workers, perfis ou arquivos necessários ao bundle. No repositório local, valide e revise antes de uma importação autorizada:

python dova_gitops.py --config dova-gitops.json validate
python dova_gitops.py --config dova-gitops.json plan --plan-file dova/plan.json
python dova_gitops.py --config dova-gitops.json apply --plan-file dova/plan.json

validate verifica o bundle local. plan consulta o destino sem gravar. apply cria ou atualiza definições e publica as versões revisadas em Development, Test ou Stage. As versões publicadas da origem e seus rótulos de ambiente permanecem intactos. A autoria direta em Production é rejeitada antes de solicitações com production_authoring_requires_environment_promotion; utilize a promoção governada do Dova para esse destino.

Preservar o estado e resolver contexto incorreto

Use um statePath distinto por destino. O estado associa origin, tenant, Domain e Environment; sua reutilização em outro workspace é rejeitada antes de consultar o Dova. Um estado antigo vazio pode adotar o contexto selecionado. Um estado anterior preenchido sem escopo exige reconciliação manual dos IDs e das versões publicadas. Preserve estado e journal quando o resultado de uma gravação for incerto: não os apague nem altere os campos de contexto para forçar outra importação.

Se uma importação de Finance tentar usar General, revise source.domainId, target.environment e bindings.domainId, instale o kit 1.1.2 e gere outro plano. Os kits históricos 1.1.0 e 1.1.1 preservam seus bytes originais; 1.1.2 é a distribuição com escopo de workspace para Dova 24.