> For the complete documentation index, see [llms.txt](https://docs.hivel.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hivel.ai/hybrid-hivel-agent/8.-work-metrics-credentials-and-controls.md).

# 8. 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.

{% columns %}
{% column %} <a href="/hybrid-hivel-agent/7.-troubleshooting-and-security-notes.md" class="button primary" data-icon="backward">Troubleshooting</a>
{% endcolumn %}

{% column %}

{% endcolumn %}

{% column %} <a href="/hybrid-hivel-agent/9.-verification-and-summary.md" class="button primary" data-icon="forward">Verification & Summary</a>
{% endcolumn %}
{% endcolumns %}