# tunnelhub.yml

`tunnelhub.yml` é o manifesto local usado pelos fluxos de scaffold, build e deploy de projetos TunnelHub.

Em geral, ele responde três perguntas:

* qual recurso esse projeto representa;
* como o artefato deve ser gerado ou publicado;
* qual configuração de runtime acompanha a automação.

## Fonte de verdade pública

Use esta página como referência prática e o schema publicado no SchemaStore como referência estrutural:

* `https://json.schemastore.org/tunnelhub.json`

Se você usa editor com suporte a JSON Schema em YAML, vale associar esse schema ao arquivo para ganhar validação e autocomplete.

## Exemplo mínimo

```yaml
service:
  type: automation
  uuid: 11111111-2222-3333-4444-555555555555

configuration:
  runtimeEngine: LAMBDA
  entrypoint: index.handler
  runtime: nodejs22.x
  memorySize: 512
  timeout: 30

package:
  artifact: dist/artifact.zip
```

## Exemplo com campos opcionais

```yaml
service:
  type: automation
  uuid: 11111111-2222-3333-4444-555555555555
  region: us-east-1

configuration:
  runtimeEngine: LAMBDA
  entrypoint: index.handler
  runtime: nodejs22.x
  memorySize: 1024
  timeout: 120
  lambdaLayers:
    - arn:aws:lambda:us-east-1:123456789012:layer:shared-lib:1
  environmentVariables:
    LOG_LEVEL: info
  vpcConfig:
    subnetIds:
      - subnet-aaaa1111
    securityGroupIds:
      - sg-bbbb2222
    assignPublicIp: false

package:
  artifact: dist/artifact.zip
```

## Bloco `service`

Esse bloco identifica o tipo de recurso e o vínculo com a plataforma.

Campos mais importantes:

* `type`: normalmente `automation` no fluxo público atual;
* `uuid`: UUID da automação no TunnelHub;
* `region`: opcional em cenários que precisam declarar região explicitamente.

Durante `create-automation`, a CLI escreve `service.uuid` automaticamente no template baixado.

## Bloco `configuration`

Esse bloco orienta o runtime do projeto.

Campos mais comuns:

* `runtimeEngine`: como `LAMBDA` ou `ECS_FARGATE`;
* `entrypoint`: função ou arquivo de entrada esperado pelo bundle;
* `runtime`: runtime Node.js alvo;
* `memorySize`: memória esperada;
* `timeout`: tempo máximo de execução.

Também podem aparecer campos opcionais, como:

* `lambdaLayers`;
* `environmentVariables`;
* `vpcConfig`.

O schema publicado é a melhor referência para validar combinações e tipos desses campos.

## Bloco `package`

Esse bloco é especialmente importante para o deploy da CLI.

Campo crítico:

* `artifact`: caminho do artefato ZIP que será enviado para a plataforma.

Sem esse valor, `deploy-automation` não consegue concluir o fluxo de publicação.

## Quem usa cada parte do arquivo

* **CLI scaffold**: preenche `service.uuid`.
* **CLI deploy**: lê `service.uuid` e `package.artifact`.
* **SDK build tooling**: usa `configuration` para empacotar o projeto corretamente.

## O que é obrigatório na prática

Para o fluxo público atual de automações, o contrato mínimo é:

* `service.type`;
* `service.uuid`;
* `configuration.runtimeEngine`;
* `configuration.entrypoint`;
* `configuration.runtime`;
* `configuration.memorySize`;
* `package.artifact`.

## Erros comuns

* **`tunnelhub.yml` ausente**: execute o deploy na raiz do projeto correto.
* **`service.uuid` ausente**: recrie o projeto com `create-automation` ou informe `--automation` no deploy.
* **`package.artifact` ausente**: configure o caminho do ZIP antes do deploy.
* **artefato em caminho errado**: confirme se o arquivo realmente existe no caminho configurado.
* **bundle incompleto**: garanta que o artefato gerado contenha o que o runtime precisa.

## Relação com o fluxo de trabalho

O ciclo mais comum é:

1. `create-automation` gera o projeto e grava `service.uuid`;
2. o projeto gera o artefato configurado;
3. `deploy-automation` lê `tunnelhub.yml` e publica a nova versão.

Consulte também [Comandos e referência](https://docs.tunnelhub.io/cli/commands) e [Criando sua primeira automação](https://docs.tunnelhub.io/primeiros-passos/creating-your-first-automation).