> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage preview environments

> List capsules, schedule them, update their secrets, choose branches and remove them

Once [preview environments are set up](/guides/preview-environments), GitHub Actions creates and updates a capsule for every branch you push. This page covers what you do with them afterwards. See [Capsules](/concepts/capsules) for how they work.

## See what is running

```
/monk list the preview environments
```

Monk shows each capsule's branch, status, cluster, preview URL and last deploy. The web dashboard lists the same under the project's **Previews** tab, with the pull request and schedule. Open a preview's page there for its URL.

## Keep capsules up only when people use them

```
/monk run preview environments only on weekdays from 8 to 19 Berlin time
```

A schedule has a timezone, rules for when capsules are up or down, and a default state for the rest of the time. You can add exceptions for dates:

```
/monk keep preview environments up all day during the week of 9 November
```

Change the schedule for one capsule, or send it back to the project's:

```
/monk keep the feature-search preview up all the time
```

```
/monk make the feature-search preview follow the project schedule again
```

You approve each change in the local dashboard, where it shows the current and the new schedule. In the web dashboard, the project's Previews tab and each preview's page have the same controls.

The workflow applies the schedule every hour. A capsule that is taken down loses its cluster and data, and comes back from the branch with fresh data.

## Choose which branches get capsules

In the web dashboard, open the project's **Previews** tab and **How previews work here**:

* **Build previews for pull requests** turns capsules on or off for the project.
* **Only these branches** and **Never these branches** take comma-separated patterns such as `feature/*`.

The next push follows the new settings. You need the manage permission on the project to change them.

## Update secrets

```
/monk update the secrets for the preview environments
```

Monk asks whether the change is for all capsules or one:

* **All capsules (global):** stores the values in GitHub and updates the workflow. Commit and push it. New capsules get the values. A capsule that is already running keeps its old values, so update it locally as well if it needs them now.
* **One capsule (local):** writes the values into a running capsule right away. Ask Monk to switch to that capsule's cluster first.

Values are entered in the local dashboard. To refresh the cloud credentials stored in GitHub, for example after rotating a key:

```
/monk refresh the cloud credentials for the preview environments
```

## Redeploy or remove a capsule

Pushing to the branch rebuilds and redeploys its capsule. To remove one, close or merge the branch's pull request. Deleting the branch alone doesn't remove it.

You can also run the **Monk Capsules** workflow from the repository's Actions tab, with a branch and an action:

| Action | Use it to |
| - | - |
| `provision_deploy` | Create the capsule if it is missing, then build and deploy |
| `deploy` | Redeploy an existing capsule without touching its infrastructure |
| `deprovision` | Delete the capsule's cluster and data, keeping its record |
| `destroy` | Remove the capsule completely |

## When a run fails

Open the failed run in the Actions tab and read the job's log. Then fix what is in your project and push again:

```
/monk the capsule run for feature-search failed, here is the log: ...
```

The usual causes are a template that doesn't deploy, a secret that isn't set, or a name that two branches share. Don't edit `dynenv.yml` by hand, because running setup again replaces it, and don't delete a capsule's cluster yourself, because its records and pull request stay behind. If the failure is in Monk's workflow rather than your project, report it:

```
/monk report a bug
```

## Replace the API key

The project API key the workflow uses lasts 365 days. Run setup again before it expires:

```
/monk set up preview environments again to renew the key
```

## Next

* [Capsules](/concepts/capsules)
* [Costs](/guides/costs)
* [Secrets and config](/guides/secrets-and-config)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.