WIP: OpenAI connector doc draft and index entries #21
Conversation
📝 WalkthroughWalkthroughThis pull request introduces OpenAI connector documentation to the Baton project. A new documentation page describing the OpenAI connector is added, along with corresponding index updates to make the connector discoverable across multiple documentation sections and the connector catalog. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In @baton/openai.mdx:
- Around line 35-37: The link under the "OpenAI Admin Key" section points to an
inaccessible Admin API docs URL; update the markdown link target for the OpenAI
Admin Key reference (the line containing the [View the documentation] anchor) to
the correct public API keys docs URL (for example replace the href with
https://platform.openai.com/docs/api-keys) so the documentation link is
accessible.
🧹 Nitpick comments (4)
baton/_release-notes.mdx (1)
6-6: Clarify the purpose of this comment.The JSX comment
{/* OpenAI */}appears orphaned and isn't associated with any specific release note entry. Given the PR is marked WIP and notes "Do not merge until OpenAI connector is out of catalog validation," this may be a placeholder for a future announcement.Consider either:
- Removing this comment until the connector is ready to be announced
- Moving it to the appropriate release note section where OpenAI will be featured
- Adding a TODO comment to clarify its purpose
baton/intro.mdx (1)
317-317: Verify the category placement is appropriate.OpenAI is categorized under "Collaboration and productivity" alongside tools like Asana, Slack, Notion, and Zoom. While OpenAI can be used for productivity, it's primarily an AI/ML platform. Consider whether a different category might be more appropriate, such as:
- Developer tools (where AI coding assistants might fit)
- A dedicated AI/ML category if more AI connectors are planned
That said, if OpenAI is being positioned for its ChatGPT Enterprise/Teams collaboration features, the current placement may be appropriate.
baton/openai.mdx (2)
133-150: Consider clarifying the boolean value for BATON_PROVISIONING.In the Kubernetes Secret's
stringDatasection,BATON_PROVISIONING: trueis set as a string value. While Kubernetes will handle this correctly, for clarity consider:
- Adding a comment explaining that this should be the string
"true"or omitted if provisioning is not desired- Confirming whether the connector expects the string
"true"or a boolean valueAlso, ensure the configuration variable names match what the actual connector expects.
💡 Suggested improvement for clarity
# Optional: include if you want ConductorOne to provision access using this connector - BATON_PROVISIONING: true + BATON_PROVISIONING: "true" # Set to "true" to enable provisioning, or omit this line to disable
177-177: Avoid using the:latesttag in production deployments.The deployment manifest uses
ghcr.io/conductorone/baton-openai:latest, which is not recommended for production environments because:
- The
:latesttag can change unexpectedly, leading to inconsistent deployments- It makes rollbacks difficult
- It's harder to track which version is running
Consider pinning to a specific version tag (e.g.,
v1.0.0) once the connector is released from beta.📌 Recommended approach
containers: - name: baton-openai - image: ghcr.io/conductorone/baton-openai:latest + image: ghcr.io/conductorone/baton-openai:v1.0.0 # Replace with specific version imagePullPolicy: IfNotPresentAdditionally, when using a specific version tag, you can change
imagePullPolicytoAlwaysif you want to ensure the image is pulled on each deployment, or keepIfNotPresentfor better performance with pinned versions.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
baton/_release-notes.mdxbaton/intro.mdxbaton/openai.mdxdocs.json
🔇 Additional comments (6)
docs.json (1)
365-365: LGTM!The OpenAI connector entry is correctly placed in alphabetical order in the connector library navigation.
baton/intro.mdx (2)
191-192: LGTM!The OpenAI connector is correctly positioned alphabetically in the A-Z list between OneLogin and OpenSearch.
273-273: LGTM!Adding OpenAI to the "New this month" section is appropriate for a newly introduced connector.
baton/openai.mdx (3)
9-13: LGTM!The beta warning is clear and appropriate, setting proper expectations for users about the connector's maturity level while encouraging feedback.
15-28: LGTM!The capabilities table is clear and comprehensive, properly documenting what resources can be synced and provisioned. The additional functionality note about account provisioning/deprovisioning is helpful.
48-201: LGTM!The dual deployment options (cloud-hosted and self-hosted) are well-documented with clear step-by-step instructions. The structure is consistent with other connector documentation and provides users with comprehensive guidance for both deployment methods.
| - OpenAI Admin Key | ||
|
|
||
| See the OpenAI docs for information on how to acquire credentials: [View the documentation](https://platform.openai.com/docs/api-reference/administration) |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# Check if the file exists and read the relevant lines
if [ -f "baton/openai.mdx" ]; then
echo "=== File exists ==="
sed -n '35,37p' baton/openai.mdx | cat -n
else
echo "File not found at baton/openai.mdx"
# Try to find similar files
find . -name "*openai*" -type f 2>/dev/null | head -20
fiRepository: ConductorOne/docs
Length of output: 276
🏁 Script executed:
# Test the URL accessibility
curl -I -L -s -o /dev/null -w "HTTP Status: %{http_code}\n" "https://platform.openai.com/docs/api-reference/administration"Repository: ConductorOne/docs
Length of output: 77
🌐 Web query:
OpenAI Admin Key documentation API reference
💡 Result:
OpenAI’s Admin API Keys reference (endpoints, object schema, and curl examples) is in the API docs: it covers listing organization/project admin API keys, creating keys (POST), retrieving a key (GET), and deleting a key (DELETE), plus the Admin API key object fields (id, name, redacted_value, value, created_at, last_used_at, owner). Example endpoints and curl samples are shown in the docs. [1]
Additional Admin/API audit and Admin API usage guidance (who can create/use admin keys, audit logging notes) is in the Help Center. [2]
Sources:
- OpenAI API Reference — Admin API Keys (endpoints, object schema, examples). [1]
- OpenAI Help Center — Admin and Audit Logs / Admin API guidance. [2]
Fix the inaccessible OpenAI documentation link.
The documentation link at line 36 returns HTTP 403 Forbidden and is not publicly accessible. Update to the correct, accessible URL for OpenAI's Admin API Key documentation.
🤖 Prompt for AI Agents
In @baton/openai.mdx around lines 35 - 37, The link under the "OpenAI Admin Key"
section points to an inaccessible Admin API docs URL; update the markdown link
target for the OpenAI Admin Key reference (the line containing the [View the
documentation] anchor) to the correct public API keys docs URL (for example
replace the href with https://platform.openai.com/docs/api-keys) so the
documentation link is accessible.
Do not merge until OpenAI connector is out of catalog validation.
Summary by CodeRabbit
New Features
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.