Project configuration
Everything under Project → Settings: how your app is built, which repository and branches it deploys from, the environment variables it runs with, and the lifecycle actions for the project itself.
Build settings
Sensible defaults are inferred from your framework. Override these only when your project layout differs — a monorepo, a custom output folder, or a non-standard package manager.
| Setting | Example | What it does |
|---|---|---|
| Install command | pnpm install | Runs before the build to install dependencies |
| Build command | pnpm build | Produces your production output |
| Output directory | dist | Folder containing the built artifact to serve |
| Root directory | apps/web | Subdirectory to build (for monorepos) |
Deploxa auto-detects your framework from the repository and applies the right build pipeline; you can override the detected framework here if detection guesses wrong. See the Frameworks guide for the full detection rules. Build caching reuses dependencies between builds to speed them up, and image optimization serves resized, modern-format images — both are toggled on this screen and apply to subsequent deployments.
Git & auto-deploy
The connected GitHub repository and its production branch (usually main) are shown here. Pushes to the production branch deploy to your production URL; pushes to any other branch create preview deployments.
Auto-deploy on push
With auto-deploy enabled, every push to a tracked branch triggers a build automatically via the GitHub webhook. Disable it if you would rather deploy manually or through a deploy hook.
Branch policy
Configure which branches produce preview deployments, and protect specific branches so they can't be deployed by accident — useful for keeping a release branch deployable only through a reviewed process.
Deployment environments
Every project has Production, Preview, and Development by default. You can define additional environments and target them by branch pattern — the first environment whose pattern matches the pushed branch wins.
| Environment | Branch pattern | Result |
|---|---|---|
| Production | main | Deploys to the production URL |
| Staging | staging | Deploys with staging config |
| Preview | * | Any other branch gets a preview deployment |
Environment variables
Add a variable with its key, value, and target environments. Values are encrypted at rest with AES-256-GCM before being written to the database, and take effect on the next deployment. You can also paste a whole .env file into the bulk import box — quoted values, comments, and blank lines are all parsed correctly.
Environment targets
Each variable is scoped to one or more environments, so a value can differ between Production and Preview without a code change.
| Target | Applied to |
|---|---|
| Production | Deployments from your production branch |
| Preview | Branch and pull-request deployments — point these at staging services |
| Development | Held for local use; not injected during builds |
Browser vs. server variables
Server-side variables are never exposed to the browser. To make one available in client-side JavaScript, prefix it with NEXT_PUBLIC_ (Next.js), VITE_ (Vite), or REACT_APP_ (CRA).
# Server-only (never sent to browser) DATABASE_URL=postgresql://... JWT_SECRET=supersecret # Exposed to the browser NEXT_PUBLIC_API_URL=https://api.example.com VITE_STRIPE_KEY=pk_live_...
System-injected variables
These are set automatically in every build and runtime environment:
| Variable | Value |
|---|---|
DEPLOXA_URL | The public URL of this deployment |
DEPLOXA_ENV | production | preview | development |
DEPLOXA_DEPLOYMENT_ID | Unique ID of this deployment |
DEPLOXA_GIT_COMMIT_SHA | Git commit SHA being deployed |
DEPLOXA_GIT_BRANCH | Branch name being deployed |
Read them the way you would locally — process.env.DATABASE_URL in Node.js.
Encryption & auditing
- AES-256-GCM at rest — every value is encrypted before it reaches the database; nothing is stored in plaintext.
- Per-org KMS keys (Team plan) — bring your own AWS KMS key for envelope encryption and keep full key custody.
- Audit log — every create, update, and delete is recorded in the organization audit log.
Deploying from your own pipeline
A deploy hook is a secret URL that starts a deployment when you POST to it — the simplest way to trigger Deploxa from GitHub Actions, GitLab CI, CircleCI, or a cron job. Create one under Integrations and store it as a secret in your pipeline.
# GitHub Actions
- name: Deploy to Deploxa
run: curl -X POST "${{ secrets.DEPLOXA_DEPLOY_HOOK }}"Deploy ignore patterns
Skip a build when a push only touches files that don't affect your app — docs, tests, CI config. Patterns use micromatch globs, and a build is skipped only when every changed file matches one.
**/*.md docs/** .github/**
For monorepos, pair this with the root directory setting above so only changes under your app trigger a build.
Status checks
Deploxa surfaces your GitHub Actions runs and posts deployment status checks back to commits and pull requests, so the result shows up in your GitHub workflow.
General & advanced
Change the project name and slug, and copy the Project ID used by the analytics and custom-event ingest endpoints.
*.deploxa.com subdomain and every URL built from it. Update external references after renaming.The advanced section holds the lifecycle actions:
- Pause — temporarily stop serving the project
- Transfer — request moving it to another organization (handled via support to verify ownership)
- Export — download your project data
- Delete — permanently remove the project and its deployments
Deletion is permanent