Bring your own templates

When you run start_project, deploymill scaffolds the new repo from a starter template — a minimal app that gets the first deploy green and pins the container port. Out of the box those come from the official DeployMill/Templates repo (the static, node, and python starters).

If your team has its own conventions — a house framework, a standard Dockerfile, preconfigured linting, a shared component library — you can point your workspace at your own templates repo instead. New projects then scaffold from your starters, and list_templates / start_project show your stack names.

The official catalog stays the fallback: if your repo is ever unreachable or misconfigured, scaffolding falls back to the official starters rather than breaking.

This is a workspace setting, configured in the dashboard by an admin or owner — not something the agent sets. The agent simply uses whatever templates the workspace is pointed at.

How a templates repo is structured

A templates repo is a normal Git repo with a small manifest contract:

1. A root deploymill.json that lists the template directories:

   {
     "schemaVersion": 1,
     "templates": [{ "dir": "static" }, { "dir": "node" }, { "dir": "worker-node" }]
   }

1. One directory per template, each containing its files plus its own

   deploymill.json manifest describing the stack:

   {
     "schemaVersion": 1,
     "stack": "node",
     "workload": "web",
     "title": "Node.js (our house setup)",
     "description": "Node 22 + our shared server preset.",
     "port": 3000,
     "buildType": "dockerfile"
   }

process, no port). A stack can have both a web and a worker variant (e.g. dirs node and worker-node, both with "stack": "node"); they're grouped into one catalog entry. A stack must have a web variant to appear.

{{PROJECT_NAME}} substituted for the project name. The template's own deploymill.json is not copied.

The official DeployMill/Templates repo is the reference for the exact layout — copy its shape and edit from there.

Setting it on the Connections page

In the dashboard, go to Connections → Templates (admin/owner only) and fill in:

• Repo — owner/name or a github.com URL of your templates repo.
• Ref — the branch, tag, or commit to read (defaults to main).
• Access:
  • Public repo — the repo is read anonymously; no connection needed.
  • Private via <account> — pick one of your org's

    connected GitHub accounts. The repo is read privately through that connection's installation. (Connect your account under Connections → Source first.)

Use Test to validate the repo and preview the resolved catalog without saving, then Save. Saving re-validates: if the repo can't be read or has no valid root manifest, the save is rejected with the reason — so a typo can't silently break start_project. Clear reverts your workspace to the official catalog.

What changes for the agent

Once set, the agent's deploy-lifecycle template surfaces become workspace-aware:

• list_templates returns your catalog (its stack keys, titles, ports, and

  worker support).

• start_project accepts your stack keys. Passing a stack that isn't in the

  catalog returns a structured unknown_stack error listing the valid keys, so the agent can correct and retry.

Everything else about start_project is unchanged — it still creates the repo, provisions and deploys the app, and attaches a domain.

Notes & limits

• The repo URL is constrained to GitHub (owner/name or a github.com URL).
• Templates are just files committed into your new repo — they're never executed

  by the server.

• A custom catalog replaces the official one for your workspace (the official

  set isn't merged in alongside it); it remains only as the unreachable-repo fallback.

• Custom stacks don't have the per-stack conventions guides the official

  node / python stacks ship with — your template's own files are the contract.