Setup & Reference
Everything you need to connect your tools, understand the concepts, and get accurate team intelligence from day one.
Quick start
Three steps take you from a new workspace to live team intelligence. Steps 1–3 are required; everything else is optional and can be added at any time.
Register and name your organization. One workspace per engineering team. The person who creates it becomes the owner — the only role that can add integrations and manage billing.
Point TeamEye at your company /teameye service: host, path, machine token. GitLab PATs and Kubernetes tokens stay on that service. Jira, Sentry and leave sources are optional add-ons.
After the first pull, TeamEye lists people from the company data service. Select the teammates whose operational signals should appear in your management view. Nobody is included automatically.
Once you've completed these three steps, the daily intelligence engine activates automatically — no further configuration needed. Jira, absence integrations, and Ask AI are additive layers you can enable later.
Key concepts
Lenses
TeamEye organizes signals into four independent lenses. Each lens can be active or inactive depending on which integrations you've connected. A bad or missing lens never degrades another.
| Lens | Source | What it measures |
|---|---|---|
| Engineering Activity | GitLab via company data | Commit rhythm, merge request flow, review activity, collaboration patterns and workload changes |
| Delivery | Jira optional | Issue throughput, cycle time, story points delivered, flow health — gated by Data Trust score |
| Reliability | Sentry optional | Error volume, new issues, severity levels and timing across your projects — read live, never your code or event payloads |
| Availability | Google Calendar / Microsoft 365 / BambooHR optional | Approved leave and Out-of-Office windows; used to suppress false alerts while someone is away |
Visible teammates
A visible teammate is a person whose operational engineering metadata is included in TeamEye reports. They are selected explicitly by a workspace owner and can see the same data used for their profile.
Plan tiers are based on engineering team size, not per-seat billing. You can add or remove visible teammates from Setup → People.
If the same person has GitLab and Jira accounts, link them by email in the Jira people picker. Linked identities let delivery and engineering activity data appear together on their profile page.
Data Trust score
The Data Trust score (0–100) measures how usable a Jira project's data actually is. TeamEye audits five hygiene rules and weights them into a single score.
Assignee coverage
What share of In-Progress issues have an assignee.
Estimate coverage
What share of open issues have a story point estimate.
Freshness
Issues not updated in ≥ 14 days count against this rule.
Flow
Issues stuck In-Progress for ≥ 7 days count against this rule.
Resolution
Done issues marked Cancelled / Declined / Won't Fix don't count as delivered.
A score below 60 (the default threshold) puts the project in hygiene report mode: delivery numbers won't be used in operational risk summaries until the data is reliable enough. The hygiene findings themselves are still visible — you can see what's dragging the score down and fix it. The threshold is configurable via the TEAMEYE_JIRA_TRUST_MIN environment variable.
Excused absences
When a visible teammate is on approved leave (confirmed by Google Calendar, Microsoft 365, or BambooHR), their status is set to Excused. While excused:
- No low-activity or availability-related risk signals are generated during approved leave
- Their absence window is shown on their profile and in daily digest summaries
- Operational activity is interpreted with availability context, so planned absence is not treated as a risk
Tentative/pending leave events are not treated as excused by default. Enable them with TEAMEYE_ABSENCE_INCLUDE_TENTATIVE=true if your team approves leave retroactively.
Company data
GitLab and Kubernetes credentials never land in TeamEye. You run a /teameye service in your environment. TeamEye only stores the host, path and a machine token, then reads GET /config and /drivers/*.
People, infrastructure, deploys and releases all arrive through this one connection. There is no GitLab PAT field and no Kubernetes token field on the default setup path.
Setup steps
/teameye service
Deploy it in your environment. Put the GitLab PAT, Kubernetes ServiceAccount token and cluster CA on that service — not in TeamEye.
Go to Setup → Company data. Enter the host (e.g. https://teameye.example.com), path (default /teameye) and the machine token. Click connect. TeamEye probes GET /config before saving.
The first pull lists people from the service. Check who should appear in management views. You can change this later from People.
Parameters
| Field | Required | Description |
|---|---|---|
| Host | Required | Public URL of your company service, e.g. https://teameye.example.com. No trailing slash. |
| Path | Optional | Defaults to /teameye. TeamEye calls {host}{path}/config and {host}{path}/drivers/{id}. |
| Machine token | Required | Bearer token for the facade. Not a GitLab PAT. Stored encrypted, scoped to this workspace. |
What stays on your side
- GitLab Personal Access Token
- Kubernetes ServiceAccount token and cluster CA
- Any other credentials the company service uses to talk to GitLab or the cluster
TeamEye never asks for those on this form. If GitLab is behind a firewall, that is fine: the company service talks to GitLab. TeamEye only needs to reach the company service.
Legacy GitLab PAT
Workspaces that do not run a company service yet can still paste a GitLab token in Setup. That path stores the PAT in TeamEye. Prefer company data — once it is connected, the GitLab token card is hidden.
GitLab signals
GitLab provides the Engineering Activity lens: commits, merge requests and review flow. Those signals arrive through company data. TeamEye does not store a GitLab token on the default path.
What data is read
- Group and member lists (names, usernames, email addresses)
- Commit timestamps and counts per author per day
- Merge Request open/merge/close events and review activity
- Nothing from private message contents, wikis, or issue descriptions
The company service talks to GitLab with read-only scopes. TeamEye never creates, edits or deletes anything in your GitLab.
Jira integration
Jira adds the Delivery lens — throughput, cycle time, and a Data Trust hygiene audit. It adds delivery planning context and is analyzed independently from Git activity, so weak Jira hygiene is visible instead of silently corrupting management conclusions.
Only Atlassian Cloud Jira is supported. Jira Server / Data Center is not currently available.
Setup steps
Log in to id.atlassian.com, go to Security → API tokens → Create API token. The account must be a regular Jira member — it does not need project-admin rights.
Go to Setup → Connect Jira. Enter your Jira site URL, the account email that owns the token, and the token itself.
Pick which Jira projects to sync. Only issues in selected projects appear in delivery reports and hygiene audits.
Match Jira account IDs to your existing visible teammates. Matching is attempted automatically by email; any unmatched accounts can be linked manually.
Parameters
| Field | Required | Description |
|---|---|---|
| Jira site URL | Required | Your Atlassian Cloud domain. Format: https://acme.atlassian.net. Include the https:// prefix and no trailing slash. |
| Account email | Required | The Atlassian account the API token belongs to. Used as the Basic Auth username in all API calls. |
| API token | Required | Token from id.atlassian.com → Security → API tokens. Format: ATATT3xFfGF0…. Stored encrypted, never shared across workspaces. |
Data Trust thresholds
Delivery numbers only feed into operational risk summaries when a project's Data Trust score is at or above 60 (default). Below that, the hygiene audit findings are still shown so you can see exactly which rules are dragging the score down.
The audit only looks at tasks created in the last month — old backlog is ignored so it can't drag the score around. These thresholds tune the individual rules:
| Parameter | Default | Meaning |
|---|---|---|
| TEAMEYE_JIRA_WINDOW_DAYS | 30 | How far back the audit looks. Only tasks created within this window are scored; set 0 to audit everything. |
| TEAMEYE_JIRA_UNASSIGNED_GRACE_DAYS | 7 | An active (In Progress or sprint) task may sit unassigned this long before it counts against hygiene. Backlog is ignored. |
| TEAMEYE_JIRA_IN_PROGRESS_MAX_DAYS | 14 | An "In Progress" task that hasn't moved within this many days counts as stuck. |
| TEAMEYE_JIRA_TESTING_MAX_DAYS | 3 | A task parked in a testing/QA status longer than this many working days (Mon–Fri) counts as piling up. |
| TEAMEYE_JIRA_TESTING_STATUSES | Testing, In Testing, QA, … | Status names treated as "in testing" (comma-separated). A status your board doesn't have is simply skipped. |
| TEAMEYE_JIRA_TRUST_MIN | 60 | Trust score below which delivery data is excluded from operational risk summaries. |
| TEAMEYE_JIRA_DELIVERY_DAYS | 30 | Rolling window (days) used when calculating throughput and cycle time. |
Excluded done statuses
Issues closed as Cancelled, Won't Do, Duplicate, etc. should not inflate throughput. By default, TeamEye excludes the following status names from the delivered count:
Cancelled · Canceled · Won't Do · Won't Fix · Won't fix · Duplicate · Rejected · Declined · Abandoned · Obsolete
If your board uses different wording, override with the TEAMEYE_JIRA_EXCLUDED_DONE_STATUSES environment variable (comma-separated, case-sensitive to your Jira status names).
Story points custom field
Atlassian Cloud assigns a unique custom field ID to story points per instance (commonly customfield_10016, but not guaranteed). Without this configured, TeamEye counts issues instead of summing points — throughput still works, the points column stays blank.
To find your field ID: open any Jira issue that has points, press ? to open keyboard shortcuts, then navigate to … → View issue in XML and search for customfield_ next to the story points value. Set TEAMEYE_JIRA_STORY_POINTS_FIELD=customfield_XXXXX.
What data is read
- Project keys and names
- Issue status, assignee, created/updated/resolved timestamps
- Story point estimates (if field is configured)
- Issue type and resolution — no issue descriptions or comments
Sentry integration
Sentry powers the Reliability lens — a live view of what's breaking across your projects: error volume, new issues, severity and timing. It's completely optional, read-only, and never touches your source code or event payloads.
Works with both Sentry SaaS (sentry.io) and self-hosted Sentry. Unlike the other integrations, reliability stats are read live from the Sentry API and cached for a few minutes — there's no nightly sync and no local copy of your error data.
Setup steps
On sentry.io, go to Settings → Auth Tokens (an organization token is recommended) or User settings → Auth Tokens. Self-hosted Sentry uses the same path. Grant the scopes org:read, project:read and event:read.
It's the path segment in your Sentry URL: sentry.io/organizations/acme-inc/. Self-hosted instances use the same /organizations/{slug}/ path.
Go to Setup → Connect Sentry. Enter your Sentry URL, the organization slug and the auth token, then click Connect and view stats. TeamEye probes /organizations/{slug}/ to validate the credentials before saving.
Parameters
| Field | Required | Description |
|---|---|---|
| Sentry URL | Required | Defaults to https://sentry.io. For self-hosted, set your instance root, e.g. https://sentry.acme.com. No trailing slash. |
| Organization slug | Required | The slug from your Sentry URL (sentry.io/organizations/acme-inc/). |
| Auth token | Required | Token from Sentry's Auth Tokens page. Format: sntrys_…. Stored encrypted, never shared across workspaces. |
Required scopes
The auth token needs three read-only scopes:
org:read— resolves the organization and validates the connectionproject:read— lists your projectsevent:read— reads aggregate error statistics (counts, levels, timing)
No write scopes are ever needed. TeamEye never creates, edits, or resolves anything in Sentry.
What data is read
- Project list (names and slugs)
- Error / event counts over a trailing window, as a timeseries
- New-issue counts and the top issues leaderboard
- Severity levels and timing — never event payloads, stack-trace source, or your code
Tuning
Reliability tuning is controlled by environment variables (sensible defaults shown):
| Parameter | Default | Meaning |
|---|---|---|
| TEAMEYE_SENTRY_ENABLED | true | Hard kill-switch for the whole lens, independent of any per-workspace connection. |
| TEAMEYE_SENTRY_STATS_DAYS | 14 | Trailing window (days) the stats dashboard covers — drives the event timeseries and the new-issues tile. |
| TEAMEYE_SENTRY_TOP_ISSUES | 25 | How many top issues to pull for the leaderboard. |
| TEAMEYE_SENTRY_CACHE_TTL | 600 | How long (seconds) the assembled dashboard payload is cached. Keeps refreshes cheap while staying current enough for a manager view. |
Google Calendar integration
Reads Out-of-Office events for your Google Workspace users so TeamEye knows when someone is officially away and can suppress false alerts.
How it works
TeamEye uses a Google service account with domain-wide delegation (DWD). The service account impersonates a Workspace admin to enumerate per-user OOF event types and dates. No event titles, descriptions, or attendees are ever read.
Setup steps
In console.cloud.google.com, open IAM & Admin → Service Accounts → Create service account. Enable the Google Calendar API for the project.
On the service account, click Edit → Show advanced settings → Enable Google Workspace Domain-wide Delegation. Copy the Client ID shown below the checkbox.
In admin.google.com → Security → Access and data control → API controls → Domain-wide delegation → Manage domain-wide delegation, add the Client ID with this OAuth scope:https://www.googleapis.com/auth/calendar.readonly
On the service account page, go to Keys → Add key → Create new key → JSON. Save the downloaded file — it contains the private key.
Go to Setup → Connect Google Calendar. Paste the full JSON key content, enter a delegated admin email, and optionally a shared leave calendar ID.
Parameters
| Field | Required | Description |
|---|---|---|
| Service account JSON key | Required | Full JSON content from Google Cloud → IAM → Service Accounts → Keys → Add key → JSON. Paste the entire file, including the outer { }. Stored encrypted at rest. |
| Delegated admin email | Required | A Google Workspace admin account (e.g. admin@acme.com) that the service account will impersonate. Must have read access to user calendars. |
| Shared leave calendar ID | Optional | If your org maintains a shared OOF / Leave calendar, add its calendar ID here (format: c_xxxxx@group.calendar.google.com). Found in Google Calendar → calendar settings → Calendar ID. |
Microsoft 365 integration
Reads Out-of-Office calendar blocks and auto-reply date ranges via the Microsoft Graph API. Requires an Azure App Registration with admin consent.
Setup steps
In portal.azure.com, go to Azure Active Directory → App registrations → New registration. Name it (e.g. "TeamEye"), leave Redirect URI blank, and click Register.
Under API permissions → Add a permission → Microsoft Graph → Application permissions, add:
Calendars.Read and MailboxSettings.Read.
Then click Grant admin consent — this requires Global Admin rights.
Under Certificates & secrets → New client secret, set an expiry and click Add. Copy the Value column (not the Secret ID) — it's shown only once.
Go to Setup → Connect Microsoft 365 and enter the Tenant ID, Application (client) ID, and client secret value.
Parameters
| Field | Required | Description |
|---|---|---|
| Tenant ID | Required | Your Azure AD Tenant ID (GUID). Found at Azure Portal → Azure Active Directory → Overview → Tenant ID. Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. |
| Application (client) ID | Required | The App Registration's Application ID. Found at App registrations → your app → Overview. Same GUID format as Tenant ID. |
| Client secret | Required | The secret Value (not the Secret ID). Shown only at creation time. Stored encrypted; only the secret value — not the ID — is used for token exchange. |
Client secrets expire. When your secret expires TeamEye will stop reading absence data and will surface a disconnected state in Setup. Renew the secret in Azure before it expires and update the value in TeamEye.
BambooHR integration
Pulls approved time-off requests for your team members so TeamEye never fires false alerts when someone is officially on leave. The simplest absence integration — two fields, no admin console required.
Setup steps
Log in to BambooHR, click your avatar in the top right, then API Keys → Add New Key. Name it (e.g. "TeamEye") and copy the key. A read-only key is sufficient.
Go to Setup → Connect BambooHR. Enter your BambooHR subdomain and the API key.
Parameters
| Field | Required | Description |
|---|---|---|
| Subdomain | Required | The part before .bamboohr.com in your BambooHR URL. If you access BambooHR at acme.bamboohr.com, enter acme. |
| API key | Required | Generated in BambooHR → your avatar → API Keys. Stored encrypted at rest. We only call /v1/time_off/requests?status=approved. |
Matching logic
TeamEye matches BambooHR employees to visible teammates by work email address. If an employee's email in BambooHR matches a visible teammate's email in TeamEye, their approved leave days are automatically marked as Excused.
If the emails don't match (different domains, aliases), the coverage report in Setup will show the employee as unmatched. Fix this by ensuring the email in BambooHR matches the one used in GitLab, or by manually linking the person in TeamEye.
Roles & permissions
TeamEye has two roles: Owner and Member. One workspace can have multiple members but currently only one owner.
| Capability | Owner | Member |
|---|---|---|
| View dashboard, reports, people | ✓ | ✓ |
| Use Ask AI chat | ✓ | — |
| Connect / disconnect integrations | ✓ | — |
| Add / remove visible teammates | ✓ | — |
| Invite or remove members | ✓ | — |
| Manage billing | ✓ | — |
| Delete organization | ✓ | — |
| View delivery (Jira) reports | ✓ | ✓ |
| Run Jira hygiene audit manually | ✓ | — |
| View reliability (Sentry) stats | ✓ | — |
Invites are sent by email from Setup → Team. The invited person must register or log in; they land in the same organization automatically once they accept the invite link.
FAQ
Do I need Jira to use TeamEye?
No. TeamEye starts from company data (GitLab activity via your /teameye service). Jira adds delivery flow and planning context. If Jira is not connected, or if its Data Trust score is too low, TeamEye simply excludes Jira-based delivery signals from operational summaries.
Can the same person appear in multiple workspaces?
Yes — a user account can belong to multiple organizations, each with its own visible teammates, integrations, and billing. Switching between them is done via the organization switcher in the app shell.
My Jira Data Trust score is below 60. What do I do?
Open Delivery → Hygiene. The audit lists every project with its score breakdown by rule. The most common fixes: assign In-Progress issues, add story point estimates, and move stale issues forward or close them. Once the score crosses the threshold, delivery data will appear in the next nightly sync.
How often does data sync?
Most integrations sync nightly (once per day, EU time). Absence syncs cover a 30-day lookback and 60-day lookahead window by default. You can trigger a manual Jira hygiene run from the Hygiene page; GitLab and absence syncs cannot be triggered manually.
Sentry is the exception — reliability stats are read live from the Sentry API on demand and cached for about 10 minutes, so there's no nightly Sentry sync and figures may lag Sentry by up to that cache window.
Is there a way to exclude certain GitLab groups or projects?
Exclusion happens at the people level, not the group level. If you don't want someone included, deselect them in the people picker. TeamEye only stores metadata for selected visible teammates. Activity from people who are not selected is ignored.
What happens when someone leaves the team?
Remove them from Setup → People. Their historical operational data can remain available for reports, but they stop appearing in future daily briefings and risk summaries.
Where are credentials stored?
GitLab PATs and Kubernetes tokens never leave your company /teameye service. TeamEye stores only the host, path and a machine token for that service. Optional tools (Jira, Sentry, leave) keep their own API tokens encrypted at rest in your workspace. Credentials are never shared across workspaces and are never logged or sent to third parties.
How do I disconnect an integration?
Go to Setup and click Disconnect next to the relevant integration. All stored credentials for that integration are deleted immediately. Historical data synced before disconnection is retained.
Still have questions? Contact us — we typically reply the same business day.