> For the complete documentation index, see [llms.txt](https://docs.tessl.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tessl.io/automations/environments.md).

# Environments

A named set of secrets and configuration that a schedule, launch, or cloud run executes inside. Store API keys and credentials here.

## What is an environment?

An environment is a named set of secrets and configuration attached to a workspace. When a schedule fires, when you trigger a launch, or when a cloud run starts, it runs inside an environment. That environment is where API keys, webhook URLs, and other credentials live.

You reference an environment by name when you create a schedule or start a launch. The run picks up whatever secrets are stored there.

A repo-defined schedule in `tessl.json` names its environment by **name**, not by ID:

```json
{
  "schedules": {
    "weekly-changelog": {
      "skill": "tessl/changelog-writer",
      "cron": "0 9 * * 5",
      "environment": "production"
    }
  }
}
```

The name is used because an environment ID is workspace-scoped: it resolves to nothing in another workspace, so a committed file names the environment and Tessl resolves it to an ID when the file syncs. The environment must already exist in the workspace before the schedule syncs. If no environment of that name exists, Tessl skips that schedule. It does not create the environment for you, and it does not delete anything. Create the environment (see below), then trigger a new sync. The easiest way is to update `tessl.json` (even a minor edit counts) and push to your default branch, or force-push the default branch.

## What goes in an environment

An environment holds any secrets or API keys your plugin needs at runtime.

**Scheduled runs require a GitHub token.** A scheduled run cannot mint its own GitHub token. You must include a `GITHUB_TOKEN` (or `GH_TOKEN`) in the environment so the run can check out your repo and open pull requests. Without it, the schedule cannot start a run against a repository.

Other common values to include:

* A Linear API key (if the plugin reads or writes Linear issues)
* A Slack webhook URL (if the plugin posts notifications)
* Any other third-party service credential the plugin needs

## How to create one

### From the CLI

Create the environment and supply its secrets in one step using a `.env` file:

```bash
# Create a .env file with your secrets
cat > production.env << 'EOF'
GITHUB_TOKEN=ghp_your_token_here
LINEAR_API_KEY=your_linear_key_here
EOF

# Create the environment from the file
tessl env create production --env-file production.env
```

To update an existing environment later, use `tessl env update`:

```bash
tessl env update production --env-file production.env
```

Note: `update` replaces the entire environment value. Include all keys you want to keep, not just the changed ones.

### From the web app

1. Open your workspace settings.
2. Go to **Environments**.
3. Click **Create environment**, enter a name, and save.
4. On the environment's page, click **Replace value**, enter all key/value pairs, and save.

Note: **Replace value** replaces the entire environment value. The prior value cannot be recovered after you save, so include all keys in the new value.

## Related pages

* [Schedules](/automations/overview/overview.md): how to reference an environment when creating a schedule


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.tessl.io/automations/environments.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.