Settings overview

Overview

Settings is where every workspace-wide configuration surface lives. It's not a single page — it's a sidebar of grouped sub-pages that swap into the same shell when you navigate, so you can move between sections without losing context. The route is /ws/{slug}/settings; opening it from the main sidebar takes you to Workspace by default.

The Settings sidebar replaces the main app sidebar while you're under /settings/*, with a Back to workspace button pinned at the top so you can leave at any moment. Sub-pages render their own headers — there's no duplicated "Settings" banner above the content.

Why it exists

Earlier Vigilo versions scattered configuration across the main nav (Integrations, Members, Roles…). The result was a top-level sidebar that grew unmanageable and a configuration story split between "stuff you do daily" and "stuff you set once". Settings collapses all the set-once surfaces into one place with a curated taxonomy. Day-to-day work — Changes, Incidents, Certificates — stays in the main sidebar; everything else lives here.

Groups in the Settings sidebar

The earlier Advanced group was retired — its items (roles, freeze / maintenance windows, SCIM, custom fields) moved into the topical group each one actually belongs to, so the sidebar reads as a flat taxonomy without an "everything else" bucket. The earlier top-level Members nav entry also moved into Settings → Access; the legacy /ws/<slug>/members URL redirects to /ws/<slug>/settings/members so existing bookmarks keep working.

Common workflows

1. Brand the workspace

1. Settings → General → Workspace.
2. Set the display name, logo URL, primary colour, and portfolio tags (the chips used by the platform overview rollup).
3. Save. The new branding appears in the top bar within a few seconds.

2. Configure outbound email for alerts

1. Settings → Reliability → SMTP.
2. Enter host, port, credentials, From address. Click Send test email.
3. On success, save. Future alert rule fires use this profile rather than the platform default.
4. See SMTP configuration for the full security story (CMEK encryption at rest, key rotation).

3. Add a chat/issue-tracker integration

1. Settings → Infrastructure → Integrations.
2. Pick the integration kind (Slack, Jira, Linear, PagerDuty, GitHub, Teams).
3. Paste the credentials. The save dialog shows a •••• redaction immediately — the plaintext value never round-trips to the database.
4. See Outbound integrations for the full configuration model.

4. Lock down access by IP

1. Settings → Identity → IP allowlist.
2. Add CIDR ranges one per line. The save action warns you if your current source IP is outside the list (so you can't accidentally lock yourself out) — confirm only if you're sure.
3. Loopback addresses are always allowed in dev mode.

5. Bump audit retention before an audit cycle

1. Settings → Compliance → Audit retention.
2. Set the retention window in days. 0 or blank means "keep forever".
3. The audit nightly sweep archives anything older than the window into a separate AuditLogArchive table — the sweep is reversible until a separate purge job runs.

6. Roll a SCIM token for IdP provisioning

1. Settings → Identity → SCIM tokens.
2. Click + New token, give it a label.
3. The plaintext token is shown once in a copy-to-clipboard dialog. Paste it into your IdP (Okta, Azure AD) immediately — it's not retrievable again.
4. To rotate, mint a new token and revoke the old one. Existing provisioning calls fail-fast after revocation so you can detect cutover.

7. Add a custom field to changes or incidents

1. Settings → General → Custom fields.
2. Pick the target entity (ChangeRequest, Incident, Task, Asset, Project).
3. Choose a field type (text, number, date, select, multi-select) and label. Set it required or optional.
4. The field appears on the corresponding create/edit form within a few seconds. Historical rows show an empty value until edited.

8. Set the workspace's OpenAI key for the AI assistant

1. Settings → General → AI assistant.
2. Paste your OpenAI API key (starts with sk-). The masked input has a show/hide toggle. CMEK-encrypted at rest; the read endpoint only ever returns whether a key is configured, not the value itself.
3. Status badge reflects the resolution order: workspace key configured > platform default (env var) > not configured (assistant returns retrieved sources without synthesised answers).
4. Remove workspace key clears the workspace override and falls back to the platform default.

Permissions

The Settings sidebar itself is visible only to roles whose Members permission includes the relevant scope — Viewers and Engineers don't see entries they can't act on.

Troubleshooting

A Settings sub-page is missing from the sidebar. Confirm your role. Settings groups hide entire entries when the active user can't view them; the sidebar shows the items you actually have access to.

I can't get out of Settings mode. Click the Back to workspace row pinned at the top of the Settings sidebar. It deep-links to the workspace's last main route.

A change I made on a Settings page doesn't appear elsewhere. Most Settings changes propagate on the next request the affected feature makes — the cache is short. If you've just changed an IP allowlist or session policy, log out and back in to confirm the new value takes effect.

Related articles

• Members and invitations — who can use the workspace.
• Roles and permissions — what each role can do.
• Outbound integrations — Slack, Jira, Linear, PagerDuty, GitHub, Teams.
• SAML and SSO — IdP login setup.
• SCIM provisioning — automated user lifecycle.