docs: add guide for using external secret references

[Aaron ("AJ") Steers (aaronsteers)]

Summary

Adds a new guide (docs/guides/secret_references.md) documenting how to use the secret_coordinate:: prefix when configuring connectors via Terraform. This allows users with a custom secret storage configured to reference secrets in their external secret manager (AWS SM, GCP SM, Azure Key Vault, etc.) instead of passing raw values.

Covers:

• How the secret_coordinate:: prefix works
• Example using the generic airbyte_source resource with jsonencode()
• Reading back coordinates via include_secret_coordinates = true
• Prerequisites and link to the companion Airbyte docs

A corresponding template file (templates/guides/secret_references.md.tmpl) is included so that the guide survives the docs-generate pipeline (which regenerates docs/ from templates/).

Companion PR: airbytehq/airbyte#73672 (adds the main secret_coordinate:: documentation to docs.airbyte.com)

Updates since last revision

• Added templates/guides/secret_references.md.tmpl to fix the "Verify Docs Are Up-to-Date" CI check, which was deleting the manually-added guide during doc generation.

Review & Testing Checklist for Human

• Verify the secret coordinate format: The guide states users pass the secret name after the prefix (e.g., secret_coordinate::my-pg-password). Confirm this is correct — is it the secret name, a full path, or an ARN? This was inferred from code reading of SecretsHelpers.kt, not end-to-end testing. This is the highest-risk item.
• Cross-link validity: The guide links to https://docs.airbyte.com/platform/understanding-airbyte/secrets#external-secret-references and .../enterprise-flex/external-secrets, both of which are being added in the companion PR (docs: add external secret references documentation for secret_coordinate:: prefix airbyte#73672). Ensure those land before or alongside this PR.
• Plan availability language: Currently says "contact your Airbyte representative" for Cloud setup without specifying which plans support custom secret storages. Confirm this is acceptable or if it should mention Enterprise-only.

Suggested test plan: Have someone with a workspace that has custom secret storage configured attempt to create a source via Terraform using the secret_coordinate:: prefix pattern shown in the guide, and verify the secret resolves correctly.

Notes

• The Terraform example uses the generic airbyte_source resource with jsonencode() (v1.0+ pattern), consistent with the v1 migration guide.
• The exact behavior of what the platform expects after secret_coordinate:: (secret name vs. full coordinate path) is the highest-risk item — this was derived from code analysis of SecretsHelpers.kt, not from runtime testing.
• Both docs/guides/secret_references.md and templates/guides/secret_references.md.tmpl must stay in sync. The CI "Verify Docs Are Up-to-Date" check enforces this.

Link to Devin run: https://app.devin.ai/sessions/94c36f482f634314936fea1261ad61e3
Requested by: Aaron ("AJ") Steers (@aaronsteers)

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[github-actions]

Thanks for opening this pull request!

Your contribution is appreciated. Here are some helpful tips and resources.

💡 Show Tips and Tricks

Terraform Example Commands

• /tf-examples project=pre-1.0 action=plan - Run terraform plan on the pre-1.0 example project
• /tf-examples project=1.0 action=plan - Run terraform plan on the 1.0 example project
• /tf-examples project=all action=plan - Run terraform plan on all example projects
• /tf-examples project=pre-1.0 action=apply - Apply terraform changes to the pre-1.0 example project
• /tf-examples project=pre-1.0 action=destroy - Destroy terraform resources in the pre-1.0 example project

📚 Show Repo Guidance

About This Repository

This repository uses Speakeasy to generate the Terraform provider from the Airbyte OpenAPI specification. The CI will automatically build the provider, validate code generation, and run acceptance tests across Terraform versions 1.0-1.4.

Note: This is a generated codebase. Direct modifications to generated files are not accepted - changes must be made to the upstream OpenAPI spec.

📝 Edit this welcome message.