Concepts

This page explains the building blocks of OpsNexus and how they relate. Each concept links to the page that covers it in detail.

#The big picture

Organization ── users, teams & groups, roles, settings, plugins, backups, audit log
 │
 ├─ Project "Default" ── pipelines & builds, integrations, cloud accounts, clusters, servers,
 │                       monitoring, domains, artifacts, private agents, private secrets & variables
 ├─ Project "Payments" ── ...
 │
 └─ Shared with every project ── build agents, secrets & variables,
                                 notification channels, rules & summaries, plugins

#Organization

One OpsNexus installation holds one organization. It is created on the first start from BOOTSTRAP_ORG_NAME, together with the first admin user, the built-in roles and a project named Default.

People, teams, roles, organization settings (such as the password policy and SSO), backups and the audit log belong to the organization, not to a project.

#Projects

A project is the unit of isolation. It owns the work: pipelines and builds, integrations, cloud accounts and resources, Kubernetes clusters, servers, monitoring, domains, artifacts, and its own private build agents, secrets and variables. People in one project cannot see another project's data.

• Create and manage projects under Settings → Projects with New project.
• Each project has a name and a Key, a short ID used in URLs and the API.
• The project you work in is chosen in the app. Every page shows data for the active project.

Some things can be shared with every project instead of belonging to one:

• Build agents
• Secrets & variables
• Notification channels, rules & summaries
• Plugins

A project secret may reuse the name of a shared secret. Inside that project, the project's own secret wins.

#Users, teams and groups

A user is a person who signs in, with a password or with Google or Microsoft single sign-on. Users are managed under Settings → Access control (tabs Users, Roles & permissions and Teams & groups).

A team or group collects users. A team can have a role, and its members get that role's permissions in addition to their own.

A user can also hold API keys (an access key and a secret) to call the API from scripts. API keys are created under Password, MFA & SSO. See API.

#Roles and module permissions

OpsNexus uses role-based access control (RBAC). A role gives an access level for each module:

The modules are: Dashboards & reports, CI/CD pipelines, Integrations, Build agents, Cloud accounts & resources, Artifacts, Tools marketplace, Monitoring & alerts, Notifications, Domains & SEO, Security findings, Secrets & variables, Users, roles & teams, Organization settings, Backup & restore, and Audit logs.

Every organization starts with five built-in roles:

A user's effective level for a module is the highest level among their own role and the roles of their teams. Access is denied by default. Super admins, such as the first admin, have full access everywhere.

#Project roles

Inside a project, each member (a person or a whole team) has a project role:

Organization admins (super admins, or anyone with full on Users, roles & teams) are admins of every project. Organization-level modules, such as users, settings and the audit log, always follow the person's organization role.

See Access control.

#Environments

An environment is a label such as dev, staging or prod. OpsNexus uses it in several places:

• Variables are stored per environment, or for all environments. A pipeline reads ${{ vars.KEY }} for its environment and falls back to the all-environments value.
• Pipelines and stages can set an environment, and a stage can be limited to certain environments with when.
• Integrations are tagged with an environment.
• Notification rules can be limited to one environment.
• Infra designer stacks have an environment.

Environments are not a separate object you create. They are the labels you use on these items. See Secrets and variables and Pipeline syntax.

#Build agents

A build agent is a small program (onx_agent.py) that runs on a Linux, Windows or macOS machine, or in Docker. It:

• sends a heartbeat with host health to OpsNexus every 15 seconds over HTTPS;
• when it has executors above 0, takes pipeline runs and runs their steps;
• runs Terraform for Infra designer deployments.

Agents register with a single-use registration token (onx_reg_...) created in Build agents. Pipelines pick agents by labels. An agent can belong to one project or be shared with every project. An agent that stops reporting becomes disconnected and later offline.

See Build agents.

#Integrations

An integration connects OpsNexus to an external CI/CD tool: Jenkins, GitLab, Azure DevOps, Argo CD or GitHub Actions. OpsNexus imports its pipelines and recent builds on a schedule.

Integrations are read-only by default. To trigger or cancel builds in the external tool, turn on Allow write actions on the integration, and the user also needs modify on CI/CD pipelines.

See Integrations.

#Secrets and variables

A secret is a credential: a cloud access key, a tool token, an SSH password and so on. Secret values are stored in HashiCorp Vault. The database keeps only the secret's name, type and path. Values are never returned in API lists, logs or audit details. Revealing a value needs full on Secrets & variables, and is recorded in the audit log.

Pipelines use secrets as ${{ secrets.NAME }}. Secret values are masked in build output.

A variable is a plain, non-secret value per environment. A variable can point at a secret with vault:<credential ID> instead of holding the value.

See Secrets and variables.

#Audit log

Every sign-in, change, deployment and secret access is written to the audit log. Each entry is hash-chained to the previous one, so tampering is detectable. You can filter the log and select Export CSV.

See Audit logs.

#How they relate