From 069eb937f384606802c58006ca8997e22c0a19d0 Mon Sep 17 00:00:00 2001 From: Matt Van Horn <455140+mvanhorn@users.noreply.github.com> Date: Tue, 28 Apr 2026 03:22:22 -0700 Subject: [PATCH 1/2] docs(files): document STORAGE__CREDENTIALS for GCS Closes #324. The GCS storage driver passes any extra storage__* env var through to @google-cloud/storage's Storage() constructor. Inline service-account credentials work because that constructor accepts a 'credentials' option, but the option was completely undocumented; users had to read the api/src/storage/register-locations.ts + packages/storage-driver-gcs source to discover it. Adds a CREDENTIALS row to the GCS table with: - explanation of when to prefer it over KEY_FILENAME (managed platforms that inject secrets as env vars and don't give you a writeable filesystem), - the json: syntax prefix users hit when guessing (and which is the only way to get a JSON value through Directus's env parser), - a copy-paste example, - explicit note that KEY_FILENAME and CREDENTIALS are mutually exclusive, - a link to the Environment Syntax Prefix section. Tone-of-voice: imperative, no em dashes, no marketing language; matches CLAUDE.md guidance. --- content/configuration/files.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/content/configuration/files.md b/content/configuration/files.md index fa21b62d8..3f269c962 100644 --- a/content/configuration/files.md +++ b/content/configuration/files.md @@ -57,10 +57,19 @@ Based on your configured drivers, you must also provide additional variables, wh ### Google Cloud Storage (`gcs`) -| Variable | Description | Default Value | -| --------------------------------- | ---------------------------- | ------------- | -| `STORAGE__KEY_FILENAME` | Path to key file on disk. | | -| `STORAGE__BUCKET` | Google Cloud Storage bucket. | | +| Variable | Description | Default Value | +| --------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------- | +| `STORAGE__KEY_FILENAME` | Path to a service-account JSON key file on disk. | | +| `STORAGE__CREDENTIALS` | Service-account JSON credentials passed inline. Use the `json:` syntax prefix (see example below). | | +| `STORAGE__BUCKET` | Google Cloud Storage bucket. | | + +Use `STORAGE__CREDENTIALS` when you can't (or don't want to) write the key file to disk, for example when you're running Directus on a managed platform that injects secrets as environment variables. The value must be the full service-account JSON, prefixed with `json:` so Directus parses it as an object instead of a string. See [Environment Syntax Prefix](/configuration/intro#environment-syntax-prefix) for details on the prefix. + +``` +STORAGE_GCS_CREDENTIALS="json:{\"type\":\"service_account\",\"project_id\":\"...\",\"private_key\":\"...\",\"client_email\":\"...\"}" +``` + +`KEY_FILENAME` and `CREDENTIALS` are mutually exclusive. Pick one. ### Azure (`azure`) From 50ab0b5d04260ca7be2cc2e73a922227c45077ae Mon Sep 17 00:00:00 2001 From: daedalus <44623501+ComfortablyCoding@users.noreply.github.com> Date: Tue, 16 Jun 2026 11:46:24 -0400 Subject: [PATCH 2/2] adjustments --- content/configuration/files.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/content/configuration/files.md b/content/configuration/files.md index 270fd1295..df031bb4d 100644 --- a/content/configuration/files.md +++ b/content/configuration/files.md @@ -58,19 +58,19 @@ Based on your configured drivers, you must also provide additional variables, wh ### Google Cloud Storage (`gcs`) -| Variable | Description | Default Value | -| --------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------- | -| `STORAGE__KEY_FILENAME` | Path to a service-account JSON key file on disk. | | -| `STORAGE__CREDENTIALS` | Service-account JSON credentials passed inline. Use the `json:` syntax prefix (see example below). | | -| `STORAGE__BUCKET` | Google Cloud Storage bucket. | | +| Variable | Description | Default Value | +| ---------------------------------------------- | ------------------------------------------------------------------------------- | ------------- | +| `STORAGE__KEY_FILENAME` | Path to a service account key file on disk. | | +| `STORAGE__CREDENTIALS`[1] | Service account JSON credentials provided inline. Must be prefixed with`json:`. | | +| `STORAGE__BUCKET` | Google Cloud Storage bucket. | | -Use `STORAGE__CREDENTIALS` when you can't (or don't want to) write the key file to disk, for example when you're running Directus on a managed platform that injects secrets as environment variables. The value must be the full service-account JSON, prefixed with `json:` so Directus parses it as an object instead of a string. See [Environment Syntax Prefix](/configuration/intro#environment-syntax-prefix) for details on the prefix. +[1] Use this when a key file is unavailable or impractical, such as on platforms that inject secrets through environment variables. The value must contain the full service account JSON and be prefixed with `json:` so Directus parses it as an object rather than a string. See [Environment Syntax Prefix](/configuration/intro#environment-syntax-prefix) for details. -``` +```env STORAGE_GCS_CREDENTIALS="json:{\"type\":\"service_account\",\"project_id\":\"...\",\"private_key\":\"...\",\"client_email\":\"...\"}" ``` -`KEY_FILENAME` and `CREDENTIALS` are mutually exclusive. Pick one. +`STORAGE__KEY_FILENAME` and `STORAGE__CREDENTIALS` are mutually exclusive. Configure only one. ### Azure (`azure`)