Como usar o voar

1. Abra a página do app no GitHub e escolha a organização. Contas pessoais ainda não funcionam.

   Instalar o voar no GitHub

2. Escolha os repositórios que podem usar o voar: todos ou só alguns. Dá para mudar depois, nas configurações do app no GitHub.

3. No workflow, troque o runs-on do job por um label do voar:

   name: CIon: push jobs:  test:    runs-on: voar-2vcpu-ubuntu-2404    steps:      - uses: actions/checkout@v7      - run: npm ci      - run: npm test

   Copiar

4. Faça um push. Depois, entre no painel com a sua conta do GitHub: a página de jobs mostra cada job, a máquina, quanto tempo levou e quanto custou.

   Abrir o painel

O label diz ao voar qual máquina o job quer. Cada tamanho aceita a forma completa e as formas curtas.

• Use um label do voar por job.
• Junto dele, você pode listar self-hosted, linux e x64. Qualquer outro label no mesmo runs-on deixa o job esperando.
• Maiúsculas e minúsculas tanto faz: o GitHub compara labels sem diferenciar.

Ubuntu 24.04 em x64, com sudo. Já vem instalado:

• Docker, com Compose e Buildx
• sudo e git
• Node 22 e 24
• Bun
• Python 3
• GitHub CLI (gh)
• AWS CLI

Não é a imagem completa dos runners do GitHub. O que faltar, instale no próprio job:

- run: sudo apt-get update && sudo apt-get install -y postgresql-client

Cada job começa numa máquina nova. Nada do job anterior fica nela.

O cache guarda arquivos para o próximo job não precisar baixar ou gerar tudo de novo. O voar usa o cache do próprio GitHub. Se o workflow já usa actions/cache, mantenha esses passos.

Para npm, adicione estes passos depois de actions/checkout. O repositório precisa ter um package-lock.json:

- uses: actions/setup-node@v7  with:    node-version: '24'    cache: npm- run: npm ci

O setup-node reaproveita os pacotes baixados. Ele não guarda a pasta node_modules, então mantenha o npm ci.

Camadas do Docker

Para reaproveitar camadas entre builds, use o cache gha do Buildx. Depois do checkout, num repositório com Dockerfile:

- uses: docker/setup-buildx-action@v4- uses: docker/build-push-action@v7  with:    push: false    cache-from: type=gha,version=2    cache-to: type=gha,version=2,mode=max

Os arquivos de cache ficam no GitHub, não num serviço do voar em São Paulo. Os limites, o prazo de exclusão e a cobrança de armazenamento seguem as regras do GitHub para o repositório.

O primeiro job cria o cache. Se aparecer Cache not found, deixe o job terminar e rode de novo com a mesma chave. Confira também o caminho e o arquivo de dependências usado na chave. Não guarde senhas ou tokens no cache.

• Um job roda por até 6 horas. Nessa marca, a máquina se desliga.
• Só organizações. Contas pessoais ainda não funcionam.
• Só Linux x64 (Ubuntu 24.04), em São Paulo (AWS sa-east-1).
• Até 2 jobs ao mesmo tempo antes da primeira compra, e 10 depois. Para mais, escreva para [email protected].

Repositórios públicos

Por padrão, só repositórios privados usam o voar: o grupo de runners padrão do GitHub não atende os públicos. Para liberar, um admin da organização abre Settings > Actions > Runner groups, entra no grupo Default e marca Allow public repositories.

Num repositório público, um pull request de fora do time pode fazer um job rodar no voar, e o custo sai do seu saldo. Antes de liberar, confira nas configurações de Actions do GitHub quem precisa de aprovação para rodar workflows de forks.

O app do voar pede só o que precisa para criar runners e saber dos jobs. Ele não pede acesso ao conteúdo dos repositórios.

• Self-hosted runners (leitura e escrita), na organização: para criar o runner de cada job e removê-lo no fim.
• Members (leitura): para saber quem é admin da organização.
• Actions (leitura): para receber os eventos dos jobs.
• Metadata (leitura): o GitHub pede essa junto com as outras.
• O e-mail de quem entra no painel: para os avisos da conta, como o de saldo baixo.

• Cada job é cobrado sozinho, arredondado para cima no minuto inteiro, como o GitHub faz. Um job de 3 min e 10 s conta 4 minutos.
• As máquinas maiores contam mais minutos por minuto: na de 4 vCPU, cada minuto conta 2, e na de 16 vCPU, conta 8.
• Toda organização ganha 3.000 minutos grátis por mês, contados na máquina de 2 vCPU. Eles voltam à meia-noite do dia 1º, no horário de Brasília.
• Depois deles, cada job desconta do saldo. Coloque crédito pelo painel, em pacotes a partir de R$ 50. Não há plano nem assinatura.
• A moeda fica fixa no primeiro pagamento da organização: reais, dólares ou euros.
• Sem saldo e sem minutos grátis, os jobs esperam na fila do GitHub até você colocar crédito. O GitHub cancela o job que espera mais de 24 horas.
• Owners e admins da organização colocam crédito e mudam as configurações. Membros veem os jobs e o saldo.

Ver os preços

Owners e admins criam chaves de API da organização (voar_...) nas Configurações do painel. Cada organização pode ter até 10 chaves ativas, todas somente leitura.

curl -H "Authorization: Bearer voar_..." https://api.voar.dev/v1/account

Endpoints e ferramentas

• GET /v1/account (ferramenta MCP get_account, permissão account:read): resumo da organização, saldo, unidades grátis do mês e quantas já foram usadas, limite de concorrência, máquinas ativas e jobs na fila.
• GET /v1/jobs (ferramenta MCP list_jobs, permissão jobs:read): últimos jobs da organização (limit de 1 a 100 e before em ISO 8601), com tamanho da máquina, duração, custo e motivo caso algum job não tenha partido.
• GET /v1/usage (ferramenta MCP get_usage, permissão usage:read): jobs concluídos, unidades cobradas e custo pago no mês (month como AAAA-MM em America/Sao_Paulo), dia a dia. O costMicros está na moeda que o get_account informa.
• GET /v1/openapi.json (ou ?lang=pt-BR): especificação OpenAPI 3.1 pública.

Uma unidade é um minuto na máquina de 2 vCPU. As máquinas de 4, 8 e 16 vCPU contam 2, 4 e 8 unidades por minuto. Os campos de dinheiro terminam em Micros: um milhão de micros é 1,00 da moeda.

Conectar pelo MCP

Aponte o Claude, o ChatGPT ou o Codex para https://api.voar.dev/mcp. O aplicativo abre a tela de autorização do voar para você escolher a organização, e recebe uma chave voar_ própria.

Em um agente de terminal sem navegador local, inicie o login por código (RFC 8628) e aprove em https://app.voar.dev/device:

curl -X POST https://api.voar.dev/oauth/device_authorization \  -d "client_id=voar-agent"

Quando você conecta um aplicativo de IA ao voar por OAuth ou código de terminal, ele recebe uma chave de API somente leitura vinculada à organização que você escolheu.

• O aplicativo só lê o resumo da organização (account:read), a lista de jobs (jobs:read) e o consumo mensal (usage:read). Ele não altera limites, não compra pacotes de crédito e não cria outras chaves.
• O app do voar no GitHub não tem permissão para ler o conteúdo dos seus repositórios, e o que a API devolve não traz código-fonte, logs de job nem secrets de workflow.
• Seus jobs rodam nas máquinas do voar. Enquanto um job roda, a máquina guarda o código e os secrets que o workflow usa, como em qualquer runner. Quando o job termina, a máquina e o disco dela são apagados.
• Os dados do cartão vão para o Stripe, não para o voar.
• Cada aplicativo conectado aparece na lista de chaves de API nas Configurações da organização, onde qualquer owner ou admin pode trocar ou revogar a chave na hora.
• Se a pessoa que autorizou o aplicativo sair da organização no GitHub ou deixar de ser owner ou admin, a chave para de funcionar imediatamente.

Troque o runs-on de volta para ubuntu-latest, ou para o runner do GitHub que você usava. Nada mais muda.

Para trocar todos os workflows de uma vez, leia o runner de uma variável da organização:

runs-on: ${{ vars.CI_RUNNER || 'ubuntu-24.04' }}

Crie a variável CI_RUNNER na organização (Settings > Secrets and variables > Actions > Variables) com o valor voar-2vcpu-ubuntu-2404. Sem a variável, os jobs rodam no ubuntu-24.04 do GitHub.

O job ficou em Queued

Abra a página de jobs do painel. Ela diz por que cada job parado ainda não ganhou máquina. Os motivos possíveis:

• O label está escrito errado, como voar-3vcpu. Confira a tabela de labels.
• O runs-on tem outro label além do voar. Só self-hosted, linux e x64 podem ir junto.
• Acabaram o saldo e os minutos grátis do mês. Coloque crédito e o job começa.
• A organização chegou ao máximo de jobs ao mesmo tempo. O job espera a vez.
• O voar não conseguiu ligar a máquina. Rode o job de novo. Se acontecer outra vez, escreva para [email protected].
• A instalação do app foi removida ou suspensa no GitHub. Instale o voar de novo na organização.

Se o repositório for público, confira também se o grupo de runners libera repositórios públicos.

O job nem aparece no painel

O app não está instalado nesse repositório. Nas configurações do app no GitHub, inclua o repositório e rode o job de novo.