System configuration

Understanding the configuration screen

Select Administration in the navigation bar, then Configuration, to change OpsChain's global settings - the values every project, environment and asset falls back to unless it sets its own.

The sections are listed down the left of the screen, grouped under Node, Project, Notifications, Security and System. The screen opens on Node settings. Type in Search in config to find a section by its name or by the settings it holds.

Above the sections, Configuration reference opens the configuration guides on the documentation site, and Switch to advanced mode replaces the sections with a JSON editor for the whole settings document - see editing the settings as JSON.

Each setting the screen edits is described in the settings reference or the additional settings guide. The settings managed by the deployment are changed in your values.yaml file instead, and are not editable here.

Access is controlled by the /system_configuration resource path. Without permission to change the settings, the fields are read-only and Save changes is unavailable.

Saving your changes

Sections with fields save only their own settings: select Save changes before moving to another section, or Discard to put back the saved values. Discard appears once you have changed a field. Changes apply as soon as they are saved.

Notification settings, Vault settings, CA certificates, Maintenance mode, Banners and API Cache have no Save changes button. Each action in them - adding a channel, uploading a certificate, turning on maintenance mode - takes effect when you confirm it.

Node

Node settings

The defaults every project, environment and asset inherits, and can override in its own settings.

Field	Function
Requires approval from	The Users and Groups whose approval every change needs, unless overridden. See requires_approval_from.
Repo folder	The folder in the Git repository that OpsChain properties are imported from when running a change. See repo_folder.
Pod per change step	When on, OpsChain creates one pod for each change step; when off, a single pod runs the whole change. See pod_per_change_step.
Include Git history	Whether the .git directory, with the full commit history, is included in the repository tarball supplied to a custom step runner Dockerfile build. See include_git_history.
Remove change worker pod	When on, OpsChain removes a change's worker pod once the change finishes. Turn it off temporarily to keep the pod for debugging. Applies only when Pod per change step is off.
Enable MintModel debug	Adds phase output to the MintModel generation response, and the MintPress context and asset properties to the MintModel render logs. See enable_mintmodel_debug.

Pod resources is a table of the CPU request, Memory request and Memory limit for each Pod template: Change worker, Step runner, Actions refresh, Agent and MintModel. Values are Kubernetes quantities. A memory limit below 256Mi is refused, and no value may exceed the maximum pod size set in Runner pod limits. See pod template settings and what a runner step is allowed to take.

Image reuse controls whether OpsChain reuses previously built runner images instead of rebuilding them for every step or change. Its fields are Enabled, Retention (days) and Include parent data, described under image reuse.

Vault settings

The Vault settings section shows the bundled secret vault, which is always the global secret vault, and lists the external secret vaults registered with OpsChain.

The bundled secret vault is shown read-only, with its mount path and whether values are encrypted by OpsChain before they are stored. Every project, environment, asset and template that does not set vault.code uses it.

Superusers can add, edit and delete external secret vaults here. Each vault has a code, a name, an address, an authentication method, the service credentials OpsChain signs in with, and client options. OpsChain signs in to the vault with the credentials before saving it, and saves nothing if that fails. Credentials are shown only as configured or not, never as their values; leave one blank when editing to keep it. A vault cannot be deleted while a settings level or an unfinished change uses it. See register an external secret vault for each field.

To use an external secret vault for a project, environment or asset, set vault.code in its settings.

Below the vaults, superusers manage the runner credentials of each vault. Add one with Add runner credential under the vault: for the bundled secret vault, turn on Managed and list the mount paths it reaches, or turn it off and enter a token or username and password; for an external vault, enter the credential. Pick the projects, environments and assets to tag it on in Tagged on. A credential whose tags cover a node with no credential for that node's vault shows a warning naming the node, because changes there are rejected until one is tagged.

Project

Project settings

The defaults every project inherits, and can override on its own settings page.

Field	Function
Allow parallel changes	Allow parallel changes of the same action in a project.
Allow parallel runs of the same change	Allow parallel runs of the same change in a project and its children. Parallel changes must also be allowed.
Allow parallel runs of the same workflow	Allow parallel runs of the same workflow in a project.

See parallelism settings.

Notifications

Notification settings

Lists the global notification channels, with their code, description, type and whether each is enabled or the default. Add one from New channel, choosing Add email channel, Add Slack channel or Add Teams channel. Each channel has a Code (which cannot be changed once set), a Description and a Channel enabled switch, plus the fields for its type, and Send test message checks it before you save. Select a channel to edit it.

System channels lists the channels OpsChain uses internally; they cannot be modified or removed. See configuring channels for each channel type's fields.

Security

Authentication

How users and API clients authenticate, and how long their sessions last.

Field	Function
Authentication strategy	LDAP and local authenticates users against LDAP first; Local only uses only local accounts. Users stay signed in until their token expires.
Enable basic authentication	Allows insecure HTTP basic authentication on the API in addition to tokens.
Access token lifetime	How long a newly issued access token stays valid. Existing tokens keep their original expiry.
Refresh token lifetime	How long a newly issued refresh token stays valid.
Enable cookies	Issues the refresh token as an HTTP cookie when signing in.

See authentication settings.

CA certificates

Upload the certificate of an additional certificate authority for OpsChain to trust. Drag the file onto Upload CA Certs, or select Choose file, then Upload. Existing certificates lists the uploaded certificates with the date each was added; select the bin icon to delete one. See uploading an authority to a running instance.

LDAP config

How OpsChain connects to LDAP or Active Directory. These settings apply as soon as they are saved; see altering the OpsChain LDAP configuration and LDAP/AD settings.

Field	Function
Base DN	The LDAP/AD base DN.
User base	The base DN to search for users.
User attribute	The user attribute used as the OpsChain username.
Mail attribute	The user attribute containing the user's email address.
Display name attribute	The user attribute containing the user's display name.
First name attribute	The user attribute containing the user's first name.
Last name attribute	The user attribute containing the user's last name.
Users filter	A filter applied to the user base to restrict the users displayed in the GUI.
Admin	The administrator DN OpsChain connects as. OpsChain does not write to LDAP, so this needs only permission to search all users and groups.
Password	The administrator password.
HC user	The username OpsChain queries regularly to check that the LDAP server is available. Leave blank to skip the check.
Cache TTL	How long group memberships are cached. Set to zero to turn off caching. See LDAP group membership caching.
Search timeout	The timeout for LDAP/AD search queries.
Refresh interval	The interval between synchronisations of the users and groups OpsChain caches from LDAP. See directory synchronisation.
Refresh search timeout	The timeout for synchronisation search queries. Increase it if synchronisation queries time out.
Host	The LDAP/AD host name or IP address.
Port	The LDAP/AD port.
Group base DN	The base DN to search for groups.
Group attribute	The group attribute containing OpsChain user DNs.
Groups filter	A filter applied to the group base to restrict the groups displayed in the GUI.
Enable SSL	Use SSL for LDAP communication.
Use admin to bind	Bind as the admin user during authentication.
LDAP Logger	Log LDAP queries to the API pod logs at DEBUG level.
New group object class	Comma-separated object classes assigned to a group OpsChain creates in LDAP.
New user object class	Comma-separated object classes assigned to a user OpsChain creates in LDAP.
New organisation unit object class	Comma-separated object classes assigned to an organisation unit OpsChain creates in LDAP.

Vault LDAP login

The Vault LDAP login section configures how OpsChain sets up LDAP sign-in on the OpsChain secret vault, so users can sign in to the secret vault with their LDAP account and superusers can assign vault policies to LDAP users and groups. It applies only when OpsChain uses LDAP authentication and the OpsChain secret vault.

Field	Function
Enabled	Whether OpsChain manages the secret vault's LDAP sign-in. Turned off, OpsChain stops managing it, and vault policies can no longer be managed or assigned from OpsChain.
Bind DN	The DN the secret vault binds as to look up users and groups. Left blank, OpsChain's own LDAP admin DN is used.
Bind password	The password for the bind DN. Left blank, OpsChain's own LDAP admin password is used. It is stored encrypted and never shown; select Clear to remove a stored password.
Config	A JSON object merged over the LDAP configuration OpsChain derives from its own LDAP settings, for directories those settings do not describe.

OpsChain applies the settings to the secret vault shortly after they are saved. Each field is described under configure the secret vault's LDAP connection.

System

Agent

The image and placement of agent pods: Repository, Name, Image tag, Node selector (a Kubernetes nodeSelector as a JSON string), Script path and Enable host alias (whether agents get a Kubernetes host alias for reaching the OpsChain API). See agent settings.

API autoscaling

Lets OpsChain grow or shrink the number of worker processes in each API pod, between a minimum and maximum, in response to request queuing. Every decision is recorded as an event.

Field	Function
Mode	Disabled turns autoscaling off. Dry run, the default, records what OpsChain would do as an event without changing the worker count. Active changes the worker count and records the same events.
Min workers	The fewest worker processes autoscaling can shrink a pod to.
Max workers	The most worker processes autoscaling can grow a pod to.

Choose a Max workers value your pod's memory limit can support at full worker count, and that your database's maximum connections can absorb across every OpsChain pod. See API worker autoscaling settings.

API Cache

Select Clear cache to clear the API's cache. Superusers only.

Banners

Lists the banners shown above the header for every user until they are deleted. Select Add banner to add one, with a Type (Alert, Announcement, Info or Warning), a Title and a Message. Select a banner to edit it, or the bin icon to delete it.

Build service

Settings for the service that builds runner images: Max image build retries, Max concurrent image builds and Image build throttle delay (in seconds). See image build settings.

Executor pool

The Executor pool section sets the global executor pool settings: Enabled, Sharing scope, Filesystem isolation scope, Separate creators, Keep alive, Idle timeout, Max idle pods and Step start memory %. Each field shows the default while the setting has not been changed, and is described under executor pool settings. To use the pool for a single project, environment or asset instead, set executor_pool.enabled in its settings.

Global config

Field	Function
Log aggregator output	Additional settings for the log aggregator output. See log_aggregator_additional_output_settings.
Parallel change worker steps	The number of steps a single change can run in parallel. Applies only when Pod per change step resolves to off, or to a MintModel change.
Git fetch stale threshold	How recently a project's Git repository must have been fetched for that fetch to be reused instead of fetching again.
Git periodic fetch interval	How often each project's Git remotes are fetched in the background, between one minute and one day. A project, or an individual Git remote, can override it.
Log step pod events	Record Kubernetes pod events for step runner pods, to help diagnose scheduling or start-up problems.

See Git remote settings.

Instance info

A Title for this instance and a Support contact, shown next to the OpsChain logo in the header.

Maintenance mode

Holds every new change and workflow run, across all projects, until maintenance mode is turned off. A badge shows whether it is Off, On or On - superusers exempt.

Select Turn on maintenance mode, then choose Hold everyone, including superusers or Hold ordinary users, but let superusers keep running changes. While it is on, select Turn off maintenance mode, or switch between the two modes with Allow superusers to keep running or Also hold superusers. See maintenance mode.

Runner config

The step runner image and placement: Runner image repository, Runner image name, Runner image tag and Node selector (a Kubernetes nodeSelector for step runner pods, as a JSON string). See runner image settings.

Runner pod limits

Caps how many runner pods run at once and how large any one can be. When a cap is reached, further pods wait until running ones complete. Each cap is enforced on its own.

Field	Function
Runner limit	The most change worker and step runner pods that run at once on a cluster.
Actions refresh limit	The most actions-refresh pods that run at once on a cluster.
MintModel limit	The most MintModels concretised at once on a cluster. Read-only: it is the MintModel API's replicas multiplied by its concurrency, changed on the Deployments tab.
Agent limit	The most agent pods that run at once on a cluster.
Max pod memory	The largest memory request or limit any runner pod may be given. Overrides above it are rejected when saved. Raising it does not change any pod's size.

See runner pod concurrency and limit settings and the ceiling those overrides cannot pass.

Editing the settings as JSON

Select Switch to advanced mode to edit the whole global settings document as JSON - for settings that have no form, or to remove a setting. It works like the settings editor on a project. Select Switch to basic mode to return to the sections.