Working with Environments

Inngest accounts all have multiple environments that help support your entire software development lifecycle. Inngest has different types of environments:

• Production Environment for all of your production applications, functions and event data.
• Branch Environments are sandbox environments that enables developers on your team to test your changes specific to current Git feature branch. These are designed to work with platforms that support branch-based deployment previews like Vercel or Netlify.
• Custom Environments are used to create shared, non-production environments like staging, QA, or canary.
• Local Environment leverages the Inngest Dev Server (npx inngest-cli@latest dev) to test and debug functions on your own machine.

The key things that you need to know about environments:

• Data is isolated within each environment. Event types or functions may share the same name, but their data and logs are fully separated.
• Each environment uses Event Keys and Signing Keys to securely send data or sync apps within a given environment.
• You can sync multiple applications with each environment.
• You are billed for your usage across all environments, except of course your local environment.

Branch Environments

Most developer workflows are centered around branching, whether feature branches or a variant of GitFlow. Inngest's Branch Environments are designed to give you and your team an isolated sandbox for every non-production branch that you deploy. For example,

Branch deployments:

• Are created on-demand when you send events or register your functions for a given environment
• Share Event Keys and Signing Keys to streamline your developer workflow (see: Configuring Branch Environments)

It can be helpful to visualize the typical Inngest developer workflow using Branch environments and your platform's deploy previews:

Configuring Branch Environments

As Branch Environments are created on-demand, all of your Branch Environments share the same Event Keys and Signing Key. This enables you to use the same environment variables in each of your application's deployment preview environments and set the environment dynamically using the env option with the Inngest client:

const inngest = new Inngest({
  id: "my-app",
  env: process.env.BRANCH,
});
// Alternatively, you can set the INNGEST_ENV environment variable in your app

// Pass the client to the serve handler to complete the setup
serve({ client: inngest, functions: [myFirstFunction, mySecondFunction] });

Automatically Supported Platforms

The Inngest SDK tries to automatically detect your application's branch and use it to set the env option when deploying to certain supported platforms. Here are the platforms that are automatically supported and what environment variable is automatically used:

• Vercel - VERCEL_GIT_COMMIT_REF - This works perfectly with our Vercel integration.

You can always override this using INNGEST_ENV or by manually passing env to the Inngest client.

Other Platforms

Some platforms only pass an environment variable at build time. This means you'll have to explicitly set env to the platform's specific environment variable. For example, here's how you would set it on Netlify:

const inngest = new Inngest({
  id: "my-app",
  env: process.env.BRANCH,
});

• Netlify - BRANCH (docs)
• Cloudflare Pages - CF_PAGES_BRANCH (docs)
• Railway - RAILWAY_GIT_BRANCH (docs)
• Render - RENDER_GIT_BRANCH (docs)

Sending Events to Branch Environments

As all branch environments share Event Keys, all you need to do to send events to your branch environment is set the env option with the SDK. This will configure the SDK's send() method to automatically routes events to the correct environment.

If you are sending events without an Inngest SDK, you'll need pass the x-inngest-env header along with your request. For more information about this and sending events from any environment with the Event API, read the send() reference.

Archiving Branch Environments

By default, branch environments are archived 3 days after their latest deploy. Each time you deploy, the auto archive date is extended by 3 days. Archiving a branch environment doesn't delete anything; it only prevents the environment's functions from triggering.

If you'd like to disable auto archive on a branch environment, click the toggle in the environments page. There's also a button that lets you manually archive/unarchive branch environments at any time.

Disabling Branch Environments in Vercel

The recommended way to disable branch environments is through the Vercel UI. Delete the "Preview" Inngest environment variables:

Custom Environments

Many teams have shared environments that are used for non-production purposes like staging, QA, or canary. Inngest's Custom Environments are designed to give you and your team an isolated sandbox for every non-production environment that you deploy.

You can create an environment from the environments page in the Inngest dashboard.

Some key things to know about custom environments:

• Each environment has its own keys, event history, and functions. All data is isolated within each environment.
• You can deploy multiple apps to the same environment to fully simulate your production environment.
• You can create as many environments as you need.

Create an environment in the dashboard

Viewing and Switching Environments

In the Inngest dashboard you can quickly switch between environments in the environment switcher dropdown in the top navigation. You can click “View All Environments” for a high level view of all of your environments.