---
title: "Governance Service Operations"
description: "Health checks, storage, upgrades, and troubleshooting guidance for Governance Service."
source: "Guardian Platform"
---
Operators should monitor Governance Service as part of the full Guardian Platform. User-facing issues often come from dependency problems, configuration mismatches, or missing permissions.

## Readiness Checks

Governance Service exposes a liveness probe, a readiness probe, and an authenticated probe that exercises the Auth Service token path. The readiness probe reports whether the service can reach the platform database; it does not check object storage, Integrity Service, or PDFGen.

Because readiness covers only the database, confirm the remaining dependencies separately: use the authenticated probe for Auth Service, and check object storage, Integrity Service, and PDFGen through their own health signals before declaring the deployment ready.

The liveness, readiness, and authenticated probes, the last with a sign-in token or API key:

```bash
curl https://guardian.example.com/governanceService/health
curl https://guardian.example.com/governanceService/health/ready
curl -H "Authorization: Bearer $GUARDIAN_API_KEY" \
  https://guardian.example.com/governanceService/health/auth
```

A ready response:

```json
{
  "status": "ready",
  "service": "governance-service",
  "database": "ok",
  "timestamp": "2026-10-16T12:00:00Z",
  "version": "1.2.1"
}
```

Readiness returns `503` with `"status": "not_ready"` when the database is unreachable. The authenticated probe returns `401` when Auth Service rejects the token or cannot be reached, and `"auth": "verified"` when the token path works. Token checks are cached for 30 seconds by default, so an Auth Service outage can take that long to show.

If readiness fails, check the deployment status and service logs before asking users to retry.

## Before Upgrades

Before upgrading, back up platform data, preserve current deployment values, and review release notes for migrations or behavior changes. Avoid starting an upgrade while large evidence imports, report generation, or credential workflows are in progress.

## Common Operational Symptoms

- Users cannot access projects, or every request returns `401`: check Auth Service health and membership assignments.
- Creating projects, creating or applying policies, or submitting declarations and reviews fails: check Integrity Service health and connectivity.
- Attachments fail: check object storage configuration and permissions, then Integrity Service.
- Credentials fail: check Integrity Service health and connectivity.
- Reports fail: "Failed to retrieve policy manifest" points at Integrity Service; "Failed to generate policy report" points at PDFGen; see [PDFGen Operations](../pdfgen/operations.mdx#common-operational-symptoms).
- Indicator evaluations do not appear: check the event integration, project context, and active indicator applications.
- Indicator-generated declarations, agent control reviews, or agent certifications fail: confirm `AUTH_SERVICE_API_KEY` is set and the `governance-worker` service account exists (check Auth Service startup logs).

## Escalation Information

When escalating, include the project, affected workflow, approximate time, user role, and whether the issue affects all users or a single project. Do not include sensitive attachment contents unless support explicitly requests them through an approved channel.

## Related

- [Governance Service Configuration](./configuration.mdx) — the dependencies Governance Service is configured with
- [Observability](../deployment/observability.mdx) — platform-wide signals to monitor
- [Upgrade](../deployment/upgrade.mdx) — the full platform upgrade process
- [Backup and Restore](../deployment/backup-and-restore.mdx) — what to back up before an upgrade and the order to restore it in
- [Deployment Troubleshooting](../deployment/troubleshooting.mdx) — first-line checks for sign-in, attachment, and indicator failures
- [Auth Service Operations](../auth-service/operations.mdx) — membership and authorization checks when users cannot access projects