Skip to content

Commit 6f5e73d

Browse files
author
baton-admin[bot]
committed
chore: update baton-admin doc files
1 parent a0f60af commit 6f5e73d

File tree

2 files changed

+198
-0
lines changed

2 files changed

+198
-0
lines changed

‎.claude/skills/connector/INDEX.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ Skills for building and reviewing ConductorOne Baton connectors.
2323
| `build-provisioning.md` | Grant/Revoke implementation, idempotency, AccountManager |
2424
| `build-config.md` | Configuration schema, CLI flags, environment variables |
2525
| `build-connector-docs.md` | Writing connector documentation (MDX format, capabilities, credentials, setup tabs) |
26+
| `fix-ci-checks.md` | Fixing CI failures: doc freshness, lint, test, version mismatches |
2627

2728
### Patterns (Best Practices)
2829

@@ -76,6 +77,9 @@ Skills for building and reviewing ConductorOne Baton connectors.
7677
**"How do I write/update connector docs?"**
7778
- `build-connector-docs.md` - MDX template, capabilities tables, credential sections, setup tabs
7879

80+
**"CI is failing on my PR"**
81+
- `fix-ci-checks.md` - Fixes for doc freshness, lint, test, and version mismatch failures
82+
7983
### User is reviewing connector code
8084

8185
**"Is this PR safe to merge?"**

‎.claude/skills/connector/fix-ci-checks.md‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
---
2+
name: fix-ci-checks
3+
description: Fix CI check failures in a connector repo. Covers doc freshness (Generate Baton Metadata), lint and test failures (Verify), and version mismatches (Check versions). Run this when any managed CI workflow fails on your PR.
4+
---
5+
6+
# Fix CI Checks
7+
8+
Fix CI failures on connector PRs. This skill covers the three managed CI workflows: Generate Baton Metadata, Verify, and Check versions.
9+
10+
## Generate Baton Metadata failures
11+
12+
### Docs not matching metadata
13+
14+
**When**: The `Generate Baton Metadata` workflow step `Verify docs match current metadata` fails with "docs/connector.mdx was not updated."
15+
16+
**Cause**: Your code changes altered the connector's capabilities or config schema, but `docs/connector.mdx` wasn't updated to match.
17+
18+
**Fix**:
19+
20+
1. Build the connector and regenerate metadata into the root files:
21+
22+
```bash
23+
CONNECTOR_NAME=$(ls cmd/ | head -1)
24+
go build -o connector "./cmd/${CONNECTOR_NAME}"
25+
./connector capabilities > baton_capabilities.json
26+
./connector config > config_schema.json
27+
```
28+
29+
2. Check what changed:
30+
31+
```bash
32+
git diff baton_capabilities.json
33+
git diff config_schema.json
34+
```
35+
36+
3. Update `docs/connector.mdx` based on what changed. Each type of metadata change maps to a specific doc section:
37+
38+
| What changed | Doc section to update |
39+
|-|-|
40+
| Resource types added/removed | Capabilities table (AUTO-GENERATED) |
41+
| Sync/provision support changed | Capabilities table (AUTO-GENERATED) |
42+
| Config fields added/removed/renamed | Config params step (AUTO-GENERATED) |
43+
| New required OAuth scopes | "Gather credentials" section |
44+
| Permission level changed | "Gather credentials" section |
45+
| New auth method (e.g., added OAuth) | "Gather credentials" section |
46+
| New BatonActionSchema definitions | "Connector actions" section |
47+
| Action arguments changed | "Connector actions" section |
48+
49+
4. For auto-generated sections, find the marker comments and update the content between them:
50+
51+
```
52+
{/* AUTO-GENERATED:START - capabilities */}
53+
...update capabilities table here...
54+
{/* AUTO-GENERATED:END - capabilities */}
55+
```
56+
57+
```
58+
{/* AUTO-GENERATED:START - config-params */}
59+
...update config params here...
60+
{/* AUTO-GENERATED:END - config-params */}
61+
```
62+
63+
#### Capabilities table format
64+
65+
Read `baton_capabilities.json`. The `resourceTypeCapabilities` array lists each resource type and its capabilities. Generate a table:
66+
67+
```mdx
68+
| Resource | Sync | Provision |
69+
| :--- | :--- | :--- |
70+
| Accounts | <Icon icon="square-check" iconType="solid" color="#65DE23"/> | <Icon icon="square-check" iconType="solid" color="#65DE23"/> |
71+
| Groups | <Icon icon="square-check" iconType="solid" color="#65DE23"/> | |
72+
```
73+
74+
- Checkmark: `<Icon icon="square-check" iconType="solid" color="#65DE23"/>`
75+
- No capability: leave cell empty
76+
- Map type names: `user` -> `Accounts`, `group` -> `Groups`, `role` -> `Roles`
77+
78+
#### Config params format
79+
80+
Read `config_schema.json`. The `properties` object has field definitions, `required` array marks required fields:
81+
82+
```mdx
83+
<Step>
84+
Enter the required configuration:
85+
86+
- **api-key** (required): API key for authentication
87+
- **domain** (required): Your instance domain
88+
- **include-inactive**: Include inactive users in sync
89+
</Step>
90+
```
91+
92+
5. Stage the metadata files and docs, then push:
93+
94+
```bash
95+
git add baton_capabilities.json config_schema.json docs/connector.mdx
96+
```
97+
98+
### Build failures in metadata workflow
99+
100+
**When**: The `Generate Baton Metadata` workflow fails at the `Build` step.
101+
102+
**Fix**: The connector binary must compile. Fix build errors first — they'll show in the workflow logs. Common causes:
103+
- Missing vendored dependencies: run `go mod vendor`
104+
- Syntax errors in new code
105+
- Incompatible SDK version
106+
107+
## Verify workflow failures
108+
109+
### Lint failures
110+
111+
**When**: The `Verify / lint` job fails.
112+
113+
**Fix**: Run the linter locally and fix reported issues:
114+
115+
```bash
116+
golangci-lint run --timeout=6m
117+
```
118+
119+
Common issues:
120+
- `errcheck`: unchecked error return — add `if err != nil` handling
121+
- `govet`: struct field alignment or printf format issues
122+
- `goimports`: import ordering — run `goimports -w .`
123+
- `revive`: naming conventions — check exported names follow Go conventions
124+
- `gosec`: security issues — review and fix or add `//nolint:gosec` with justification
125+
126+
### Test failures
127+
128+
**When**: The `Verify / test` job fails.
129+
130+
**Fix**: Run tests locally:
131+
132+
```bash
133+
go test -v -mod=vendor ./...
134+
```
135+
136+
If tests need credentials or a running service, check if the connector supports `--base-url` for mock server testing.
137+
138+
## Check versions failures
139+
140+
`.versions.yaml` is managed by baton-admin. Never edit it directly in a connector repo. To change Go version, SDK version, or other dependency versions:
141+
142+
1. Open a PR on `baton-admin` updating the connector's config in `connectors.yaml` (the `versions` section)
143+
2. Merge that PR — baton-admin pushes the updated `.versions.yaml` to the connector repo
144+
3. Rebase your connector PR onto the updated main
145+
4. Fix any breaking changes from the new SDK/Go version in your PR
146+
147+
### .versions.yaml edited directly
148+
149+
**When**: The `Check versions / block-versions-yaml-edits` job fails with ".versions.yaml is managed by baton-admin and must not be edited in PRs."
150+
151+
**Fix**: Revert the change. If you need different versions, update them via baton-admin (see above).
152+
153+
```bash
154+
git checkout origin/main -- .versions.yaml
155+
```
156+
157+
### Go or SDK version mismatch
158+
159+
**When**: The `Check versions / verify-versions-match` job fails with a version mismatch (e.g., "Go version mismatch: .versions.yaml expects 1.25.2, but go.mod has 1.24.0").
160+
161+
**Cause**: Your `go.mod` doesn't match `.versions.yaml` on main. This happens when baton-admin updated versions after you branched.
162+
163+
**Fix**: Rebase onto the latest main to pick up the version update, then fix any breaking changes:
164+
165+
```bash
166+
git fetch origin
167+
git rebase origin/main
168+
```
169+
170+
If the rebase introduces conflicts in `go.mod` or `go.sum`, resolve them:
171+
172+
```bash
173+
go mod tidy
174+
go mod vendor
175+
```
176+
177+
If the new SDK or Go version introduces breaking changes in your code, fix them as part of your PR.
178+
179+
## If docs/connector.mdx doesn't exist
180+
181+
If your connector doesn't have `docs/connector.mdx` yet, create it using the `build-connector-docs` skill which has the full template structure and writing standards.
182+
183+
## If AUTO-GENERATED markers don't exist
184+
185+
If `docs/connector.mdx` exists but doesn't have the `AUTO-GENERATED` marker comments, add them around the capabilities table and config params step:
186+
187+
```mdx
188+
{/* AUTO-GENERATED:START - capabilities
189+
Generated from baton_capabilities.json. Do not edit manually. */}
190+
191+
...capabilities section...
192+
193+
{/* AUTO-GENERATED:END - capabilities */}
194+
```

0 commit comments

Comments
 (0)