> ## Documentation Index > Fetch the complete documentation index at: https://docs.devin.ai/llms.txt > Use this file to discover all available pages before exploring further. # blueprints baseados em Git > Armazene blueprints como .devin/blueprint.yaml no seu repositório e sincronize-os via API ou pela UI.
## 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](/pt-BR/onboard-devin/environment/blueprint-reference) 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: ```yaml theme={null} 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: 1. **Sincronização via API** — Chame o endpoint de sincronização v3 (veja [Sincronização via API](#sync-via-the-api) abaixo). Esta é a abordagem recomendada para pipelines de CI/CD. 2. **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. 3. **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
```mermaid theme={null} sequenceDiagram participant Dev as Developer participant Git as Git Provider participant CI as CI/CD Pipeline participant API as Devin API Dev->>Git: Push/merge .devin/blueprint.yaml Git->>CI: Trigger post-merge workflow CI->>API: POST /v3/organizations/{org_id}/snapshot-setup/sync API-->>CI: 200 OK (repo_name) CI->>API: POST /v3/organizations/{org_id}/snapshot-setup/builds API-->>CI: 201 Created (build_id, status) CI->>API: GET /v3/organizations/{org_id}/snapshot-setup/builds/{build_id} API-->>CI: 200 OK (status: succeeded) ```
### Etapa 1: Sincronize o blueprint
Obtenha a versão mais recente de `.devin/blueprint.yaml` da branch padrão: ```bash theme={null} 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: ```json theme={null} {"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: ```bash theme={null} 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: ```json theme={null} { "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: ```bash theme={null} 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: ```bash theme={null} 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: ```json theme={null} {"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: ```yaml theme={null} # .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](/pt-BR/api-reference/overview) 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
1. Abra o editor de blueprint em **Configurações > Ambiente > Blueprints** 2. Edite o YAML no editor 3. Clique em **Criar PR** 4. O Devin abre uma pull request (PR) no seu repositório que atualiza `.devin/blueprint.yaml` 5. Revise, aprove e faça o merge da PR 6. 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
1. Edite `.devin/blueprint.yaml` no seu IDE ou no seu provedor Git 2. Faça commit e push para a branch padrão (ou abra uma PR e faça o merge) 3. 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](#sync-via-the-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: ```yaml theme={null} # 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`: ```yaml theme={null} # my-repo/packages/frontend/.devin/blueprint.yaml maintenance: | pnpm build knowledge: - name: lint contents: pnpm lint - name: test contents: pnpm test ``` ```yaml theme={null} # 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: 1. Crie `.devin/blueprint.yaml` no seu repositório com o conteúdo desejado 2. Faça push para a branch padrão 3. No editor de blueprint, clique no menu suspenso de origem e selecione seu provedor Git (por exemplo, "GitHub") 4. 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: 1. No blueprint editor, clique no menu suspenso de origem e selecione **Database** 2. O conteúdo atual é preservado, mas futuros pushes para `.devin/blueprint.yaml` não atualizarão mais o blueprint 3. 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: ```yaml theme={null} # 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](/pt-BR/onboard-devin/environment/windows-support) 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 `/.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.