Integrations

An integration connects OpsNexus to an external CI/CD tool. OpsNexus imports the tool's pipelines and recent builds, shows them next to native OpsNexus pipelines, and can run and cancel them if you allow it.

Integrations belong to the current project. You find them under CI/CD → Integrations.

#Supported tools

For each pipeline OpsNexus keeps its name, project or folder, link and default branch. For each build it keeps the number, status, branch, commit, who triggered it, start and finish times, duration, a link, and the agent or queue when the tool reports one. OpsNexus imports up to the 20 newest builds per pipeline on each sync. Build logs stay in the original tool: Logs on the Builds page opens the build there.

#Connect a tool

You need modify access to Integrations.

1. Open CI/CD → Integrations and select Connect a tool.
2. Choose tool, then select Next.
3. Fill in Connection details:
   • Display name, for example Jenkins – Production. It must be unique in the project.
   • Environment: prod, staging or dev. It is shown with the integration and its notifications.
   • The tool's fields (see below).
   • Allow running and cancelling builds: off by default. Read-only sync works without it.
4. Select Test connection. OpsNexus calls the tool with the details and shows the result.
5. Select Save integration (or Save anyway if the test failed and you want to fix it later).

Secret fields go to the secret store (HashiCorp Vault in production) and are never shown again.

After saving, open the integration and select Sync now to import right away. Otherwise the first scheduled sync imports it.

#Jenkins

The user needs read access to the jobs you want to see. To run and cancel builds from OpsNexus, it also needs permission to build and cancel those jobs.

#GitLab CI/CD

Running a pipeline starts a new GitLab pipeline on the chosen branch, or on the project's default branch.

#GitHub Actions

One integration covers one repository. Add an integration per repository. Running a workflow sends a workflow_dispatch event, so the workflow must have a workflow_dispatch trigger.

#Azure DevOps

#Argo CD

Argo CD syncs appear on CI/CD → Deployments. Running an application starts a sync (to the branch or revision you give, if any). Cancelling ends the running sync operation.

# Example: a local Argo CD account for OpsNexus with an API token
argocd account generate-token --account opsnexus

#How syncing works

• Every enabled integration syncs on a schedule. The default interval is 5 minutes, set by INTEGRATION_SYNC_MINUTES in .env. See Environment variables.
• Sync now on an integration's page queues a sync at once.
• Running a pipeline from OpsNexus queues a sync too, so the new build appears soon.
• Turn Scheduled sync enabled off on the integration's page to stop scheduled syncs. Sync now still works.
• Sync history on the integration's page lists each sync with its status, number of builds and log.

When a sync fails, the integration's status becomes error with the message, and OpsNexus sends the integration.error notification event (once, when it changes from connected to error).

When a sync finds a build that started or finished in the last 24 hours, OpsNexus sends build.started, build.succeeded or build.failed. For Argo CD it sends deployment.started, deployment.completed or deployment.failed. The first sync of a new integration sends no events. See Notifications.

#Run and cancel external builds

With Allow running and cancelling builds on:

• Run on the CI/CD overview starts the pipeline in its tool.
• Cancel on the Builds page stops a running or queued build in its tool.
• The VS Code extension can do both.

Both actions need modify access to CI/CD pipelines and are recorded in the audit log as pipeline.trigger and build.cancel.

#Manage an integration

The integration's page shows its configuration, where its credentials are stored, its status and its sync history.

The summary tiles on CI/CD → Integrations count integrations that are Connected, that Can't connect, and that are Pending or disabled.

#Troubleshooting