Plugins

A plugin is a reusable pipeline step, like a Jenkins plugin. It has typed inputs and a script, and it runs on your build agents, never on the OpsNexus server. OpsNexus ships 22 official plugins (Slack, Docker, Helm, Terraform, Trivy and more), and you can write your own in YAML.

Plugins are managed under Build & deploy → Plugins.

#Install a plugin

A plugin must be installed before a pipeline can use it.

1. Open Plugins and select the Available tab.
2. Under Install into, choose This project or Shared with all projects.
3. Select Install on the plugin.

• A plugin installed in a project is used only by that project's pipelines. A shared plugin is used by every project. If a project has its own plugin with the same name as a shared one, the project's plugin wins.
• Installing or sharing needs modify access to CI/CD pipelines. Shared plugins need that access in your organization role, and an organization admin can turn sharing off.
• When a newer official version is available, the Installed tab shows an update count, and the plugin's page has an Update to button with the new version number. Older versions stay installed, so pipelines pinned to them keep working.

The Installed tab lists each plugin with its category, version, where it is installed, and where it is used (jobs and builds in the last 30 days). Report plugins is a separate tab for PDF reports made by the OpsNexus server; those are not pipeline steps.

#Use a plugin in a pipeline file

Write a step with uses: and put the inputs under with::

stages:
  - name: Image
    steps:
      - uses: docker-build-push@1
        with:
          image: registry.example.com/team/api
          tags: "${{ run.number }}, latest"
          registry: registry.example.com
          login: registry-login            # name of a credential
post:
  failure:
    - uses: slack-notify@1
      with:
        webhook: slack-webhook
        status: failure
        message: "Build #${{ run.number }} of ${{ job.name }} failed"

A plugin step also accepts name, env, continue_on_error, timeout_minutes and working_directory. It does not take run or shell. See Pipeline syntax.

The version is resolved when the build starts. The build page shows the exact plugin version each step used.

Each plugin's page has Use it in a pipeline file with a ready-to-paste step: required inputs filled in, optional inputs as commented-out lines with their defaults. CI/CD → Pipeline syntax lists every installed plugin with its required inputs.

#In a Freestyle project

On a Freestyle project's Build steps or Post-build tab, select Add plugin step, choose the plugin and fill in its form. The form is generated from the plugin's inputs.

#How inputs are checked

OpsNexus checks plugin inputs when it validates the pipeline and again when a build starts. Problems are reported with their place, for example stages[1].steps[0].with.region: required.

How inputs reach the plugin's script:

• Each input becomes an environment variable INPUT_<NAME>, for example INPUT_REGION. Values are never pasted into the script text.
• A credential input becomes ${{ secrets.<name> }}. It is masked in the log like any secret.
• A credential input with fields also sets one variable per field, for example INPUT_AWS_ACCESS_KEY_ID and INPUT_AWS_SECRET_ACCESS_KEY for an input called aws.
• For a Secret file credential (such as a kubeconfig), the input holds the path of a file the agent writes for the build.
• Defaults can contain expressions. For example, the default tag of docker-build-push is ${{ run.number }}.

#Where plugins run

• Plugins with an image run their script in that pinned container image. The agent needs Docker. The workspace is mounted at the same path. Only the plugin's INPUT_* variables and CI, BUILD_NUMBER, JOB_NAME, BUILD_URL, GIT_COMMIT, GIT_BRANCH are passed into the container.
• Plugins without an image run on the agent with their shell. Plugins that list required tools check them first and fail with Plugin <name> needs '<tool>' on this agent if one is missing.
• A step fails when the plugin's script exits with a non-zero code.

#Manage plugins

On a plugin's page:

The page also shows About (how it runs and what it needs on the agent), Inputs, Script, Used by and Versions.

#Write your own plugin

To create a plugin:

1. Open Plugins and select Create plugin.
2. Choose Where to create it: this project or all projects.
3. Write the manifest. The page validates it as you type and previews the step form and the pipeline snippet.
4. Select Create plugin.

A manifest:

name: notify-webhook              # 3-40 lowercase letters, digits and '-', starting with a letter
version: 1.0.0                    # MAJOR.MINOR.PATCH
title: Notify a webhook
description: Post a JSON message to a webhook URL.
category: notifications
inputs:
  url:     { type: credential, kinds: [secret_text], required: true, description: Webhook URL }
  message: { type: text, default: "Build ${{ run.number }} of ${{ job.name }} finished" }
  level:   { type: choice, options: [info, warning, error], default: info }
artifacts:                        # optional: files the step writes, archived with the build
  - reports/notify.json
runs:
  shell: python                   # bash | sh | python | pwsh | powershell | cmd
  script: |
    import json, os, urllib.request
    body = json.dumps({"text": os.environ["INPUT_MESSAGE"], "level": os.environ["INPUT_LEVEL"]}).encode()
    req = urllib.request.Request(os.environ["INPUT_URL"], data=body, headers={"Content-Type": "application/json"})
    urllib.request.urlopen(req, timeout=30)

Manifest keys:

Input keys: type (string default, text, number, boolean, choice, multichoice, credential), required, default, description, options (for choice types), kinds (allowed credential types), fields (credential fields to expose), secret and placeholder. Input names use lowercase letters, digits and _. Credential inputs cannot have a default.

The plugin file can be at most 200 KB.

#Official plugin catalog

All official plugins have version 1.0.0, except trivy-scan (1.1.1). Credential types are the names shown on Secrets & variables.

#aws-cli

Runs AWS CLI commands with an AWS credential and region, for example ECS deploys, CloudFront invalidations or Lambda updates. It can assume an IAM role first and prints the identity it uses.

- uses: aws-cli@1
  with:
    aws: aws-deployer
    region: ap-south-1
    commands: aws ecs update-service --cluster prod --service web --force-new-deployment

#aws-cost-guard

Checks this month's AWS spend (Cost Explorer) and AWS's forecast for the month against a budget, lists the top services, and fails or warns before you deploy more. The credential needs ce:GetCostAndUsage and ce:GetCostForecast.

- uses: aws-cost-guard@1
  with:
    aws: aws-billing
    budget: 2500
    check: forecast
    on_exceed: fail

#docker-build-push

Builds a Docker image from the workspace and pushes it to any registry (Docker Hub, ECR, ACR, GHCR, Harbor, Nexus). Adds the commit and build URL as image labels.

- uses: docker-build-push@1
  with:
    image: ghcr.io/acme/api
    tags: "${{ run.number }}, latest"
    registry: ghcr.io
    login: ghcr-login

#email-notify

Sends an email through your SMTP server, optionally with workspace files attached. The build link is added to the body.

- uses: email-notify@1
  with:
    smtp_host: smtp.example.com
    login: smtp-login
    sender: ci@example.com
    to: team@example.com
    attachments: reports/*.html

#helm-deploy

Installs or upgrades a Helm chart (helm upgrade --install) and waits until it is ready. Creates the namespace if needed.

- uses: helm-deploy@1
  with:
    kubeconfig: prod-kubeconfig
    release: web
    chart: ./chart
    namespace: web
    values_files: chart/values-prod.yaml
    set: image.tag=${{ run.number }}

#http-request

Calls any HTTP API, or waits for a URL to become healthy, with retries, an expected status and an optional bearer token.

- uses: http-request@1
  with:
    url: https://staging.example.com/health
    retries: 12
    retry_delay_seconds: 10

#iac-security-scan

Scans Terraform, CloudFormation, Kubernetes, Helm, Dockerfiles and GitHub Actions workflows for misconfigurations with Checkov, writes a JUnit report and fails on findings. The report is archived with the build as a test report, with passed and failed counts.

- uses: iac-security-scan@1
  with:
    directory: infra
    frameworks: [terraform, dockerfile]

#infracost-estimate

Estimates the monthly cost of Terraform code with Infracost, prints a breakdown per resource, and fails when it is above your budget. Needs an Infracost API key.

- uses: infracost-estimate@1
  with:
    directory: infra/environments/prod
    api_key: infracost-key
    budget: 1200

#jira-comment

Adds a comment with a link to the build to one or more Jira issues. Fails if any issue could not be commented on.

- uses: jira-comment@1
  with:
    site: https://acme.atlassian.net
    login: jira-bot
    issues: OPS-12

#junit-report

Reads JUnit or xUnit XML results (pytest, Jest, Maven Surefire, Go, .NET), prints a summary with every failure, and fails or warns on failed tests.

- uses: junit-report@1
  with:
    results: |
      reports/junit/*.xml
    fail_on_failure: true

To keep the XML files with the build, add them to artifacts: in the pipeline file.

#kubectl-apply

Applies manifests (or kustomizations) to a Kubernetes cluster and waits for rollouts.

- uses: kubectl-apply@1
  with:
    kubeconfig: staging-kubeconfig
    manifests: k8s/overlays/staging
    kustomize: true
    wait_for: deployment/web

#opsnexus-infra-deploy

Plans, applies or destroys an Infra Designer stack from a pipeline, waits for it and prints the plan and outputs. It calls the OpsNexus API with an API key. The deployment itself also runs on a build agent, so keep a second executor free.

- uses: opsnexus-infra-deploy@1
  with:
    server_url: https://opsnexus.example.com
    api_key: opsnexus-deployer
    stack_id: 0b6f7c1e-0000-0000-0000-000000000000
    action: apply

#pdf-report

Turns your pipeline's own results (a JSON or CSV file with test counts, timings, coverage, costs and so on) into a PDF with charts and tables. The PDF is archived with the build.

The JSON format:

{
  "title": "Nightly tests",
  "summary": {"Tests": 120, "Failed": 2},
  "charts": [{"title": "Duration", "type": "bar", "labels": ["api", "web"],
              "series": [{"name": "seconds", "values": [41, 63]}], "unit": "s"}],
  "tables": [{"title": "Slowest", "columns": ["Test", "s"], "rows": [["checkout", 12.4]]}]
}

- uses: pdf-report@1
  with:
    data_file: reports/summary.json
    style: modern
    output: reports/summary.pdf

#s3-upload

Uploads files or folders from the workspace to an S3 bucket. A folder is synced; a file is copied. It can also invalidate a CloudFront distribution for static sites.

- uses: s3-upload@1
  with:
    aws: aws-deployer
    region: ap-south-1
    source: dist/
    bucket: www-example-com
    prefix: /
    sync_delete: true
    cloudfront_distribution: E1ABCDEF234567

#slack-notify

Posts a build message to a Slack channel through an incoming webhook.

- uses: slack-notify@1
  with:
    webhook: slack-webhook
    status: success
    message: "Deployed ${{ job.name }} #${{ run.number }} to production"

#sonarqube-scan

Runs SonarScanner on the workspace and sends the analysis to SonarQube or SonarCloud, optionally waiting for the quality gate.

- uses: sonarqube-scan@1
  with:
    host_url: https://sonarqube.example.com
    token: sonar-token
    project_key: web-app
    extra_properties: sonar.exclusions=**/test/**

#ssh-deploy

Copies files to a server over SSH and runs commands there.

- uses: ssh-deploy@1
  with:
    host: app-01.example.com
    user: deploy
    key: deploy-ssh
    files: dist.tgz
    remote_dir: /opt/app/releases
    command: |
      cd /opt/app/releases && tar xzf dist.tgz && sudo systemctl restart app

#teams-notify

Posts a build card to a Microsoft Teams channel through a Workflows webhook ("Post to a channel when a webhook request is received").

- uses: teams-notify@1
  with:
    webhook: teams-webhook
    status: failure
    message: Build failed on ${{ git.branch }}

#terraform

Runs terraform init and then plan, apply, destroy or validate in a workspace folder. apply and destroy run with -auto-approve; put an approval stage before them.

stages:
  - name: Plan
    steps:
      - uses: terraform@1
        with: { command: plan, directory: infra, aws: aws-deployer, region: ap-south-1 }
  - name: Apply
    approval: { message: Apply the Terraform plan? }
    steps:
      - uses: terraform@1
        with: { command: apply, directory: infra, aws: aws-deployer, region: ap-south-1 }

#terraform-plan-report

Runs terraform plan and writes a readable Markdown summary (resources to add, change, replace and destroy) that is archived with the build. It can block destroys or any change.

- uses: terraform-plan-report@1
  with:
    directory: infra/environments/prod
    aws: aws-deployer
    region: ap-south-1
    fail_on: destroy

#trivy-scan

Scans the workspace (dependencies, IaC misconfigurations, leaked secrets, licenses) or a registry image for vulnerabilities and fails on the severities you choose. The full JSON report is archived with the build and its findings appear under Security.

- uses: trivy-scan@1
  with:
    target: image
    image: ghcr.io/acme/api:${{ run.number }}
    registry_login: ghcr-login
    severity: [CRITICAL, HIGH]

#workspace-cleanup

Deletes files from the build workspace (everything, or only matching patterns) to save disk on the agent. It never deletes outside the workspace.

post:
  always:
    - uses: workspace-cleanup@1
      with:
        patterns: |
          node_modules
          **/*.log