blueprints baseados em Git

Visão geral

Blueprints baseados em Git permitem armazenar a configuração do seu ambiente diretamente no repositório como um arquivo .devin/blueprint.yaml. Você sincroniza o arquivo com o Devin pela API ou pela UI e, em seguida, aciona um build do snapshot para aplicar as alterações. Isso dá a você o mesmo workflow usado no código da aplicação: editar na IDE, abrir uma pull request, receber uma revisão, fazer merge e depois sincronizar + executar o build por uma etapa de CI ou pela UI.

Abordagem	Onde o blueprint fica	Como você o edita	Como as alterações são aplicadas
Banco de dados (padrão)	UI de configurações do Devin	Edite no navegador	Salvo imediatamente ao clicar
Baseado em Git	`.devin/blueprint.yaml` no seu repo	Edite na sua IDE, faça merge de uma PR	Chame a API de sincronização (ou clique em Sync na UI) e depois acione um build

Blueprints baseados em Git usam o mesmo formato YAML do editor da UI. Consulte a Referência de blueprints para ver a especificação completa dos campos.

Primeiros passos

1. Crie o arquivo blueprint

Adicione um arquivo .devin/blueprint.yaml à raiz do seu repositório:

my-repo/
  .devin/
    blueprint.yaml
  src/
  package.json
  ...

O arquivo usa o mesmo formato YAML do editor da UI:

initialize:
  - name: Install Node.js 22
    uses: github.com/actions/setup-node@v4
    with:
      node-version: "22"

maintenance:
  - name: Install dependencies
    run: npm install

knowledge:
  - name: lint
    contents: npm run lint
  - name: test
    contents: npm test

2. Faça push para a branch padrão

Faça commit e dê push de .devin/blueprint.yaml para a branch padrão do seu repositório (geralmente main ou master). Se o repositório já estiver conectado ao ambiente do Devin, você precisará acionar uma sincronização (via API ou pelo botão Sync na UI) para que o Devin detecte o arquivo. Se você estiver adicionando o repo pela primeira vez, a descoberta inicial lê o blueprint do Git.

3. Verifique na UI

Acesse Configurações > Ambiente > Blueprints e clique no repositório. O editor exibe o conteúdo do blueprint do Git, e o indicador de origem mostra o nome do provedor (por exemplo, “GitHub”) com o SHA do commit sincronizado.

Como a sincronização funciona

A sincronização é o processo de obter .devin/blueprint.yaml a partir do HEAD da branch padrão do repositório e atualizar as versões de blueprint armazenadas no Devin. A sincronização não acontece automaticamente a cada push — você precisa acioná-la explicitamente:

Sincronização via API — Chame o endpoint de sincronização v3 (veja Sincronização via API abaixo). Esta é a abordagem recomendada para pipelines de CI/CD.
Sincronização via UI — Clique no botão Sync no editor de blueprint. Isso também aciona um build do snapshot se o conteúdo tiver mudado.
Ao adicionar um repositório ao ambiente — Se .devin/blueprint.yaml existir na branch padrão, o blueprint será obtido automaticamente do Git durante a descoberta inicial.

A sincronização é idempotente: se o conteúdo do arquivo não mudou desde a última sincronização, nenhuma nova versão será criada.

Sync vs. build

Sync e build são operações separadas:

Sync busca a versão mais recente de .devin/blueprint.yaml no Git e armazena uma nova versão do blueprint.
Build cria uma nova imagem de snapshot a partir das versões atuais dos blueprints.

O botão de sync da UI executa as duas etapas em uma única ação. A API v3 separa essas operações para que você tenha controle total — chame sync primeiro e, em seguida, acione um build.

Sincronização via a API

A forma recomendada de manter os blueprints sincronizados é fazer uma chamada à API v3 após o merge das alterações em .devin/blueprint.yaml. Isso normalmente é feito por meio de um pipeline de CI/CD (por exemplo, uma etapa pós-merge do GitHub Actions).

Fluxo completo

Etapa 1: Sincronize o blueprint

Obtenha a versão mais recente de .devin/blueprint.yaml da branch padrão:

curl -X POST https://api.devin.ai/v3/organizations/{org_id}/snapshot-setup/sync \
  -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repo_name": "owner/repo"}'

Resposta:

{"repo_name": "owner/repo"}

O campo repo_name aceita owner/repo para o GitHub ou uma URL completa do provedor para outros hosts (por exemplo, https://gitlab.com/org/repo).

Etapa 2: Acione um build

Após a sincronização, acione um build do snapshot para aplicar o novo blueprint:

curl -X POST https://api.devin.ai/v3/organizations/{org_id}/snapshot-setup/builds \
  -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Resposta:

{
  "build_id": "sbj-abc123",
  "status": "running",
  "trigger": "api",
  "created_at": 1718000000,
  "updated_at": 1718000000
}

Etapa 3: Consultar o status da build (opcional)

Se você quiser esperar a conclusão da build na CI:

curl https://api.devin.ai/v3/organizations/{org_id}/snapshot-setup/builds/{build_id} \
  -H "Authorization: Bearer $DEVIN_API_TOKEN"

O campo status passa pelos seguintes estados: running → succeeded ou failed.

Sincronização em toda a Enterprise

Para clientes Enterprise com várias organizações compartilhando o mesmo repositório, há um endpoint em nível de Enterprise que sincroniza todas as orgs conectadas ao repositório:

curl -X POST https://api.devin.ai/v3/enterprise/snapshot-setup/sync \
  -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repo_name": "owner/repo"}'

A resposta inclui o número de orgs sincronizadas:

{"repo_name": "owner/repo", "org_count": 3}

Exemplo: workflow do GitHub Actions

Automatize a sincronização + o build a cada push para a branch padrão que alterar o arquivo de blueprint:

# .github/workflows/sync-blueprint.yml
name: Sync Devin Blueprint

on:
  push:
    branches: [main]
    paths:
      - '.devin/blueprint.yaml'

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - name: Sync blueprint
        run: |
          curl -sf -X POST \
            "https://api.devin.ai/v3/organizations/${{ secrets.DEVIN_ORG_ID }}/snapshot-setup/sync" \
            -H "Authorization: Bearer ${{ secrets.DEVIN_API_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d '{"repo_name": "${{ github.repository }}"}'

      - name: Trigger build
        run: |
          curl -sf -X POST \
            "https://api.devin.ai/v3/organizations/${{ secrets.DEVIN_ORG_ID }}/snapshot-setup/builds" \
            -H "Authorization: Bearer ${{ secrets.DEVIN_API_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d '{}'

Você precisa de um usuário de serviço ou de um token de acesso pessoal com permissão de escrita no ambiente. Armazene o token como DEVIN_API_TOKEN e o ID da organização como DEVIN_ORG_ID nos segredos do repositório.

Editando blueprints baseados em Git

Quando um blueprint está baseado em Git, o editor na UI fica somente leitura para salvamentos diretos. Em vez disso, você tem duas opções para fazer alterações:

Criar uma PR pelo editor

Abra o editor de blueprint em Configurações > Ambiente > Blueprints
Edite o YAML no editor
Clique em Criar PR
O Devin abre uma pull request (PR) no seu repositório que atualiza .devin/blueprint.yaml
Revise, aprove e faça o merge da PR
A próxima sincronização reconhece a alteração e aciona uma build

Isso é útil para fazer edições rápidas sem sair da UI do Devin.

Edite diretamente no seu repositório

Edite .devin/blueprint.yaml no seu IDE ou no seu provedor Git
Faça commit e push para a branch padrão (ou abra uma PR e faça o merge)
Acione a sincronização pela API ou clique em Sync na UI

Este é o fluxo de trabalho padrão para equipes que gerenciam infraestrutura como código. Combine isso com uma etapa de CI para automatizar a sincronização (veja Sincronizar via a API).

Sugestões do Devin

Quando o Devin propõe uma alteração de blueprint durante uma sessão (e.g., após analisar seu projeto), a sugestão é aplicada com a abertura de uma PR para .devin/blueprint.yaml, em vez de ser salva diretamente no banco de dados. Você revisa e faz o merge da PR como qualquer outra alteração de código.

Monorepos e workspaces

Para monorepos com vários pacotes, você pode usar a diretiva includes para definir blueprints separados para cada workspace. Cada workspace tem seu próprio arquivo .devin/blueprint.yaml em seu subdiretório.

Root blueprint com includes

O arquivo .devin/blueprint.yaml na raiz declara quais workspaces têm seus próprios blueprints:

# my-repo/.devin/blueprint.yaml
includes:
  - packages/frontend
  - packages/backend

initialize: |
  npm install -g pnpm

maintenance: |
  pnpm install

Blueprints de workspace

Cada workspace incluído tem seu próprio .devin/blueprint.yaml:

# my-repo/packages/frontend/.devin/blueprint.yaml
maintenance: |
  pnpm build

knowledge:
  - name: lint
    contents: pnpm lint
  - name: test
    contents: pnpm test

# my-repo/packages/backend/.devin/blueprint.yaml
maintenance: |
  pip install -r requirements.txt

knowledge:
  - name: lint
    contents: ruff check .
  - name: test
    contents: pytest

Regras de inclusão

Cada entrada de includes é um caminho de subdiretório (e.g., packages/frontend). Devin procura .devin/blueprint.yaml dentro desse diretório.
Você também pode usar o caminho completo: packages/frontend/.devin/blueprint.yaml.
Somente o root blueprint pode conter includes. Inclusões aninhadas (um blueprint incluído que também declara includes) não são permitidas.
Cada caminho de workspace pode aparecer apenas uma vez em includes.
Se um arquivo incluído estiver ausente do repositório, esse workspace será tratado como removido, e seu blueprint será removido.

Alternar entre os modos Git e de banco de dados

Mudar para o Git

Se você já tem um blueprint gerenciado no banco de dados e quer mudar para o Git:

Crie .devin/blueprint.yaml no seu repositório com o conteúdo desejado
Faça push para a branch padrão
No editor de blueprint, clique no menu suspenso de origem e selecione seu provedor Git (por exemplo, “GitHub”)
O Devin sincroniza o arquivo do Git e passa para o modo baseado em Git

Mudar para o modo de banco de dados

Se você quiser parar de usar o modo baseado em Git e gerenciar o blueprint na UI:

No blueprint editor, clique no menu suspenso de origem e selecione Database
O conteúdo atual é preservado, mas futuros pushes para .devin/blueprint.yaml não atualizarão mais o blueprint
Agora você pode editar e salvar diretamente na UI

Mudar o root blueprint para o modo de banco de dados também muda todos os blueprints de workspace desse repo para o modo de banco de dados, já que a sincronização acontece no nível do repo.

Workspaces desvinculados

Você pode desvincular blueprints individuais de workspace do Git, mantendo a raiz no modo baseado em Git. Um workspace desvinculado pode ser editado na UI e é ignorado durante a sincronização. Isso é útil quando um workspace precisa de um override temporário sem afetar o restante do repositório. Para vincular novamente um workspace desvinculado, altere sua origem de volta para Git no menu suspenso de origem.

Histórico de versões

Cada sincronização cria uma nova versão no histórico do blueprint, identificada com:

Origem: git_sync para versões criadas por sincronização, manual para versões criadas na UI
SHA do commit: o commit da branch padrão usado na sincronização (com link para o commit no seu provedor Git)

Você pode visualizar o histórico completo de versões e os diffs na aba Version history do editor de blueprint.

YAML com múltiplos documentos

Assim como no editor da UI, .devin/blueprint.yaml oferece suporte a YAML com múltiplos documentos usando o separador ---. Isso permite definir configurações específicas da plataforma em um único arquivo:

# Configuração Linux (default)
initialize: |
  curl -LsSf https://astral.sh/uv/install.sh | sh

maintenance: |
  uv sync
---
runs-on: windows

initialize: |
  powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

maintenance: |
  uv sync

Consulte Suporte ao Windows para obter detalhes sobre blueprints multiplataforma.

Solução de problemas

Blueprint não sincroniza

O arquivo está no caminho correto? Ele deve ser .devin/blueprint.yaml na raiz do repositório (ou <workspace>/.devin/blueprint.yaml para workspaces incluídos).
Você acionou uma sincronização? A sincronização não acontece automaticamente após um push. Chame o endpoint da API de sincronização ou clique no botão Sync na UI.
O repositório está no ambiente do Devin? O repo deve ser adicionado em Configurações > Ambiente > Blueprints para que a sincronização seja executada.
O modo baseado em Git está ativado? O blueprint deve estar no modo baseado em Git (não no modo de banco de dados) para que a sincronização o atualize.

Erros por YAML inválido

Se .devin/blueprint.yaml contiver YAML inválido ou não estiver em conformidade com o schema do blueprint, a sincronização falhará com um erro. Corrija o arquivo na branch padrão e sincronize novamente. O editor de blueprint na UI valida o schema e mostra erros antes que você abra uma PR, o que ajuda a detectar problemas antes que eles cheguem à branch padrão.

Blueprint mostra “Database” após fazer push

Se você fez push de um .devin/blueprint.yaml, mas o editor ainda mostra “Database” como a origem, talvez o blueprint ainda não tenha sido alternado para o modo baseado em Git. Use o menu suspenso de origem para mudar para seu provedor Git, o que aciona a sincronização inicial.

​Visão geral

​Primeiros passos

​1. Crie o arquivo blueprint

​2. Faça push para a branch padrão

​3. Verifique na UI

​Como a sincronização funciona

​Sync vs. build

​Sincronização via a API

​Fluxo completo

​Etapa 1: Sincronize o blueprint

​Etapa 2: Acione um build

​Etapa 3: Consultar o status da build (opcional)

​Sincronização em toda a Enterprise

​Exemplo: workflow do GitHub Actions

​Editando blueprints baseados em Git

​Criar uma PR pelo editor

​Edite diretamente no seu repositório

​Sugestões do Devin

​Monorepos e workspaces

​Root blueprint com includes

​Blueprints de workspace

​Regras de inclusão

​Alternar entre os modos Git e de banco de dados

​Mudar para o Git

​Mudar para o modo de banco de dados

​Workspaces desvinculados

​Histórico de versões

​YAML com múltiplos documentos

​Solução de problemas

​Blueprint não sincroniza

​Erros por YAML inválido

​Blueprint mostra “Database” após fazer push

Visão geral

Primeiros passos

1. Crie o arquivo blueprint

2. Faça push para a branch padrão

3. Verifique na UI

Como a sincronização funciona

Sync vs. build

Sincronização via a API

Fluxo completo

Etapa 1: Sincronize o blueprint

Etapa 2: Acione um build

Etapa 3: Consultar o status da build (opcional)

Sincronização em toda a Enterprise

Exemplo: workflow do GitHub Actions

Editando blueprints baseados em Git

Criar uma PR pelo editor

Edite diretamente no seu repositório

Sugestões do Devin

Monorepos e workspaces

Root blueprint com includes

Blueprints de workspace

Regras de inclusão

Alternar entre os modos Git e de banco de dados

Mudar para o Git

Mudar para o modo de banco de dados

Workspaces desvinculados

Histórico de versões

YAML com múltiplos documentos

Solução de problemas

Blueprint não sincroniza

Erros por YAML inválido

Blueprint mostra “Database” após fazer push