# Google Cloud Storage
To use [Google Cloud Storage](https://cloud.google.com/storage/), you need to set
the `SCCACHE_GCS_BUCKET` environment variable to the name of the GCS bucket.
By default, SCCACHE on GCS will be read-only. To change this, set `SCCACHE_GCS_RW_MODE`
to either `READ_ONLY` or `READ_WRITE`.
You can also define a prefix that will be prepended to the keys of all cache objects
created and read within the GCS bucket, effectively creating a scope. To do that
use the `SCCACHE_GCS_KEY_PREFIX` environment variable. This can be useful when
sharing a bucket with another application.
## Credentials
Sccache is able to load credentials from various sources. Including:
- User Input: If `SCCACHE_GCS_KEY_PATH` has been set, we will load from this file
first.
- Service accounts JSONs
- External accounts JSONs
- [Task Cluster](https://taskcluster.net/): If `SCCACHE_GCS_CREDENTIALS_URL` has
been set, we will load token from this url first.
- Static: `GOOGLE_APPLICATION_CREDENTIALS`
- Well-known locations:
- Windows: `%APPDATA%\gcloud\application_default_credentials.json`
- macOS/Linux:
- `$XDG_CONFIG_HOME/gcloud/application_default_credentials.json`
- `$HOME/.config/gcloud/application_default_credentials.json`
- VM Metadata: Fetch token will the specified service account.
### Service accounts
To create such account, in GCP, go in `APIs and Services` => `Cloud Storage` =>
`Create credentials` => `Service account`. Then, once created, click on the account
then `Keys` => `Add key` => `Create new key`. Select the JSON format and here it
is. This JSON file is what `SCCACHE_GCS_KEY_PATH` expects.
The service account needs `Storage Object Admin` permissions on the bucket
(otherwise, sccache will fail with a simple `Permission denied`).
### External accounts
Such accounts require creating a [Workload Identity Pool and Workload Identity Provider].
This approach allows the environment (Azure, Aws, or other OIDC providers like Github)
to create a temporary service account grant without having to share a service account
JSON, which can be pretty powerful. An example on how to create such accounts is
[Google's guide on how to use it with Github].
After generating the external account JSON file, you may pass its path to `SCCACHE_GCS_KEY_PATH`.
Service accounts used by the pool must have `Storage Object Admin` permissions on
bucket as well.
## Verifying it works
To verify that it works, run:
```
export SCCACHE_GCS_BUCKET=<bucket name in GCP>
export SCCACHE_GCS_KEY_PATH=secret-gcp-storage.json
./sccache --show-stats
# you should see
[...]
Cache location GCS, bucket: Bucket(name=<bucket name in GCP>), key_prefix: (none)
```
## Deprecation
`SCCACHE_GCS_OAUTH_URL` have been deprecated and not supported, please use `SCCACHE_GCS_SERVICE_ACCOUNT` instead.
[Workload Identity Pool and Workload Identity Provider]: https://cloud.google.com/iam/docs/manage-workload-identity-pools-providers
[Google's guide on how to use it with Github]: https://cloud.google.com/blog/products/identity-security/enabling-keyless-authentication-from-github-actions