Referência de campos de blueprints

Esta é a referência completa dos campos de blueprints. Para uma introdução aos blueprints e a como eles se encaixam no ambiente do Devin, veja Configuração declarativa do ambiente.

Um blueprint define como o ambiente do Devin é configurado: quais ferramentas instalar, como manter as dependências atualizadas e quais comandos o Devin deve conhecer.

Visão geral

Um blueprint tem três seções principais:

initialize: ... # Instala ferramentas e runtimes
maintenance: ... # Instala dependências do projeto
knowledge: ... # Informações de referência para o Devin (nunca executado)

Seção	Objetivo	Executado?
`initialize`	Instalar ferramentas do sistema, runtimes de linguagem e CLIs globais	Sim, em cada build
`maintenance`	Instalar e atualizar as dependências do projeto	Sim, durante builds + no início da sessão
`knowledge`	Informar ao Devin como executar lint, testes e build, além de outras informações específicas do projeto	Não, usado apenas como referência

As três seções são opcionais. Você pode incluir qualquer combinação delas. initialize é executado apenas durante builds. Os resultados são salvos no snapshot. maintenance é executado durante builds (após initialize) e no início de cada sessão, após fazer pull do código mais recente, então os comandos devem ser rápidos e incrementais. Os builds são executados automaticamente quando seu blueprint muda e periodicamente (a cada ~24 horas).

initialize

Use initialize para instalar ferramentas e runtimes que não dependem do estado específico do seu código: runtimes de linguagens, pacotes do sistema e CLIs globais.

Forma simples

Para comandos de shell simples, use um escalar em bloco:

initialize: |
  curl -LsSf https://astral.sh/uv/install.sh | sh
  apt-get update && apt-get install -y build-essential
  npm install -g pnpm

Formato estruturado

Para etapas nomeadas, variáveis de ambiente ou GitHub Actions, use uma lista:

initialize:
  - name: "Install Python 3.12"
    uses: github.com/actions/setup-python@v5
    with:
      python-version: "3.12"

  - name: "Install system packages"
    run: |
      apt-get update
      apt-get install -y libpq-dev

  - name: "Install global tools"
    run: pip install uv
    env:
      PIP_BREAK_SYSTEM_PACKAGES: "1"

As duas formas podem ser combinadas. A forma simples equivale a uma única etapa com run.

Quando usar `initialize` vs `maintenance`

Coloque em `initialize`	Coloque em `maintenance`
Instalação do runtime de linguagem	`npm install` / `pip install`
Pacotes do sistema (`apt-get`)	`bundle install`
Ferramentas de CLI globais	`go mod download`
Configuração única	Atualizações do cache de dependências
GitHub Actions (`setup-python`, etc.)	Scripts de configuração específicos do repositório

Ambas as seções são executadas em cada build, mas essa separação mantém a configuração legível. Ferramentas e runtimes de linguagem ficam em initialize; comandos de dependência vinculados aos arquivos de lock do seu código ficam em maintenance.

maintenance

Use maintenance para instalar dependências e executar outros comandos que devem ser executados depois que seu código for clonado. É aqui que entram npm install, pip install, uv sync e comandos semelhantes.

maintenance: |
  npm install
  pip install -r requirements.txt

Ou em formato estruturado:

maintenance:
  - name: "Install npm dependencies"
    run: npm install

  - name: "Install Python dependencies"
    run: uv sync
    env:
      UV_CACHE_DIR: /tmp/uv-cache

Para blueprints no nível do repositório, os comandos maintenance são executados a partir do diretório raiz do repositório. Para blueprints no nível da organização, eles são executados a partir do diretório inicial (~).

knowledge

A seção knowledge não é executada. Ela fornece informações de referência que Devin usa ao trabalhar no seu projeto. É aqui que você informa ao Devin os comandos corretos para linting, testing, build e quaisquer outros workflows específicos do projeto.

knowledge:
  - name: lint
    contents: |
      Run linting with:
      npm run lint

      For auto-fix:
      npm run lint -- --fix

  - name: test
    contents: |
      Run the full test suite:
      npm test

      Run a single test file:
      npm test -- path/to/test.ts

  - name: build
    contents: |
      npm run build

      Build output goes to dist/

Cada item de conhecimento tem:

Campo	Tipo	Descrição
`name`	string	Identificador deste item de conhecimento (por exemplo, `lint`, `test`, `build`)
`contents`	string	Texto livre com comandos, instruções ou observações

O campo name é um rótulo. Por convenção, lint, test e build são os nomes padrão. O Devin usa esses nomes ao verificar o próprio trabalho. Você pode adicionar outros itens de conhecimento com nomes personalizados:

knowledge:
  - name: lint
    contents: ...
  - name: test
    contents: ...
  - name: build
    contents: ...
  - name: deploy
    contents: |
      Deploy to staging:
      npm run deploy:staging
  - name: database
    contents: |
      Run migrations:
      npm run db:migrate

      Seed test data:
      npm run db:seed

Tipos de etapa

Cada etapa em initialize ou maintenance usa um de dois tipos: comandos de shell (run) ou GitHub Actions (uses).

Comandos de shell (`run`)

Execute comandos arbitrários de shell no bash:

- name: "Install dependencies"
  run: |
    npm install
    pip install -r requirements.txt

Campo	Tipo	Descrição
`name`	string (optional)	Rótulo legível para humanos da etapa
`run`	string	Comando(s) de shell a ser executado(s)
`env`	map (optional)	Variáveis de ambiente adicionais para esta etapa

Detalhes de execução:

Os comandos são executados em bash. Se qualquer comando em um script com várias linhas falhar, a etapa inteira é interrompida imediatamente.
Blueprints no nível da organização são executados no diretório inicial (~).
Blueprints no nível do repositório são executados na raiz do repositório clonado.
Cada etapa tem um tempo limite de 1 hora.
Os segredos ficam automaticamente disponíveis como variáveis de ambiente.

GitHub Actions (`uses`)

Execute GitHub Actions baseadas em Node.js diretamente no seu blueprint:

- name: "Install Python"
  uses: github.com/actions/setup-python@v5
  with:
    python-version: "3.12"

Campo	Tipo	Descrição
`name`	string (optional)	Nome legível da etapa
`uses`	string	Referência da ação do GitHub
`with`	map (optional)	Parâmetros de entrada da ação
`env`	map (optional)	Variáveis de ambiente extras para esta etapa

Formato da referência da ação:

github.com/<owner>/<repo>@<ref>
github.com/<owner>/<repo>/<subpath>@<ref>

O prefixo github.com/ e o sufixo @<ref> são obrigatórios. O ref normalmente é uma tag de versão, como v5. Ações mais usadas:

Action	Purpose	Example `with`
`github.com/actions/setup-python@v5`	Instalar Python	`python-version: "3.12"`
`github.com/actions/setup-node@v4`	Instalar Node.js	`node-version: "20"`
`github.com/actions/setup-go@v5`	Instalar Go	`go-version: "1.22"`
`github.com/actions/setup-java@v4`	Instalar Java/JDK	`java-version: "21"`, `distribution: "temurin"`
`github.com/gradle/actions/setup-gradle@v4`	Instalar Gradle	(nenhum)
`github.com/ruby/setup-ruby@v1`	Instalar Ruby	`ruby-version: "3.3"`

Somente GitHub Actions baseadas em Node.js são compatíveis. Ações compostas e ações baseadas em Docker não são compatíveis.

Como os valores de with funcionam: Os valores passados em with são fornecidos à ação como entradas, seguindo as mesmas convenções dos workflows do GitHub Actions. Todos os valores são convertidos em strings.

with:
  python-version: "3.12"
  check-latest: true
  cache: "pip"

Como as ações propagam alterações: As ações podem modificar o ambiente para as etapas seguintes. Por exemplo, setup-python adiciona o binário do Python ao PATH, que permanece disponível para todas as etapas posteriores e no maintenance.

`run` vs `uses`: qual usar

Use `run` quando…	Use `uses` quando…
Instalar pacotes do sistema (`apt-get`)	Configurar runtimes de linguagem (Python, Node, Go, Java, Ruby)
Executar scripts específicos do projeto	Houver uma GitHub Action oficial para o que você precisa
Configurar arquivos ou o ambiente	Você quiser gerenciamento automático de versões e cache
O comando for simples e autocontido	Você usaria a mesma Action em um workflow do GitHub Actions

Na prática, a maioria das configurações usa uses para runtimes de linguagem e run para todo o resto.

Variáveis de ambiente e segredos

Variáveis de ambiente por etapa

Cada etapa pode definir variáveis de ambiente adicionais usando o campo env:

- run: pip install -r requirements.txt
  env:
    PIP_INDEX_URL: "https://pypi.example.com/simple/"
    PIP_BREAK_SYSTEM_PACKAGES: "1"

Eles ficam restritos à etapa e não persistem nas etapas subsequentes.

Variáveis de ambiente compartilhadas entre etapas (`$ENVRC`)

Para propagar variáveis de ambiente entre etapas, grave-as no arquivo $ENVRC:

- name: "Set shared variables"
  run: |
    echo "DATABASE_URL=postgresql://localhost:5432/myapp" >> $ENVRC
    echo "APP_ENV=development" >> $ENVRC

As variáveis gravadas em $ENVRC são exportadas automaticamente e ficam disponíveis para todas as etapas seguintes e para a sessão do Devin. Isso funciona de forma semelhante ao $GITHUB_ENV no GitHub Actions.

Segredos

Os segredos configurados na interface do Devin (Configurações → Secrets) são injetados automaticamente como variáveis de ambiente. Você não precisa declará-los no blueprint. Basta referenciá-los pelo nome (por exemplo, $MY_SECRET). Os segredos são injetados antes da execução de cada etapa durante os builds e reinjetados no início de cada sessão. Eles são removidos da própria imagem do snapshot, para que as credenciais nunca fiquem embutidas em imagens de máquina salvas.

Segredos da organização: Disponíveis como variáveis de ambiente em todas as etapas de todos os blueprints da org. Configure-os em Configurações → Secrets.
Segredos do Enterprise: Mesclados com os segredos da org (os segredos da org têm precedência em caso de conflito de nomes). Disponíveis em todas as org do enterprise.
Segredos do repositório: Gravados em um arquivo por repo em /run/repo_secrets/{owner/repo}/.env.secrets. Durante os builds, os segredos do repo são carregados automaticamente antes da execução das etapas do blueprint desse repo. Durante a sessão, o Devin os carrega ao trabalhar no repo. Configure-os em Configurações → Secrets com escopo de repo.

Segredos apenas para build: Segredos marcados como “somente para build” ficam disponíveis durante os builds do snapshot, mas são removidos antes de o snapshot ser salvo. Use-os para credenciais necessárias apenas no momento do build (por exemplo, baixar artefatos privados durante initialize).

maintenance é executado tanto durante os builds quanto no início de cada sessão. Se uma etapa maintenance gravar segredos em arquivos de configuração (por exemplo, ~/.m2/settings.xml, ~/.npmrc), esses arquivos serão incorporados ao snapshot. Coloque as etapas que gravam credenciais em maintenance (não em initialize) para que sejam atualizadas a cada sessão, mas lembre-se de que os arquivos gravados persistem na imagem. Para máxima segurança, use variáveis de ambiente ou $ENVRC em vez de gravar credenciais em disco.

Anexos de arquivos

Você pode importar arquivos (como .npmrc, settings.xml e arquivos de configuração) no editor de blueprint. Os arquivos importados são gravados em ~/.files/, e uma variável de ambiente é definida apontando para o caminho de cada arquivo:

$FILE_SETTINGS_XML    -> /home/ubuntu/.files/settings.xml
$FILE_NPMRC           -> /home/ubuntu/.files/.npmrc

O nome da variável é obtido a partir do nome do arquivo: em maiúsculas, com caracteres não alfanuméricos substituídos por underscores, com o prefixo FILE_. Use anexos de arquivo nas etapas do seu blueprint:

maintenance:
  - name: "Configure Maven"
    run: |
      mkdir -p ~/.m2
      cp "$FILE_SETTINGS_XML" ~/.m2/settings.xml

Blueprints baseados em Git

Blueprints baseados em Git ainda não têm suporte. Esse recurso chegará em breve. Você poderá armazenar blueprints no seu repositório e fazer com que as builds sejam acionadas automaticamente quando houver alterações. Por enquanto, configure os blueprints pela interface em Configurações > Configuração do ambiente.

Exemplo completo

Para entender como os blueprints se compõem entre os níveis (enterprise → org → repo), os status das builds, os estados do repositório e o que aciona um rebuild, consulte Builds e sessões na página de configuração declarativa.

Blueprint de nível da organização

Ferramentas compartilhadas de que todos os repositórios da organização precisam. É executado primeiro (após qualquer blueprint Enterprise), no diretório inicial.

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

  - name: "Install Python 3.12 and uv"
    run: |
      curl -LsSf https://astral.sh/uv/install.sh | sh

  - name: "Install shared tools"
    run: |
      npm install -g pnpm turbo
      apt-get update && apt-get install -y jq ripgrep

  - name: "Configure private registry"
    run: |
      echo "//npm.corp.example.com/:_authToken=$NPM_REGISTRY_TOKEN" >> ~/.npmrc

Blueprint em nível de repositório

Configuração específica do projeto para um monorepo em Node.js + Python. É executado após o blueprint em nível da organização, no diretório do repositório.

initialize:
  - name: "Install Playwright browsers"
    run: npx playwright install --with-deps chromium

  - name: "Set up project environment variables"
    run: |
      echo "DATABASE_URL=postgresql://localhost:5432/myapp_dev" >> $ENVRC
      echo "REDIS_URL=redis://localhost:6379" >> $ENVRC
      echo "APP_ENV=development" >> $ENVRC

maintenance:
  - name: "Install frontend dependencies"
    run: |
      cd frontend
      pnpm install

  - name: "Install backend dependencies"
    run: |
      cd backend
      uv sync

  - name: "Run database migrations"
    run: |
      cd backend
      uv run alembic upgrade head
    env:
      DATABASE_URL: "postgresql://localhost:5432/myapp_dev"

knowledge:
  - name: lint
    contents: |
      Frontend:
      cd frontend && pnpm lint

      Backend:
      cd backend && uv run ruff check .

      Auto-fix:
      cd frontend && pnpm lint --fix
      cd backend && uv run ruff check --fix .

  - name: test
    contents: |
      Frontend unit tests:
      cd frontend && pnpm test

      Backend unit tests:
      cd backend && uv run pytest

      E2E tests (requires dev server running):
      cd frontend && pnpm test:e2e

  - name: build
    contents: |
      Frontend:
      cd frontend && pnpm build

      Backend:
      cd backend && uv run python -m build

  - name: dev-server
    contents: |
      Start the full development stack:
      cd backend && uv run uvicorn main:app --reload &
      cd frontend && pnpm dev

      Frontend: http://localhost:3000
      Backend API: http://localhost:8000
      API docs: http://localhost:8000/docs

  - name: database
    contents: |
      Run migrations:
      cd backend && uv run alembic upgrade head

      Create a new migration:
      cd backend && uv run alembic revision --autogenerate -m "description"

      Reset the database:
      cd backend && uv run alembic downgrade base && uv run alembic upgrade head

Get Started

Essential Guidelines

Onboarding Devin

Working with Devin

Product Guides

Integrations

Admin

Referência de campos de blueprints

Visão geral

initialize

Forma simples

Formato estruturado

Quando usar `initialize` vs `maintenance`

maintenance

knowledge

Tipos de etapa

Comandos de shell (`run`)

GitHub Actions (`uses`)

`run` vs `uses`: qual usar

Variáveis de ambiente e segredos

Variáveis de ambiente por etapa

Variáveis de ambiente compartilhadas entre etapas (`$ENVRC`)

Segredos

Anexos de arquivos

Blueprints baseados em Git

Exemplo completo

Blueprint de nível da organização

Blueprint em nível de repositório

Get Started

Essential Guidelines

Onboarding Devin

Working with Devin

Product Guides

Integrations

Admin

​Visão geral

​initialize

​Forma simples

​Formato estruturado

​Quando usar initialize vs maintenance

​maintenance

​knowledge

​Tipos de etapa

​Comandos de shell (run)

​GitHub Actions (uses)

​run vs uses: qual usar

​Variáveis de ambiente e segredos

​Variáveis de ambiente por etapa

​Variáveis de ambiente compartilhadas entre etapas ($ENVRC)

​Segredos

​Anexos de arquivos

​Blueprints baseados em Git

​Exemplo completo

​Blueprint de nível da organização

​Blueprint em nível de repositório

Visão geral

initialize

Forma simples

Formato estruturado

Quando usar `initialize` vs `maintenance`

maintenance

knowledge

Tipos de etapa

Comandos de shell (`run`)

GitHub Actions (`uses`)

`run` vs `uses`: qual usar

Variáveis de ambiente e segredos

Variáveis de ambiente por etapa

Variáveis de ambiente compartilhadas entre etapas (`$ENVRC`)

Segredos

Anexos de arquivos

Blueprints baseados em Git

Exemplo completo

Blueprint de nível da organização

Blueprint em nível de repositório