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
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 — ou opte por sincronizar e executar o build a cada commit na branch padrão
Database	UI de configurações do Devin	Edite no navegador	Salvo imediatamente ao clicar

Como o Devin escolhe o modo quando você adiciona um repositório

Baseado em Git é o padrão sempre que um arquivo de blueprint está presente no repo. Quando você adiciona um repositório ao seu ambiente, o Devin verifica o branch padrão em busca de .devin/blueprint.yaml:

Se o arquivo existir, o Devin obtém o blueprint do Git (modo baseado em Git) e registra o SHA do commit a partir do qual sincronizou.
Se o arquivo não existir (ou se a descoberta falhar), o Devin cria um blueprint vazio que você gerencia na UI de configurações (modo de banco de dados).

Você pode alternar um repositório entre os dois modos a qualquer momento — consulte Alternando entre os modos Git e banco de dados.

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

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

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, a menos que o blueprint já esteja no modo baseado em Git e o repositório tenha a opção Run on every commit to default branch ativada. Se o blueprint estiver no modo de banco de dados, mude para Git para importar o arquivo. Se você estiver adicionando o repo pela primeira vez, a descoberta inicial lê o blueprint do Git.

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. Por padrão, a sincronização não acontece automaticamente a cada push. A sincronização é executada nestes casos:

Sincronização via API — Chame o endpoint de sincronização (beta) (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 cada commit na branch padrão (opcional) — Para repositórios com Run on every commit to default branch ativado, cada push para a branch padrão sincroniza o blueprint e aciona um build. Veja Sincronizar e fazer build a cada commit na branch padrão.

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

Sincronização e build a cada commit na branch padrão

Para repositórios do GitHub.com, você pode optar por sincronizações e builds automáticos em vez de chamar a API pelo CI ou clicar em Sync:

Acesse Configurações > Ambiente > Blueprints e clique no repositório.
Abra a aba Advanced.
Ative Run on every commit to default branch.

Com essa configuração ativada, cada push para a branch padrão sincroniza o blueprint baseado em Git e enfileira um build do snapshot para cada plataforma. Se um commit mais recente chegar enquanto o build de um commit anterior ainda estiver na fila, o build enfileirado é cancelado, de modo que apenas o commit mais novo seja construído; builds já iniciados são executados até a conclusão. Se o blueprint do repositório estiver no modo de banco de dados, o build usa o blueprint salvo no Devin em vez do arquivo do commit. Ative Report status checks for each commit para exibir o resultado de cada build como um check run do GitHub no commit.

A aba Advanced aparece apenas para repositórios do GitHub.com e somente quando essa opção está disponível para a sua organização. Para outros provedores Git, ou quando a configuração estiver desativada, use a sincronização via API ou o botão Sync.

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 separa essas operações para que você tenha controle total — chame sync primeiro e, em seguida, acione um build.

Sincronização via API

Os endpoints de blueprint e de build fazem parte da API estável /v3/. Os endpoints de sincronização ainda estão em beta e são disponibilizados em /v3beta1/; seus caminhos e formatos de requisição/resposta podem mudar antes da promoção para a /v3/.

Se Executar a cada commit na branch padrão não estiver disponível ou estiver desativado para o seu repositório, a forma recomendada de manter os blueprints sincronizados é fazer uma chamada à API 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/v3beta1/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": "pending",
  "trigger": "manual",
  "triggered_by_user_id": "user-abc123",
  "pinned": false,
  "started_at": null,
  "completed_at": null,
  "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: pending → running → succeeded ou failed (ou cancelled). Uma build parcial é retornada pela API como succeeded porque o snapshot é utilizável.

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/v3beta1/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: fluxo de trabalho 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/v3beta1/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 (não é necessário se Run on every commit to default branch estiver ativado)

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 Sincronização via API) ou ative a sincronização automática em commits na branch padrão.

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? Por padrã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. Se você espera que os pushes sincronizem automaticamente, verifique se Run on every commit to default branch está ativado na aba Advanced do repositório e se você fez push para a branch padrão.
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

​Como o Devin escolhe o modo quando você adiciona um repositório

​Primeiros passos

​ Crie o arquivo blueprint

​ Faça push para a branch padrão

​ Verifique na UI

​Como a sincronização funciona

​Sincronização e build a cada commit na branch padrão

​Sync vs. build

​Sincronização via 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: fluxo de trabalho 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

Como o Devin escolhe o modo quando você adiciona um repositório

Primeiros passos

Crie o arquivo blueprint

Faça push para a branch padrão

Verifique na UI

Como a sincronização funciona

Sincronização e build a cada commit na branch padrão

Sync vs. build

Sincronização via 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: fluxo de trabalho 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