n8n-nodes-gcs-service-account

An n8n community node for downloading files from Google Cloud Storage using Service Account authentication instead of OAuth. Perfect for automated workflows and server-to-server applications.

🚀 Features

• 🔐 Service Account Authentication - Use JSON key files instead of OAuth
• 📥 Single File Download - Download specific files from your bucket
• 📦 Bulk Download - Download all files from bucket root directory
• 🎯 Prefix Filtering - Filter files by prefix when bulk downloading
• 🔄 n8n Integration - Seamless integration with n8n workflows
• ⚡ Production Ready - No token refresh issues, works 24/7
• 🛡️ Error Handling - Robust error handling with detailed feedback

📦 Installation

Via n8n Community Nodes (Recommended)

1. Open your n8n instance
2. Go to Settings → Community Nodes
3. Click Install a community node
4. Enter: n8n-nodes-gcs-service-account
5. Click Install

Manual Installation

npm install n8n-nodes-gcs-service-account

🔧 Setup

1. Create Google Cloud Service Account

1. Go to Google Cloud Console
2. Navigate to IAM & Admin → Service Accounts
3. Click Create Service Account
4. Assign these roles:
   • Storage Object Viewer (to read objects)
   • Storage Legacy Bucket Reader (to list buckets)
5. Create and download a JSON key file

2. Configure n8n Credentials

1. In n8n, go to Settings → Credentials
2. Click Add Credential
3. Select Google Service Account
4. Paste the complete JSON key file content
5. Save the credential

🎯 Operations

1. Download Single File

Download a specific file from your GCS bucket.

Parameters:

• Bucket Name: Name of your GCS bucket
• File Path: Path to the specific file (e.g., documents/file.pdf)
• Binary Property: Name for the output binary data (default: data)

2. Download All Files from Root

Download all files from the root directory of your bucket.

Parameters:

• Bucket Name: Name of your GCS bucket
• Prefix Filter: (Optional) Only download files starting with this prefix
• Max Files: Maximum number of files to download (default: 100)
• Binary Property: Name for the output binary data (default: data)

💡 Usage Examples

Example 1: Download a Single PDF File

{
  "operation": "downloadSingle",
  "bucketName": "my-documents",
  "filePath": "reports/monthly-report.pdf"
}

Example 2: Download All Files from Root

{
  "operation": "downloadAll", 
  "bucketName": "my-images",
  "maxFiles": 50
}

Example 3: Download Files with Prefix

{
  "operation": "downloadAll",
  "bucketName": "my-data",
  "prefix": "exports/",
  "maxFiles": 20
}

📊 Output Data

Single File Download

{
  "fileName": "monthly-report.pdf",
  "filePath": "reports/monthly-report.pdf", 
  "bucketName": "my-documents",
  "size": 2048576,
  "contentType": "application/pdf",
  "downloadedAt": "2024-01-01T12:00:00.000Z",
  "etag": "abc123",
  "updated": "2024-01-01T10:00:00.000Z",
  "operation": "downloadSingle"
}

Bulk Download

Each file creates a separate output item:

{
  "fileName": "image1.jpg",
  "filePath": "image1.jpg",
  "bucketName": "my-images", 
  "size": 1024000,
  "contentType": "image/jpeg",
  "downloadedAt": "2024-01-01T12:00:00.000Z",
  "etag": "def456",
  "updated": "2024-01-01T11:00:00.000Z",
  "operation": "downloadAll",
  "totalFiles": 5
}

🔍 Binary Data

Downloaded files are available as binary data in the specified property (default: data). You can:

• Save to disk using the Write Binary File node
• Send via email using Email nodes
• Upload elsewhere using HTTP Request or other storage nodes
• Process content using appropriate nodes based on file type

⚠️ Important Notes

• Permissions: Ensure your service account has Storage Object Viewer role
• File Limits: Bulk download is limited to prevent memory issues (default: 100 files)
• Large Files: Very large files may cause memory issues - consider using streams for production
• Billing: Downloads count towards your GCS egress charges

🐛 Troubleshooting

Authentication Errors

• Verify your service account JSON is complete and valid
• Check that the service account has proper GCS permissions
• Ensure the bucket exists and is accessible

File Not Found

• Verify the file path is correct (case-sensitive)
• Check that the file exists in the specified bucket
• Ensure you have read permissions on the file

Memory Issues

• Reduce maxFiles parameter for bulk downloads
• Process files in smaller batches
• Consider file size limits in your n8n instance

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT © Gabriel Lacanna

🙏 Credits

• Built for the n8n community
• Uses Google Cloud Storage SDK

Need help? Open an issue or check the n8n community forum.