cortexapps-cli 1.35.0__tar.gz → 1.36.0__tar.gz

{cortexapps_cli-1.35.0 → cortexapps_cli-1.36.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cortexapps-cli
-Version: 1.35.0
+Version: 1.36.0
 Summary: Command Line Interface for cortexapps
 License: MIT
 License-File: LICENSE

cortexapps_cli-1.36.0/cortexapps_cli/solutions/jenkins-deploy/README.md

@@ -0,0 +1,129 @@
+---
+name: Jenkins Deploy Tracking
+description: Track deployments from Jenkins pipelines in Cortex, with a deploy health scorecard measuring delivery cadence.
+---
+
+# Jenkins Deploy Tracking
+
+Trigger deploys from Cortex, track them as they run in Jenkins, and surface deploy health back in your service catalog.
+
+```
+  ┌─────────────────────────────────┐
+  │         Cortex Catalog          │
+  │                                 │
+  │    jenkins-demo  (service)      │
+  │    ├── x-cortex-custom-metadata │
+  │    │     jenkins:               │
+  │    │       url / job            │
+  │    └── Scorecard: Deploy Health │
+  │          Bronze / Silver / Gold │
+  └──────────────┬──────────────────┘
+                 │
+                 │  Run workflow from entity page
+                 │  (or: cortex workflows run -t
+                 │   jenkins-trigger-deploy
+                 │   --scope ENTITY --entity <tag>)
+                 ▼
+  ┌─────────────────────────────────┐
+  │       Cortex Workflow           │
+  │    Trigger Jenkins Deploy       │
+  │                                 │
+  │  1. Read Jenkins config from    │
+  │     entity custom metadata      │
+  │  2. POST /buildWithParameters   │
+  │     to Jenkins via HTTP         │
+  │  3. Pass callback URL as        │
+  │     pipeline parameter          │
+  │  4. Wait for callback           │
+  └──────────────┬──────────────────┘
+                 │  POST /buildWithParameters  (HTTP + Basic auth)
+                 ▼
+  ┌─────────────────────────────────────────────────────────┐
+  │  GitHub Codespaces  (optional — provisioned by setup)   │
+  │  port 8080 exposed publicly for demo                    │
+  │                                                         │
+  │  ┌─────────────────────────────────┐                    │
+  │  │         Jenkins Pipeline        │                    │
+  │  │         cortex-deploy           │                    │
+  │  │                                 │                    │
+  │  │  stage: Build                   │                    │
+  │  │    └── run your deploy steps    │                    │
+  │  │                                 │                    │
+  │  │  stage: Record Deploy in Cortex │                    │
+  │  │    └── POST /deploys       ◄────┼── registers deploy │
+  │  │        (entity: jenkins-demo)   │   event on entity  │
+  │  │                                 │                    │
+  │  │  post { always }                │                    │
+  │  │    └── POST callbackUrl ───────►│   Cortex marks     │
+  │  │        status: SUCCESS/FAILURE  │   workflow done    │
+  │  └─────────────────────────────────┘                    │
+  └─────────────────────────────────────────────────────────┘
+  (or point to your own Jenkins instance — Codespaces not required)
+```
+
+## What's Included
+
+- **Entity:** `jenkins-demo` service — a sample entity to receive deploy events
+- **Scorecard:** Deploy Health — Bronze/Silver/Gold based on deploy frequency
+- **Jenkinsfile:** `cortex-deploy` — a two-stage pipeline (Build → Record Deploy) with an async callback to Cortex; drop it into any existing Jenkins job
+- **Cortex workflow:** `jenkins-trigger-deploy` — reads Jenkins coordinates from entity custom metadata, triggers the pipeline via HTTP, and waits for the result
+- **Setup script:** Interactive wizard that wires everything together end-to-end; optionally provisions Jenkins in GitHub Codespaces for a zero-install demo
+
+## Quick Start
+
+1. Install the solution:
+
+   ```
+   cortex solutions install -s jenkins-deploy
+   ```
+
+2. Follow the post-install setup prompts, or run later:
+
+   ```
+   cortex solutions post-install -s jenkins-deploy
+   ```
+
+## How It Works
+
+The Cortex workflow reads Jenkins coordinates from `x-cortex-custom-metadata.jenkins` on the entity, then triggers `cortex-deploy` via `buildWithParameters`, passing a `callback_url` as a pipeline parameter. Cortex waits asynchronously for the pipeline to report back.
+
+Jenkins runs the build, then notifies Cortex twice on completion:
+- **Deploy registration** (`POST /api/v1/catalog/{tag}/deploys`) — records the deploy event on the entity, feeding the Deploy Health scorecard
+- **Workflow callback** — signals the Cortex workflow run as SUCCESS or FAILURE
+
+## After Installing
+
+If you ran the post-install setup, you're already done — it created the Jenkins job, added credentials, wrote Jenkins coordinates to the entity's custom metadata, imported the Cortex workflow, and triggered a test deploy.
+
+To roll the pattern out to your own services:
+
+1. Add the `cortex-deploy` **Jenkinsfile** stages to any existing Jenkins pipeline (needs only `CORTEX_API_KEY` and `CORTEX_BASE_URL` secret-text credentials)
+
+2. Add a `x-cortex-custom-metadata` block to your entity's catalog YAML with your Jenkins coordinates:
+
+   ```yaml
+   x-cortex-custom-metadata:
+     jenkins:
+       url: "https://jenkins.example.com"
+       job: "your-pipeline-name"
+   ```
+
+3. Create a **Cortex secret** with your Jenkins credentials:
+
+   ```bash
+   cortex secrets create -f - <<EOF
+   {
+     "name": "Jenkins Auth",
+     "tag": "jenkins_auth",
+     "secret": "$(echo -n 'your-username:your-api-token' | base64)"
+   }
+   EOF
+   ```
+
+4. Run the **Solution: Trigger Jenkins Deploy** workflow from the entity page — it reads the Jenkins coordinates from the entity's custom metadata automatically, with no manual inputs required
+
+## Customizing for Production
+
+- Point the workflow at your real entity by replacing `jenkins-demo` with your service tag
+- Add `CORTEX_API_KEY` and `CORTEX_BASE_URL` secret-text credentials to your real Jenkins instances
+- The Deploy Health scorecard is scoped to `demo-jenkins-deploys` to avoid affecting your existing services. To roll it out broadly, remove the group filter from the scorecard. To opt in individual services, add the `demo-jenkins-deploys` group to them.

cortexapps_cli-1.36.0/cortexapps_cli/solutions/jenkins-deploy/_templates/Jenkinsfile

@@ -0,0 +1,82 @@
+pipeline {
+    agent any
+    parameters {
+        string(name: 'callback_url',      defaultValue: '', description: 'Cortex async callback URL')
+        string(name: 'cortex_entity_tag', defaultValue: '', description: 'Cortex entity tag')
+    }
+    environment {
+        CORTEX_API_KEY  = credentials('CORTEX_API_KEY')
+        CORTEX_BASE_URL = credentials('CORTEX_BASE_URL')
+    }
+    stages {
+        stage('Build') {
+            steps {
+                echo 'Starting build...'
+                // Replace this echo with your actual build commands
+            }
+        }
+        stage('Deploy') {
+            steps {
+                script {
+                    // Sends intermediate UPDATE callbacks to the Cortex workflow,
+                    // demonstrating that the callback URL can be called multiple times
+                    // before the terminal SUCCESS/FAILURE.
+                    def callbackUrl = params.callback_url
+                    def updates = [
+                        [progress: 33, message: 'Build complete — starting deploy'],
+                        [progress: 66, message: 'Deploy in progress'],
+                        [progress: 100, message: 'Deploy complete — recording in Cortex'],
+                    ]
+                    updates.each { u ->
+                        sleep 5
+                        echo "Deploy progress: ${u.progress}%"
+                        if (callbackUrl) {
+                            def payload = """{"status":"UPDATE","message":"${u.message}","response":{"progress":"${u.progress}%"}}"""
+                            sh """
+                                curl -s -X POST '${callbackUrl}' \\
+                                  -H 'Content-Type: application/json' \\
+                                  -H "Authorization: Bearer \${CORTEX_API_KEY}" \\
+                                  -d '${payload}' || true
+                            """
+                        }
+                    }
+                    // Replace the placeholder loop above with your actual deploy commands
+                }
+            }
+        }
+        stage('Record Deploy in Cortex') {
+            steps {
+                script {
+                    def timestamp = sh(script: 'date -u +%Y-%m-%dT%H:%M:%SZ', returnStdout: true).trim()
+                    def buildUrl = env.BUILD_URL ?: "${env.JENKINS_URL}job/${env.JOB_NAME}/${env.BUILD_NUMBER}/"
+                    def payload = """{"sha":"${env.BUILD_NUMBER}","timestamp":"${timestamp}","environment":"production","type":"DEPLOY","title":"Triggered by Jenkins","url":"${buildUrl}","deployer":{"name":"Jenkins"},"customData":{"buildNumber":"${env.BUILD_NUMBER}","jobName":"${env.JOB_NAME}"}}"""
+                    sh """
+                        curl -s -f -X POST \\
+                          "\${CORTEX_BASE_URL}/api/v1/catalog/${params.cortex_entity_tag}/deploys" \\
+                          -H "Authorization: Bearer \${CORTEX_API_KEY}" \\
+                          -H "Content-Type: application/json" \\
+                          -d '${payload}' || true
+                    """
+                }
+            }
+        }
+    }
+    post {
+        always {
+            script {
+                if (params.callback_url) {
+                    def status = currentBuild.currentResult == 'SUCCESS' ? 'SUCCESS' : 'FAILURE'
+                    def buildUrl = env.BUILD_URL ?: "${env.JENKINS_URL}job/${env.JOB_NAME}/${env.BUILD_NUMBER}/"
+                    def payload = """{"status":"${status}","message":"Jenkins pipeline ${status.toLowerCase()}","response":{"buildUrl":"${buildUrl}","buildNumber":"${env.BUILD_NUMBER}","jobName":"${env.JOB_NAME}"}}"""
+                    def callbackUrl = params.callback_url
+                    sh """
+                        curl -s -f -X POST '${callbackUrl}' \\
+                          -H 'Content-Type: application/json' \\
+                          -H "Authorization: Bearer \${CORTEX_API_KEY}" \\
+                          -d '${payload}'
+                    """
+                }
+            }
+        }
+    }
+}

cortexapps_cli-1.36.0/cortexapps_cli/solutions/jenkins-deploy/_templates/trigger-jenkins-deploy.yaml

@@ -0,0 +1,126 @@
+name: "Solution: Trigger Jenkins Deploy"
+tag: jenkins-trigger-deploy
+description: |
+  Triggers a Jenkins pipeline and waits for it to report completion back to Cortex,
+  registering a deploy event on the target entity. No inputs required — Jenkins
+  coordinates (url, job) are read from the entity's custom metadata.
+isDraft: false
+isRunnableViaApi: true
+filter:
+  type: ENTITY
+variables:
+  - slug: jenkins-job
+    type: STRING
+    defaultValue: ""
+runResponseTemplate: |
+  # Jenkins Deploy — Complete
+
+  **Job:** [{{variables.jenkins-job}}](JENKINS_BASE_URL/job/{{variables.jenkins-job}})
+
+  **Cortex Deploys:** [see deploys for {{context.entity.tag}}](https://app.getcortexapp.com/admin/resources?tag={{context.entity.tag}})
+
+  ---
+
+  ## How this workflow works
+
+  **1. Cortex read the entity's Jenkins configuration**
+
+  The workflow fetched `x-cortex-custom-metadata.jenkins` from this entity to find
+  the Jenkins URL and job name — no manual input required.
+
+  **2. Cortex triggered the Jenkins build**
+
+  It POSTed to the Jenkins `buildWithParameters` API with the callback URL and entity
+  tag in the POST body so Jenkins receives them as build parameters.
+
+  **3. Jenkins ran the pipeline**
+
+  The `cortex-deploy` pipeline runs three stages:
+
+  - **Build** — your build steps (replace `echo "Starting build..."` with your real commands)
+
+  - **Deploy** — your deploy steps, with intermediate `UPDATE` callbacks sent to Cortex
+    so you can track progress in real time; replace the placeholder loop with your real deploy
+
+  - **Record Deploy in Cortex** — POSTs a deploy event to `/api/v1/catalog/{tag}/deploys`,
+    recording build number, URL, and job name. This feeds the Deploy Health scorecard.
+
+  The `post { always { ... } }` block POSTs the final `SUCCESS` or `FAILURE` status to the
+  callback URL — which is how Cortex knows the workflow run is done.
+
+  **4. Cortex received the callback**
+
+  When Jenkins posted to the callback URL, Cortex marked this workflow run complete.
+
+  ---
+
+  ## Adapting this to your own pipelines
+
+  1. Replace the placeholder `echo` in the **Build** stage and the progress loop in the
+     **Deploy** stage with your actual build and deploy commands
+
+  2. Add the Deploy, Record Deploy, and callback steps to any existing Jenkinsfile — they
+     only need the `CORTEX_API_KEY` and `CORTEX_BASE_URL` credentials plus the two build
+     parameters
+
+  3. Add `x-cortex-custom-metadata.jenkins` to your entity's catalog YAML with
+     `url` and `job` fields — no credentials here. If your Jenkins requires auth,
+     create a Cortex secret `jenkins_auth = base64(user:token)` and add
+     `Authorization: "Basic {{context.secrets.jenkins_auth}}"` to the workflow's
+     Trigger Jenkins Build action.
+actions:
+- name: Get Jenkins config
+  slug: get-jenkins-config
+  schema:
+    type: HTTP_REQUEST
+    httpMethod: GET
+    url: "https://api.getcortexapp.com/api/v1/catalog/{{context.entity.tag}}/custom-data/jenkins"
+    headers:
+      Authorization: "Bearer {{context.secrets.cortex_api_key}}"
+      Content-Type: application/json
+    integration: null
+    integrationAlias: null
+  outgoingActions:
+  - parse-jenkins-config
+  isRootAction: true
+- name: Parse Jenkins config
+  slug: parse-jenkins-config
+  schema:
+    type: JQ
+    expression: |
+      .actions."get-jenkins-config".outputs.body.value as $j |
+      if ($j == null or $j.job == null) then
+        error("No Jenkins configuration found. Add x-cortex-custom-metadata.jenkins with url and job to this entity.")
+      else
+        { job: $j.job }
+      end
+  outgoingActions:
+  - set-variables
+  isRootAction: false
+- name: Set variables
+  slug: set-variables
+  schema:
+    type: SET_VARIABLES
+    variables:
+    - slug: jenkins-job
+      source:
+        path: actions.parse-jenkins-config.outputs.result.job
+        type: REFERENCE
+  outgoingActions:
+  - trigger-deploy
+  isRootAction: false
+- name: Trigger Jenkins Build
+  slug: trigger-deploy
+  schema:
+    type: HTTP_REQUEST_ASYNC
+    httpMethod: POST
+    url: "JENKINS_BASE_URL/job/{{variables.jenkins-job}}/buildWithParameters"
+    integration: null
+    integrationAlias: null
+    headers:
+      Content-Type: application/x-www-form-urlencoded
+      Authorization: "Basic {{{context.secrets.jenkins_auth}}}"
+    payload: "callback_url={{{callbackUrl}}}&cortex_entity_tag={{context.entity.tag}}"
+    timeoutInSeconds: 60
+  outgoingActions: []
+  isRootAction: false

cortexapps_cli-1.36.0/cortexapps_cli/solutions/jenkins-deploy/catalog/jenkins-demo.yaml

@@ -0,0 +1,13 @@
+openapi: "3.0.0"
+info:
+  title: Jenkins Demo
+  x-cortex-tag: jenkins-demo
+  x-cortex-type: service
+  x-cortex-description: Sample service for demonstrating deploy tracking via Jenkins pipelines.
+  x-cortex-definition: {}
+  x-cortex-groups:
+    - demo-jenkins-deploys
+  x-cortex-custom-metadata:
+    jenkins:
+      url: PLACEHOLDER_JENKINS_URL
+      job: cortex-deploy

cortexapps_cli-1.36.0/cortexapps_cli/solutions/jenkins-deploy/scorecards/deploy-health.yaml

@@ -0,0 +1,51 @@
+tag: jenkins-deploy-health
+name: Jenkins Deploy Health
+description: Measures deployment cadence for services using Jenkins deploy tracking. Scoped to demo-jenkins-deploys group by default — remove the filter to apply to all services.
+draft: false
+notifications:
+  enabled: true
+  scoreDropNotificationsEnabled: true
+exemptions:
+  enabled: true
+  autoApprove: false
+evaluation:
+  window: 24
+filter:
+  kind: GENERIC
+  types:
+    include:
+      - service
+  query: hasGroup("demo-jenkins-deploys")
+ladder:
+  name: Default Ladder
+  levels:
+    - name: Bronze
+      rank: 1
+      description: Service has at least one recorded deployment in the last year.
+      color: "#CD7F32"
+    - name: Silver
+      rank: 2
+      description: Service has deployed within the last 30 days.
+      color: "#C0C0C0"
+    - name: Gold
+      rank: 3
+      description: Service has deployed within the last 7 days.
+      color: "#D7AC58"
+rules:
+  - title: Has at least one deploy
+    description: At least one deployment has been recorded in the last year.
+    expression: deploys(lookback=duration("P1Y")).length > 0
+    weight: 1
+    level: Bronze
+
+  - title: Deployed in the last 30 days
+    description: A deployment was recorded within the past 30 days.
+    expression: deploys(lookback=duration("P30D")).length > 0
+    weight: 1
+    level: Silver
+
+  - title: Deployed in the last 7 days
+    description: A deployment was recorded within the past 7 days, indicating an active delivery cadence.
+    expression: deploys(lookback=duration("P7D")).length > 0
+    weight: 1
+    level: Gold