# Histórico de configuração

Toda mudança de configuração de um serviço vira uma **versão imutável**: ajustes (porta, healthcheck, recursos, build), variáveis próprias, variáveis compartilhadas que o afetam, domínios, política de domínio e volume. Cada versão guarda quem mudou, quando, o motivo e um resumo do que mudou em relação à anterior (variáveis só por nome, nunca por valor).

## Painel

No serviço, abra a aba **Histórico de configuração**. A lista mostra as versões da mais nova para a mais antiga, e **Restaurar esta versão** pede confirmação de identidade ([Confirmação de identidade](/seguranca/confirmacao-de-identidade/)).

## Rotas

| Rota | Escopo | O que faz |
|---|---|---|
| `GET /v1/projects/{p}/services/{s}/config-versions` | `projects:read` | Lista as versões (mais nova primeiro), paginada por cursor. |
| `GET /v1/projects/{p}/services/{s}/config-versions/{v}` | `projects:read` | Devolve a versão com o config normalizado. |
| `POST /v1/projects/{p}/services/{s}/config-versions/{v}/restore` | `projects:write` | Restaura a versão `{v}`. |

```bash
H="Authorization: Bearer $NEBULAR_TOKEN"
P=$(curl -sS -X POST "$NEBULAR_API/v1/projects" -H "$H" -H "Content-Type: application/json" \
  -d "{\"name\": \"hist-$(date +%s)-$RANDOM\"}" | jq -r .id)
S=$(curl -sS "$NEBULAR_API/v1/projects/$P/services" -H "$H" | jq -r '.items[0].id')
curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/config-versions" -H "$H"
```
```json
{"items": [{"version": 1, "service_id": "01jb7k4a5q8r7t2v4w6x8y0a2c", "parent_version": 0, "created_at": "2026-10-16T14:03:11Z", "actor": "01jb7k3a5q8r7t2v4w6x8y0a1b", "reason": "service.create", "summary": []}], "next_cursor": null, "has_more": false}
```

Versão que não existe e cursor inválido respondem com erro claro, e esses dois casos você pode executar:

```bash
H="Authorization: Bearer $NEBULAR_TOKEN"
P=$(curl -sS -X POST "$NEBULAR_API/v1/projects" -H "$H" -H "Content-Type: application/json" \
  -d "{\"name\": \"hist-$(date +%s)-$RANDOM\"}" | jq -r .id)
S=$(curl -sS "$NEBULAR_API/v1/projects/$P/services" -H "$H" | jq -r '.items[0].id')
curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/config-versions/999" -H "$H"
```
```json
{"error": "not_found", "message": "Recurso não encontrado."}
```

```bash
H="Authorization: Bearer $NEBULAR_TOKEN"
P=$(curl -sS -X POST "$NEBULAR_API/v1/projects" -H "$H" -H "Content-Type: application/json" \
  -d "{\"name\": \"hist-$(date +%s)-$RANDOM\"}" | jq -r .id)
S=$(curl -sS "$NEBULAR_API/v1/projects/$P/services" -H "$H" | jq -r '.items[0].id')
curl -sS "$NEBULAR_API/v1/projects/$P/services/$S/config-versions?cursor=abc" -H "$H"
```
```json
{"error": "invalid_request", "message": "Cursor inválido."}
```

## Segredos nunca aparecem

Ao consultar uma versão, cada variável própria vem com `value: null` e `masked: true`. O valor continua cifrado no servidor e só é reaplicado pelo restore, sem passar em claro.

## Restaurar

O restore **nunca reescreve o histórico**: ele cria a versão **N+1 igual à `{v}`** e marca o serviço para redeploy (`redeploy_required: true`). Faça um deploy em seguida para a configuração valer.

```bash
curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/config-versions/2/restore" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" \
  -H "Idempotency-Key: restore-config-2"
```
```json
{"version": {"version": 4, "parent_version": 2, "reason": "config_version.restore", "summary": ["port: 8080 -> 3000"]}, "redeploy_required": true}
```

**Restaura:** porta, healthcheck, comandos, recursos, source/build, auto deploy, política de domínio e as variáveis próprias com o valor original.

**Não restaura:** nome, slug e visibilidade, os **dados** do volume, os domínios (exigem DNS) e as variáveis compartilhadas do projeto.

Com token, o restore também exige a permissão `destroy` da política do token ([Tokens e escopos](/seguranca/tokens-e-escopos/)).

## Retenção de 10 deploys para o rollback

A plataforma mantém o artefato dos **10 deploys** mais recentes de cada serviço (o ativo mais nove destinos de rollback; antes eram 2), e o [rollback](/operacao/rollback/) volta a qualquer um deles sem rebuild. O histórico de configuração complementa o rollback: o rollback volta o **código**, e o restore de versão volta a **configuração**. Nenhum dos dois desfaz dados de banco ou de volume.
