Branch environments

A branch environment is a copy of a project on another branch of its repository. You push feature/login, and next to https://shop.test there’s https://shop-feature-login.test with that branch running, its own containers and its own copy of the data. It’s the thing you want when a colleague asks “can I click through it before we merge?”.

You’ll find it all in the Branches section of the project. The project needs a repository under Git and a cloned checkout, because the environment starts from the parent’s working tree.

Creating one

Click Load the branches of the repository, pick a branch and Create environment. Envoryx then copies the project the same way Duplicate does, with every box ticked:

• the project files, including the ones git ignores (.env, vendor/, node_modules/), so the copy runs without installing everything again,
• every database, dumped and imported into the environment’s own database server,
• the objects in the bucket,
• the workers and cron jobs, the environment variables and the repository binding.

After the copy, the working tree switches to the branch (git checkout -f and git clean -fd, which removes untracked files the branch doesn’t ignore), the environment starts and its deploy commands run once. Copying takes as long as the project is big, so a project with a few gigabytes of uploads isn’t done in seconds.

The environment is a project of its own, named after both, like Shop (feature/login) with the slug shop-feature-login. Extra domains and backup schedules stay with the parent, as with any copy. And the things you fix by hand in a copy apply here too: if the app keeps its own URL in the database, the environment sends you back to the parent until you change it.

Creating environments takes an admin of the whole instance, like creating any project. An environment can’t have environments of its own; you always create them on the parent.

Deploy commands

What happens after a copy or a pull is up to you. Under Branch settings → Deploy commands you put one command per line, for example:

composer install
php artisan migrate --force
php artisan optimize:clear

They run one after another in the application container as the project owner, so the files they create belong to the right user. The application container is the first of PHP, Python, Go, Ruby, Java, .NET and Node.js the project has. Next to PHP that’s the PHP container, which has no npm, so leave asset builds out of the list and run npm ci or npm run build from the environment’s Actions section, which uses the Node.js container. The first command that fails stops the deploy, and the environment shows deploy failed with the output. Up to 20 commands fit, each a single line. The environment has to be running for a deploy.

On the environment’s own Branches section there are two buttons: Pull and deploy pulls its branch first (fast forward only, so commits you made inside the environment stay and a diverged branch fails rather than being overwritten), Run deploy commands skips the pull. The section also shows the commit, the time of the last deploy and its output.

Watching the repository

With Watch the repository on, Envoryx asks the repository every few minutes what branches it has. That’s a plain git ls-remote with the project’s credentials, so you don’t need a webhook, and it works with any Git server Envoryx can clone from. Check every (minutes) sets the interval; empty means 5.

On every check three things can happen:

1. A push to an environment’s branch is pulled and deployed, as long as the environment is running. A deploy that failed, at the pull or at one of the commands, isn’t retried for the same commit (and you get one notification, not one per check); the next push tries again.
2. A deleted branch takes its environment with it, files, database and volumes included. That’s the point of it, but it’s worth knowing before you delete a branch you still want to look at.
3. A new branch that matches a pattern in Branches with an automatic environment gets an environment. Patterns are globs, one per line, like feature/* or fix/*; * doesn’t match /. With the field empty, no environment is created on its own, so watching then only keeps your hand-made ones up to date.

Envoryx creates at most one new environment per check and stops at At most automatic environments (5 if empty, 50 at most). The limit counts every environment of the project, including those you created by hand. If creating one fails, you get a notification and Envoryx tries again with the branch’s next commit, not on every check, since each attempt copies the whole project.

Without watching, nothing is deleted automatically. An environment you no longer need you delete like any project, from its More actions menu. The parent itself can’t be deleted while it still has environments; Envoryx names them and asks you to delete them first.

Stopping idle environments

Five feature branches with a database each add up. Stop idle environments after (days) stops an environment nobody opened for that long, counted from the last request through the proxy or the last start. It works with or without watching. A stopped environment keeps its files and data; start it again when you need it. Empty means never.

Roles

An environment has no roles of its own. Whoever has a project role on the parent has the same role on the environment, checked every time and not copied once, so a role you change on the parent later reaches every environment straight away. Environments don’t appear in the project list under Settings → Users → Projects, see Users and roles.

Notifications, CLI and MCP

Two notification events belong to branch environments: Branch environment failed (on by default) for a failed creation or deploy, and Branch environment changed for one that was created, deleted with its branch or stopped for being idle.

From a script or a pipeline:

envoryx project branches shop                      # environments, commit, deploy state, URL
envoryx project branch shop feature/login          # create one
envoryx project deploy shop-feature-login          # pull and deploy (--no-pull: only deploy)

An AI assistant gets the same through the MCP tools list_branch_environments, create_branch_environment and deploy_branch_environment.