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 and select File
  3. Configure:
    • Name: Identifier for the secret
    • Value: File contents (max 4KB)
    • Mount Path: Where the file appears in your environment (e.g., /home/gitpod/.ssh/id_rsa)
New secret dialog with File type showing name, value, and mount path fields
The mount path 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 - just read it like any file.

​
Update a file secret

  1. Navigate to Project → Secrets or Settings → Secrets
  2. Click Edit, update the value, click Save
Edit file secret dialog with the value field for updating file contents
New environments get the updated content. Running environments need a restart to pick up changes.