# runner edit

Edita a configuracao de uma aplicacao registrada, como a branch trackeada.

# Sintaxe

runner edit <APP> [OPTIONS]

# Argumentos

# Opcoes

# Exemplos

# Ver configuracao atual

runner edit runner-docs/front --show

Saida:

App Configuration: runner-docs/front
─────────────────────────────
  Path:    /apps/runner-docs
  Branch:  main
  Version: v1.0.0
  Status:  atualizado

# Mudar para branch dev

runner edit runner-docs/front --branch dev

Saida:

Changing branch: main → dev
✓ Git repository found
✓ Branch 'dev' exists on remote
✓ Branch contains .deploy.yml
✓ State updated
✓ Branch 'dev' is now active

Done! Run 'runner fetch' to check for updates.

# Mudar branch sem fazer pull

runner edit runner-docs/front --branch main --pull false

Apenas atualiza o state file, sem executar git checkout/pull.

# Validacoes

O comando realiza tres validacoes antes de alterar a branch:

1. Repositorio ativo - Localiza o clone da app. Desde a v2.60.1 procura em <app>/pull/ (layout v1.2.3+) e, se nao achar, na raiz <app>/ (apps do layout legado)
2. Branch existe - Verifica se a branch existe no remote via git ls-remote, com a mesma credencial do registro que o fetch usa (v2.151.0+). Se o remoto não responde, o erro é não consegui consultar o remoto: <erro>, e não "branch inexistente". Antes da v2.151.0, a consulta ia sem credencial: em repo privado com token registrado, o comando recusava uma branch que existia
3. Contem .deploy.yml - Verifica se a branch contem o arquivo de configuracao

Se qualquer validacao falhar, a alteracao e cancelada:

✗ Error: Branch 'inexistente' does not exist on remote
  Available branches:
    origin/dev
    origin/main
    origin/dist

# Antes da v2.60.1

Em apps do layout pull/ (todo app registrado a partir da v1.2.3) o comando abortava sempre na primeira validacao:

✗ Error: No git repository found at "/data/apps/minha-app"
  This app is not a git repository.

Nao havia como trocar a branch de uma app ja registrada — a saida era unregister + add, que derruba os containers e apaga o diretorio. Se voce ver esse erro, atualize o runner:

runner self-update

A mesma versao corrigiu a troca para uma branch que nao esta no refspec do clone (o pull/ e criado com clone --branch X --depth 1, entao so a branch rastreada e buscada) e o --pull com worktree sujo, que deixava o state numa branch e o clone em outra.

# Fluxo de Uso

Apos alterar a branch, execute fetch para verificar atualizacoes:

# 1. Mudar branch
runner edit runner-docs/front --branch dev

# 2. Verificar atualizacoes
runner fetch runner-docs/front

# 3. Deploy se necessario
runner deploy runner-docs/front

# State File

O comando modifica o arquivo de state em /opt/runner/state/{app}.yml:

app_path: /apps/runner-docs
project: runner-docs
system: front
dist_branch: dev  # <- alterado pelo edit
current_version: v1.0.0
status: atualizado

# Casos de Uso

# Testar versao de desenvolvimento

# Mudar para dev
runner edit meu-app/front --branch dev
runner fetch --deploy

# Depois de testar, voltar para main
runner edit meu-app/front --branch main
runner fetch --deploy

# Deploy de branch especifica

# Deploy de uma feature branch
runner edit meu-app/sys --branch feature/nova-api
runner deploy meu-app/sys

# Rollback para dist
runner edit meu-app/sys --branch dist
runner deploy meu-app/sys

# Disponibilidade

• Adicionado em: v1.2.2-rc.8

# Veja Tambem

• fetch - Buscar atualizacoes
• deploy - Executar deploy
• instances - Gerenciar instancias

# A troca de instancia e recusada com container no ar (v2.80.2+)

--instance recusa a troca quando ha container rodando na instancia atual, nomeando os containers e as duas saidas:

meu-app tem 1 container(s) rodando em 'production':
    - meu_app_production_v2-5-1

Trocar só o state deixaria containers e rota órfãos.

Para migrar preservando o serviço:
    runner switch-instance meu-app --to staging
Para editar mesmo assim, derrube a instância antes:
    runner destroy meu-app -i production

O motivo: a instancia entra no nome do container e no arquivo de rota do Traefik. Trocar so o state produz split-brain — o state aponta para uma coisa, o que roda e outra, e o proximo deploy sobe o segundo conjunto ao lado do primeiro.

A troca passa quando nao ha o que migrar: app recem-registrado (sem instancia configurada), instancia igual a atual, ou nenhum container no ar (nunca deployado, ou instancia ja derrubada).

Para migrar de verdade, use `runner switch-instance`, que faz edit + deploy + destroy sob um unico lock, com rollback.