# ckey simétrica e ckey assimétrica

O Runner suporta dois modos de encriptar os secrets de uma app. Esta página explica a diferença, quando escolher cada um, e como migrar.

Hoje o padrão é a ckey simétrica. Isso vai mudar: a assimétrica passará a ser o padrão em uma versão futura. A simétrica continuará disponível — ela resolve um caso que a assimétrica não resolve (ver Quando ficar na simétrica). O que será deprecado é ela ser o padrão, não ela existir.

# A diferença

# Como o bundle assimétrico se parece

# runner-secrets:v1
# instance:production
# recipient:age1jdfj2nx0lh2kc7us0syqrndn4w40pwquhr6tysrup4g8t988c3cqwuz27r
DATABASE_URL=enc1:hQEMAxk...
SMTP_PASSWORD=enc1:wV4DR2b...

Os nomes ficam visíveis; os valores são selados individualmente. É proposital: dá para revisar num diff de PR o que entrou ou saiu, sem que ninguém leia o conteúdo.

O cabeçalho diz runner-secrets:**v1** — isso é a versão do formato de arquivo, não do modo. Não confunda com o seletor --ckey v2 da linha de comando, que é o que escolhe o modo assimétrico.

O bundle simétrico, em contraste, é um blob binário: não dá para inspecionar nada sem a chave.

# Quando escolher cada uma

# Quando ficar na simétrica

• Você precisa fixar uma chave específica para cifrar e decifrar — porque um processo externo precisa abrir o bundle, ou porque a mesma chave é compartilhada entre servidores ou ferramentas.
• Você tem apps que compartilham a mesma ckey (ver runner ckeys copy).

Esse caso é o motivo de a simétrica continuar existindo mesmo depois que a assimétrica virar padrão: no modo assimétrico a privada é do servidor por construção e não deve sair dele, então não há como "fixar uma chave" para uso externo.

# Quando escolher a assimétrica

• Você quer que escrever um secret não dê o poder de ler os outros — um operador ou automação adiciona valores tendo só a pública.
• Você quer revisar em PR quais chaves entraram ou saíram, sem expor valores.
• Você quer reduzir o raio de exposição: quem obtiver o repositório não decifra nada sem a privada do servidor.

# Como usar

# App nova, em modo assimétrico

runner add --repo owner/app --token ghp_xxx --ckey v2

O Runner gera o par, guarda a privada no state do servidor e grava a pública (recipient) no arquivo de secrets.

# Migrar uma app da simétrica para a assimétrica

runner secrets migrate <app> --instance production

A migração é explícita e nunca acontece sozinha: faz backup, valida antes de publicar, é idempotente e preserva a ckey até a confirmação.

# Como o Runner sabe qual modo usar

Duas fontes participam:

1. O state do servidor — se a app tem uma identity registrada, é assimétrica.
2. O cabeçalho do arquivo — # runner-secrets:v1 na primeira linha indica assimétrica.

No caminho normal as duas concordam e você não precisa pensar nisso.

Se elas divergirem — por exemplo, uma migração interrompida, ou um bundle restaurado de backup de outro modo — o deploy para com erro (scheme_mismatch), citando o que cada fonte diz, o caminho do arquivo inspecionado e como reconciliar. Isso é deliberado: subir um container sem os secrets corretos é pior do que não subir.

A partir da v2.69.0. Antes disso ninguém cruzava as duas fontes: com o state em assimétrica e o bundle em simétrica, o deploy subia verde e o container ficava sem nenhum secret — sem erro, sem aviso, sem log. Se você opera uma versão anterior, essa checagem não existe.

# O que não muda entre os dois modos

• A mkey (master key do servidor) continua igual, protegendo o state.
• A precedência entre .env, .secrets e manifesto não muda — ver Hierarquia de env e secrets.
• O required: do manifesto continua sendo o gate de obrigatoriedade.
• O bundle continua no repositório da app, preservando a recuperação zero-touch.

# Ver também

• Secrets lifecycle — o ciclo completo, das fases de deploy à injeção no container
• Hierarquia de env e secrets — quem vence quem
• Secrets por instância — bundles separados por instância