Skip to main content
Each recipe includes the problem, solution code, and rationale. The examples use the V2 syncer signatures from Building connectors.

Parent-child hierarchies

Problem: Model resources that exist within other resources, such as projects in organizations or repositories in orgs. Solution:
Why: Parent-child relationships let the SDK scope List calls to a parent, and they let C1 show access in context. See Modeling hierarchies for paging through children.

Display name fallbacks

Problem: Make sure every resource has a human-readable name. Solution:
Why: Empty display names break UIs and access reviews. Reviewers can’t approve access to a blank name.

Resource attributes

Problem: Record a resource’s status, profile, and description. Solution: Set status and profile on the resource, and keep user-specific data in the trait options:
Why: Status, profile, icon, and created time are attributes of the resource itself. The older trait-level options for them, such as WithStatus, are deprecated. Use WithResourceStatus, WithResourceProfile, WithResourceIcon, and WithResourceCreatedAt instead. For group and role resources, pass nil for the trait options, or the options you need.

Error handling

Wrap errors with context

Problem: Make errors traceable to their source. Solution:
Why: The connector name makes it clear which connector produced the error. The %w verb preserves the error chain for errors.Is and errors.As, and it keeps any gRPC status code on the wrapped error, which the SDK uses to decide whether to retry.

Let the SDK retry transient errors

Problem: Rate limits and temporary outages shouldn’t fail a whole sync. Solution: Return an error that carries a gRPC Unavailable or DeadlineExceeded status. The SDK retries only those two codes. Any other error, including a plain fmt.Errorf or a custom error type, has no status code and stops the sync. If you make API calls with uhttp, you get this for free. It maps HTTP statuses to gRPC codes: 429, 502, 503, 504, and most other 5xx responses become Unavailable, 408 becomes DeadlineExceeded, 401 becomes Unauthenticated, 403 becomes PermissionDenied, and 404 becomes NotFound. Return the error and the SDK does the rest:
If you use another HTTP client, map transient failures to a status yourself:
uhttp.WrapErrors(codes.Unavailable, message, err) builds an error with a status code and keeps the original error in the chain. Why: Retrying only on Unavailable and DeadlineExceeded keeps permanent failures, such as bad credentials, from retrying forever. For fatal errors, return a clear message so users can fix the configuration:

Check context cancellation in loops

Problem: Respect timeouts and cancellation in long-running operations. Solution:
Why: A cancelled context means “stop now.” Ignoring it wastes resources and can cause timeouts in later operations.

Anti-patterns

Don’t buffer entire datasets

Don’t swallow errors

Don’t log sensitive data

Don’t mix resource types in grants