Skip to main content
File secrets mount sensitive data as files in your environment. They’re created automatically when your environment starts, so applications (and agents) can read them like any other file.

​
When to use file secrets

Use file secrets for:
  • Certificates and keys - TLS certificates, SSH keys, service account credentials
  • Config files - JSON configurations, kubeconfig, cloud provider configs
  • Multi-line content - Anything that doesn’t fit in an environment variable
Agents often need file secrets for SSH keys (Git operations), service account JSON files (cloud access), or config files that MCP servers expect at specific paths.

​
Create a file secret

  1. Navigate to Project → Secrets or Settings → Secrets
  2. Click New Secret, then choose File from the Secret type dropdown
  3. Configure:
    • Name: Identifier for the secret
    • Secret: File contents (max 10KB)
    • File Location: Where the file appears in your environment (e.g., /home/gitpod/.ssh/id_rsa)
New secret dialog with File type showing name, secret, and file location fields The file location cannot be changed after creation.

​
Access the file

The file is automatically available at your specified path: 
cat /home/gitpod/.config/gcloud/application_default_credentials.json
No special code needed. Read it like any file.

​
Update a file secret

  1. Navigate to Project → Secrets or Settings → Secrets
  2. Click Edit, update the value, click Update
Updated content is automatically propagated to running environments (within 2 minutes). The file at the mount path is updated in place.