Criando sua primeira automação

Tempo estimado: 20 a 30 minutos

Este guia mostra um fluxo atual de onboarding para criar, desenvolver, publicar e acompanhar uma automação no TunnelHub.

Antes de começar

Você vai precisar de:

• uma conta TunnelHub com acesso a pelo menos um ambiente;

• Node.js 22+ na sua máquina;

• npm ou pnpm;

• permissão para criar pacote e automação no ambiente desejado.

1. Instale a CLI

npm install -g @tunnelhub/cli

Depois da instalação, você pode usar tunnelhub ou o alias curto th.

2. Faça login

O fluxo recomendado usa autenticação via navegador:

tunnelhub login

Durante o login, a CLI solicita o Tenant ID e abre a autenticação no frontend do TunnelHub. Em casos específicos, existe fallback por usuário e senha:

tunnelhub login --password

Para validar a sessão atual:

tunnelhub login-check

3. Descubra seus ambientes

Liste os ambientes disponíveis e identifique o nome ou UUID do ambiente onde você quer trabalhar:

tunnelhub list-environments

Os comandos da CLI aceitam o nome do ambiente ou o UUID. Internamente, a CLI resolve esse valor para o identificador correto.

4. Crie um pacote

Pacotes organizam recursos relacionados, como automações, sistemas e tabelas de conversão.

tunnelhub create-package --env DEV

O comando é interativo e solicita nome e descrição.

5. Crie uma automação

Agora crie a automação com bootstrap local de um template oficial:

tunnelhub create-automation --env DEV

Durante o fluxo, você escolhe:

• o tipo base da automação;

• o pacote;

• nome e descrição;

• período de retenção de logs;

• URL do repositório, se desejar informar.

Os templates atuais cobrem quatro modelos:

• No delta

• No delta batch

• Delta

• Delta batch

Ao final, a CLI:

• cria a automação no TunnelHub;

• baixa um template do GitHub;

• extrai o projeto para uma nova pasta local;

• grava o service.uuid no tunnelhub.yml.

6. Entenda a estrutura do projeto

O projeto gerado normalmente inclui:

• código da automação em TypeScript;

• tunnelhub.yml com identificação do serviço e configuração de build/deploy;

• scripts de build;

• testes básicos para execução local.

O desenvolvimento atual deve ser feito com o @tunnelhub/sdk, usando um dos fluxos públicos:

• NoDeltaIntegrationFlow

• NoDeltaBatchIntegrationFlow

• DeltaIntegrationFlow

• BatchDeltaIntegrationFlow

Se você usa uma plataforma de agentes no desenvolvimento, também vale instalar o skill público tunnelhub-sdk, que acelera dúvidas e implementação do SDK:

npx skills add tunnelhub/agent-skills --skill tunnelhub-sdk -a opencode

7. Implemente a integração

Em alto nível, sua automação precisa:

• carregar dados da origem;

• opcionalmente comparar com o destino, nos fluxos com delta;

• executar insert, update, delete ou send;

• definir os metadados que aparecerão no monitoramento.

Exemplo simplificado de metadados:

defineMetadata(): Metadata<MyItem>[] {
  return [
    { fieldName: 'id', fieldLabel: 'ID', fieldType: 'TEXT' },
    { fieldName: 'status', fieldLabel: 'Status do item', fieldType: 'TEXT' },
    { fieldName: 'updatedAt', fieldLabel: 'Atualizado em', fieldType: 'DATETIME' },
  ];
}

Os metadados controlam como os itens aparecem nos logs de processamento.

8. Use sistemas e parâmetros

Evite valores fixos no código. O padrão atual é configurar credenciais e variáveis de negócio no produto:

• Sistemas para conexões com serviços externos.

• Parâmetros para valores variáveis da automação.

• Tabelas de conversão para de/para.

• Sequences para geração de identificadores.

No SDK, esses dados são recebidos no ProcessorPayload e acessados pelas classes utilitárias exportadas publicamente.

Se você quiser aprofundar esse contrato, consulte Data Stores, Sistemas e tunnelhub.yml.

9. Teste localmente

Os templates incluem testes iniciais. Para testes locais, habilite o modo de teste do SDK quando fizer sentido:

import { SDK } from '@tunnelhub/sdk';

beforeAll(() => {
  SDK.testMode = true;
});

Esse modo evita efeitos colaterais da execução real da plataforma durante os testes.

10. Gere o artefato

Antes do deploy, gere o bundle definido no seu projeto. O contrato importante é:

• existir um tunnelhub.yml na raiz do bundle;

• o campo package.artifact apontar para o zip ou artefato publicado;

• o projeto estar pronto para o ambiente de execução configurado.

11. Faça o deploy

Com o artefato pronto, publique uma nova versão:

tunnelhub deploy-automation --env DEV --message "primeiro deploy"

Opcionalmente, você pode informar --automation e --publish.

O deploy:

• valida seu tunnelhub.yml;

• faz upload do artefato para S3 por URL assinada;

• solicita a criação do deploy na plataforma.

12. Configure o disparo

Na tela da automação, você pode configurar os gatilhos suportados hoje:

• webhook;

• agendamento;

• inbound email.

Dependendo do tipo escolhido, a automação pode ser executada manualmente, por URL ou por agenda.

13. Acompanhe a execução

Depois do deploy, use a interface web em Automations > Monitoring para acompanhar:

• status geral da execução;

• volume processado;

• logs de processamento por item;

• traces técnicos;

• downloads e ações operacionais quando disponíveis.

Próximos passos

• Leia Automações para entender gatilhos, parâmetros e deploys.

• Leia SDK para escolher o fluxo correto.

• Leia Monitoramento para investigar falhas e execuções.

• Leia tunnelhub.yml para entender o contrato de build e deploy.