Environment Variables

You can add environment variables within each project's settings.

Forgetting environment variables is the most common reason why builds fail. If your tests run locally but not within Chipper CI, missing environment variables are the most likely cause.

These get set as server/system level environment variables - they are not added to your .env file.

Team Environment Variables

You can set team-wide environment variables within your team settings. This is useful for things like shared keys or common configurations you use across all projects.

Team-level environment variables are set on every build in each project within that team. If the same environment variable is defined on the project-level, the project-level environment variable takes precedence and overwrites the team-level environment variable.

Project Environment Variables

Each project can also have their own set of environment variables. Environment variables at the project-level take precedence over team-level variables.

By default, Chipper CI sets just one environment variable on new projects:

TELESCOPE_ENABLED=false

Telescope will attempt to connect to Redis if it is enabled. This will cause errors if you are not using Redis within Chipper CI.

Disallowed Environment Variables

As said before, project environment variables do not create a .env file in your project. You're expected to create one during your build (if needed).

The following project environment variables are not saved if added/uploaded to the project environment section:

# These should be set in your .env file
APP_NAME
APP_ENV
APP_KEY
APP_DEBUG
APP_URL

# Chipper CI sets these automatically if a DB is used
DB_CONNECTION
DB_HOST
DB_PORT
DB_DATABASE
DB_USERNAME
DB_PASSWORD

# Chipper CI sets these if Redis is used
REDIS_HOST
REDIS_PASSWORD
REDIS_PORT

# These use "${PUSHER_APP_KEY}" format, which can be set
# in the .env file if needed
MIX_PUSHER_APP_KEY
MIX_PUSHER_APP_CLUSTER

Extra Build Environment Variables

Chipper CI will also set the following environment variables for each build:

CI_COMMIT_SHA="The build commit sha"
CI_COMMIT_SHA_SHORT="The short version of the commit sha"
CI_COMMIT_BRANCH="The branch the commit resides within"
CI_COMMIT_TAG="The tag the commit resides within, empty if not a tag"
CI_COMMIT_MESSAGE="The commit message for the commit"
CI_CLONE_URL="The URL being used to clone the repository"
CI_COMMIT_USER="The username who pushed the commit"

Environment Precedence

Environment variable precedence can be ~annoying af~ complicated.

Regular Tests

When running regular tests (phpunit, pest), environment precedence goes in the following order (most precedent to least):

phpunit.xml:
- Variables from phpunit.xml take precedence if defined via <server> elements (Laravel 8 and older defaults)
System:
- System environment variables (as set within Project Environment settings)
- These override items in phpunit.xml if they are defined within <env> elements inside of phpunit.xml (Laravel 9+ defaults)
.env.testing:
- Variables from .env.testing (if exists and assuming APP_ENV=testing)
.env:
- Variables from .env

Environment variables set within your phpunit.xml file take precedence over all other environment variables in Laravel 8 and older.

However, system environment variables will take precedence over items defined in phpunit.xml in Laravel 9 and newer.

This is related to the use of <server> vs <env> to set environment variables. Read here for more details.

Dusk (Browser) Tests

When running Dusk tests, we've found that the order changes.

.env.dusk.testing:
- Variables from .env.dusk.testing (if exists and assuming APP_ENV=testing)
.env:
- Variables from .env

That's it! System environment variables and items from phpunit.xml are ignored in Dusk tests.

This means you need to be careful in your Dusk tests - for example, you may need to create a .env.dusk.testing file that includes database/redis connection details (as documented here):

DB_HOST=mysql
DB_USERNAME=chipperci
DB_DATABASE=chipperci
DB_PASSWORD=secret

REDIS_HOST=redis