Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

6. Troubleshooting & Security Notes

Troubleshooting

`validate` fails - source unreachable

  • Check the URL is correct and reachable from this machine

  • Check firewall allows outbound HTTPS to the source

  • For self-signed certs: add no_verify_ssl: true (Jira / GitLab) or skip_ssl_verification: true (GitHub / Bitbucket)

`validate` fails - Hivel API unreachable

  • Check outbound HTTPS to api.hivel.ai is allowed

  • Verify HIVEL_API_TOKEN is set and valid

Issues missing from Jira sync

  • Check earliest_issue_date - issues before this date are excluded

  • Test your issue_jql_filter in Jira's issue navigator first

Custom Jira field not appearing

  • Run config fields to find the correct field ID

  • Add to extra_fields in config

GitHub rate limiting

  • The agent proactively checks rate limits before each batch and sleeps until reset

  • Reduce concurrent_threads if you're seeing persistent throttling

Azure DevOps Server (on-prem) - PRs outside the requested date window

  • Older API versions (7.0) don't honor server-side date filtering - the agent works around this automatically, but confirm api_version matches your instance if PR counts look off

  • Double-check is_server: true and url point at the full collection URL (e.g. https://host/tfs/CollectionName), not just the host

Debug HTTP traffic

Security notes

  • Only metadata is sent to Hivel. No source code, file contents, attachments, or analytics data.

  • No hidden telemetry. The agent sends nothing beyond the metadata payload described in this document.

  • Agent logs are opt-in. Log streaming to Hivel is disabled by default (stream_logs: false). Enable only when working with Hivel support.

  • Config upload is opt-in. Disabled by default (send_agent_config: false). When enabled, all credential fields are replaced with *** before upload.

  • Credentials are never uploaded. Tokens and passwords never leave your network.

  • S3 upload uses short-lived presigned URLs issued by Hivel - the agent never holds S3 credentials.

  • All communication is over HTTPS/TLS.

  • No inbound connections for hivel-agent itself, it requires no open ports on the VM. The Claude OTel Collector is the one exception: if you enable it for Claude Code usage tracking, it requires inbound TCP 4317 (OTLP gRPC) and/or TCP 4318 (OTLP HTTP), see Claude OTel Settings.

Full config example

Work-metrics

Last updated