Project settings¶
Live
Forge does not read a configuration file from your repository. Settings are stored by Forge per project (and optionally per repository) and are edited in the web portal. A few can also be changed from an issue.
From an issue¶
/project-show
/project-set budget_cap_usd 750
/project-set --repo limits.qa_test_floor 10
/refresh-config
/project-showposts the effective configuration for the repository and where each value came from./project-set <key> <value>changes a project setting. With--repoit changes only this repository. The key is a dotted path and the value is JSON or plain text./refresh-configclears cached settings so the next agent launch re-reads them./project-guardrails-addappends a guardrail.
Settings that change billing plan or affect every customer are not editable by you.
What you can configure¶
| Area | What it controls |
|---|---|
| Stacks | Backend, web and mobile stacks for each repository, and per-app-root stacks in a monorepo. |
| Workflow | How epics run: pull request timing and draft or ready, dev and test deploy steps. See Branches and pull request timing. |
| Branches | Which branches Forge merges into: integration, staging, production and base. |
| Plan approval | Whether the plan is auto-approved (auto_approve). |
| Models | Which provider and model each agent uses. See Bring your own AI key. |
| Keys | Your AI vendor credentials. |
| Budget | A monthly budget cap, with an 80 percent warning, adaptive slowdown and a block on over-budget builds. |
| Limits | Iteration and test-count ceilings. |
| Skills and guardrails | Team conventions and rules injected into every agent. |
| MCP servers | Tools agents can call, such as read-only log access. |
| Schedules | Recurring tasks and drift probes. Business and Enterprise |
| Observability | Which post-deploy checks run. Business and Enterprise |
| Compliance | Which compliance rule sets are applied to agents. Business and Enterprise |
| GitHub access | How Forge accesses your repositories. |
| Team | Who in your workspace can use the portal. Roles are owner and member. |
Examples of keys you can set with /project-set: budget_cap_usd, auto_approve, limits.qa_test_floor, models.cache_ttl.
Where settings apply¶
A project setting applies to every repository in the project. A repository setting, set with --repo, overrides it for one repository. Changes take effect at the next agent launch, with no redeploy.
Branches and pull request timing¶
| Setting | Values | Default |
|---|---|---|
branches.integration |
Branch completed epics merge into | develop |
branches.staging |
Branch develop is promoted to after the dev deploy |
test |
branches.production |
Pull request target | main |
branches.base |
Branch new epic branches are cut from | main |
workflow.deploy_dev |
Merge into integration and deploy to dev | on |
workflow.deploy_test |
Promote to staging and deploy to test | on |
workflow.pr_on |
When the pull request opens: after_complete, after_dev or after_test |
after_test |
workflow.pr_draft |
Open the pull request as a draft | off |
/project-set workflow.pr_on after_dev
/project-set branches.integration main
Presets:
- Pull request only, no deploys:
deploy_devoff,deploy_testoff,pr_on=after_complete. The pull request opens from the epic branch. - Dev deploy, then pull request:
deploy_testoff,pr_on=after_dev. - Trunk-based: set
branches.integration,branches.stagingandbranches.productionto your default branch. Forge then merges completed epics directly into it. Protect it with required checks.
Forge never merges the pull request itself. With the defaults it writes only to the integration and staging branches.