Authenticating the Server

Authenticating the server requires Service Account Credentials or Application Default Credentials.


At the time of writing, Google’s process for managing authentication in their SDKs is somewhat intractable, with difficult to navigate guidance and varying practices implemented and recommended across the platform. It is very easy to leak credentials as a result, so please take care.

However, there are some promising developments currently happening (like Workload Identify Federation and Service Account Impersonation) so we hope that soon it’ll be much easier to have a single workflow for this. In the meantime it’s worth following this guy.

A major issue in particular for storage is that we need the ability to sign files in GCS, which either requires a dedicated service account with the full key available (no longer recommended by google), or requires additional calls to a google-hosted API, significantly slowing any interaction requiring signed URLs.

If you’re not using media storage - only tasks/events and static (public) storage - this should not be an issue and you can use service account impersonation, federation or ADCs as appropriate.

Create a service account

In most cases, the default service accounts are not sufficient to read/write and sign files in GCS, so you will need to create a dedicated service account:

On GCP infrastructure

  • This library will attempt to read the credentials provided when running on google cloud infrastructure.

  • Ensure your service account is being used by the deployed GCR / GKE / GCE instance.


Default Google Compute Engine (GCE) Service accounts are unable to sign urls.

On GitHub Actions

You may need to use the library on infrastructure external to Google like Github Actions - for example running collectstatic within a GitHub Actions release flow.

You’ll want to avoid injecting a service account json file into your github actions if possible, so you should consider Workload Identity Federation which is made pretty easy by these glorious github actions.


We’re working on using service account impersonation, but it’s not fully available for all the SDKs yet, still a lot of teething problems (like this one, solved 6 days ago at the time of writing).

So you should totally try that (please submit a PR here to show the process if you get it to work!!). In the meantime…

  • Create the key and download your-project-XXXXX.json file.


It’s best not to store this in your project, to prevent accidentally committing it or building it into a docker image layer. Instead, bind monut it into docker images and devcontainers from somewhere else on your local system.

If you must keep within your project, it’s good practice to name the file gha-greds-<whatever>.json and make sure that gha-creds-* is in your .gitignore and .dockerignore files.

  • If you’re developing in a container (like a VSCode .devcontainer), mount the file into the container. You can make gcloud available too - check out this tutorial.

  • Set an environment variable of GOOGLE_APPLICATION_CREDENTIALS to the path of the json file.