Declarando dependências

dependencies:
  source:
    type: git-repository
    description: Repositório a analisar.
    mutable: false
  gcpCredential:
    type: secret/gcp-service-account
    required: true

O contrato declara a semântica — o que é. A forma de entrega vem do tipo, e a implementação decide onde aparece.

Tipos do núcleo

Tipo	Forma	Privilégio
directory	diretório	baixo
git-repository	diretório	baixo
secret	string	médio
secret/git-token	string	médio
secret/npm-token	string	médio
secret/registry-credentials	arquivo	médio
secret/gcp-service-account	arquivo	alto
secret/aws-credentials	arquivo	alto
secret/coolify-token	string	alto
engine/docker	socket	crítico
network	capability	médio

O que cada coluna decide

Três coisas, e elas são ortogonais — é por isso que onze tipos cobrem quase tudo.

Forma é como o valor atravessa a fronteira do container, e o runtime faz trabalho diferente para cada uma:

Forma	O que o worker recebe
directory	um diretório montado, no mountPath que a implementação declara
file	um arquivo só, montado como secret quando o valor é conteúdo em vez de caminho
string	uma variável de ambiente, marcada como secreta quando o tipo é sensitive
socket	um socket Unix ligado ao container
capability	nada no filesystem — a concessão é a ausência de restrição

Privilégio é quanto custa conceder, e é o que o gate de consent lê. Abaixo de medium a dependência é concedida sem perguntar, porque não há o que decidir em ler um diretório. mutable: true sobe um degrau: escrever no diretório de alguém custa mais que ler.

extends é herança. secret/git-token é um secret, e ganha o tratamento de um — redigido em log, nunca gravado no disco do host.

Por que o vocabulário é fechado

Tipo desconhecido é erro dos dois lados: a CLI recusa resolver, e o portal recusa publicar.

Isso é deliberado. Esta é a única parte do spec que a CLI e o portal precisam interpretar de forma idêntica. Se viesse de banco ou de um arquivo do seu projeto, dois portais teriam vocabulários diferentes e o mesmo oren.yaml significaria coisas diferentes em cada um.

Admitir o desconhecido também obrigaria a assumir um privilégio para ele — e privilégio assumido para baixo é exatamente o que faz o gate de consent ficar calado sobre algo caro.

Pedindo um tipo novo

Tipo novo é mudança do spec, com release — não configuração. Antes de pedir, veja se você precisa mesmo:

Provavelmente não. Uma credencial de outra nuvem é form: file, privilege: high, que o secret/gcp-service-account já descreve mecanicamente. O que um nome novo compra é significado para quem lê o contrato, e essa é uma razão legítima — mas é a única.

Provavelmente sim quando a forma é nova: algo que não é diretório, nem arquivo, nem variável, nem socket, nem capacidade pura. Isso ainda não aconteceu.

O que uma proposta precisa ter: o nome, a forma, o privilégio e — a parte que importa — por que esse privilégio. O engine/docker é critical porque o socket do Docker é root na máquina; se você não consegue escrever uma frase dessas, o privilégio é chute, e privilégio chutado é pior que tipo nenhum.

network não é enforçado

O motor de execução dá rede a todo container e não expõe controle por execução. Declarar network documenta a intenção, mas não impede um worker que a omita de acessar a internet. É a única lacuna do núcleo.

Cardinalidade

A chave é a identidade; type é um atributo. Declarar várias do mesmo tipo é normal:

dependencies:
  source:     { type: git-repository, mutable: true }
  artifacts:  { type: directory,      mutable: true }
  gcpProd:    { type: secret/gcp-service-account }
  gcpStaging: { type: secret/gcp-service-account }

mutable

Sem ele, o que o worker escreve é descartado com o container. Com ele, a alteração volta para o host e os steps seguintes a enxergam.

Precisa ser explícito: é a diferença entre uma task que lê o repositório e uma que reescreve o working dir de quem executou. E sobe o privilégio um degrau.

Na implementação

O contrato nomeia; a implementação posiciona:

dependencies:
  source:
    mountPath: /source
  gcpCredential:
    mountPath: /secrets/gcp-key.json
  gitToken:
    env: GIT_TOKEN        # forma string chega por variável

Uma chave que não existe no contrato é dependência adicional da implementação, e precisa declarar type. É o delta que o catálogo compara.