7. Work-metrics, Credentials & Controls
The work-metrics command and local git clones
Work-metrics is a separate, optional command from the regular sync. It classifies commits and merged pull requests into work-type categories (new work / rework / maintenance / assistance) and computes line-count totals. You run it on its own schedule; if you never run it, none of the below applies.
For GitHub and GitLab, this classification is done entirely through each platform's REST blame API - no local repository copy is ever made.
For Bitbucket Cloud and Azure DevOps, neither platform exposes a blame API or a merged-PR diff API. To compute the same classification, the agent performs a local `git clone` of the relevant repository onto the disk of the machine running the agent - i.e., onto your own infrastructure, using the same credentials already configured for that provider.
What this means concretely:
The clone is bounded - by default a shallow clone of the last 30 commits (configurable via clone_depth/clone_since_days/clone_mode), not a full history mirror.
The clone is written to a local cache directory on the agent host (default /var/hivel/repo_cache), under your own disk and OS-level access controls. It is not a network transfer to Hivel. This cache is persistent and reused across runs, not wiped after each work-metrics invocation - repo copies remain on disk between runs until you clean up that directory yourself.
Blame and diff computation happen locally, against that local clone, using standard git operations.
Only the resulting aggregate numbers - a per-commit work-type classification and per-PR added/removed line totals - are uploaded. The cloned repository itself, its blame output, and any diff text produced during this local computation are never transmitted anywhere.
In short: for Bitbucket and Azure DevOps, work-metrics temporarily reconstructs part of a repository locally, on hardware you control, purely to compute a number, and only that number leaves the machine.
Credential handling
Credentials live in a local .env file that you create and control. It is never committed to source control by the agent's own tooling, and its values are substituted into config.yml at runtime via ${VAR_NAME} references.
If a referenced credential variable is missing, the agent fails immediately at startup - there is no silent fallback or degraded-but-running mode.
Credentials are used only to authenticate outbound calls to the corresponding tool (Jira, GitHub, etc.) and to Hivel. They are never included in the metadata upload payload.
Hivel-managed credentials (optional): for every provider (Jira, GitHub, GitLab, Bitbucket, Azure DevOps), you may choose to omit the source-system token from your own config entirely and instead have the agent fetch it from Hivel at startup. This is a deliberate alternative credential model - choosing it means you are trusting Hivel to hold that source-system credential on your behalf, rather than holding it yourself. It is off unless you opt into it; the default is that you supply and hold your own tokens.
Optional features that affect what leaves your network
All three of the following are off by default. None activate without you explicitly setting them in config.yml or passing a flag.
send_agent_config (default: off)
Uploads a sanitized copy of your config.yml to Hivel on every run, to help support diagnose configuration issues. Sanitization is applied in code, not by convention - the following fields are always overwritten with *** before upload: the Hivel API token, every configured Jira token and password, every GitHub/GitLab/Azure DevOps token, and the Bitbucket token *and* email address. Everything else in the config (URLs, filters, field mappings, instance names) is uploaded in clear text, since it contains no secrets.
Note: The Jira email field is not redacted (only token/password are). It is a company email address, not a credential, but flag this if your policy treats email addresses as data that shouldn't leave your environment even in a diagnostic payload.
stream_logs (default: off)
Streams the agent's own operational logs (what it's doing, timing, errors) to Hivel in real time for support purposes. Off unless explicitly enabled.
--debug-requests (local file only, but handle with care)
This flag writes a debug.log file to local disk - it is never uploaded or transmitted anywhere by the agent itself. It exists purely to let you inspect raw HTTP traffic when diagnosing a connectivity problem.
Be aware of exactly what it contains: it is a full dump of each HTTP request and response, including headers. That means it does contain your Authorization header in plaintext - the same bearer token / PAT / basic-auth credential configured for that provider. Treat debug.log as a sensitive credential-bearing file: don't attach it to a support ticket, Slack message, or email without first stripping the Authorization: header lines yourself. If you need to share it for troubleshooting, share it over a channel you'd trust with the underlying token, or redact those lines first.
PII and text redaction controls
Available per source-system config block (GitHub, GitLab, Bitbucket, Azure DevOps):
Setting
Effect
redact_names_and_urls
Replaces display names and URLs with deterministic redacted-0001-style placeholders. The same person always maps to the same placeholder, so assignment patterns ("who did what, when") are preserved for analytics while identities are hidden.
strip_text_content
Strips all free text (commit messages, PR/MR titles and bodies, review comments) entirely. Only structural identifiers (issue keys, IDs, timestamps, status transitions, numeric fields) remain. Cycle time, velocity, and flow metrics still function correctly with this enabled.
Jira additionally supports:
Setting
Effect
gdpr_active
Applies GDPR-safe handling of Jira user data. Auto-detected and enabled for *.atlassian.net (Jira Cloud); must be set explicitly for Jira Server/Data Center instances running in GDPR strict mode.
required_email_domains / is_email_required
Restricts which Jira users are synced by email domain, or drops users with no email address entirely.
These settings can be combined, and can be applied selectively per configured instance.
Last updated