DEV Community: David Bernard

CDEvents in Action #7: Instrument Any CI Step in a Few Lines

David Bernard — Mon, 13 Apr 2026 14:00:00 +0000

Webhook integrations (ep#3, ep#4) tell you when a pipeline started and whether it passed. They don't tell you which test suites ran, which failed, or how long each step took. send --run fills that gap.

The Pattern

Prefix any CI command with cdviz-collector send --run <type> [options] --:

# before
npm test

# after — expects npm test to produce JUnit XML output
cdviz-collector send --run testsuiterun_junit \
  --url "$CDVIZ_URL" \
  --header "Authorization: Bearer $CDVIZ_TOKEN" \
  -- npm test

The collector runs your command normally. When it exits, it emits testSuiteRun.started + testSuiteRun.finished CDEvents with parsed test results included. Your exit code is preserved — CI still fails if tests fail.

[!NOTE]
Authentication: --header "Authorization: Bearer $TOKEN" is shown here for clarity. HMAC signature authentication is also supported and may be preferred depending on your server configuration. See the send documentation for options.

Choose the Right `--run` Type

`--run` value	CDEvents emitted	When to use
`testsuiterun_junit`	`testSuiteRun.started` / `.finished`	Tests that output JUnit XML
`testsuiterun_tap`	`testSuiteRun.started` / `.finished`	Tests that output TAP format
`testsuiterun_sarif`	`testSuiteRun.started` / `.finished`	Security/lint scans (SARIF output)
`taskrun`	`taskRun.started` / `.finished`	Any other step (build, deploy, …)

[!TIP]
More options, custom run types, and output path overrides are available — see the send --run reference.

CI Auto-Detection

Branch, commit SHA, and job name are read automatically — no --metadata flags needed for those:

CI system	Variables detected automatically
GitHub Actions	`GITHUB_REF_NAME`, `GITHUB_SHA`, `GITHUB_JOB`, `GITHUB_RUN_ID`
GitLab CI	`CI_COMMIT_REF_NAME`, `CI_COMMIT_SHA`, `CI_JOB_NAME`, `CI_PIPELINE_ID`
Jenkins	`JENKINS_URL`, `JOB_BASE_NAME`, `BUILD_NUMBER`, `GIT_BRANCH`, `GIT_COMMIT`

GitHub Actions Example

Install the binary once, then wrap each step:

- name: Install cdviz-collector
  run: |
    curl --proto '=https' --tlsv1.2 -LsSf https://github.com/cdviz-dev/cdviz-collector/releases/latest/download/cdviz-collector-x86_64-unknown-linux-musl.tar.xz \
      | tar xJ -C /usr/local/bin --strip-components=1 cdviz-collector-x86_64-unknown-linux-musl/cdviz-collector
    chmod +x /usr/local/bin/cdviz-collector


- name: Build
  run: |
    cdviz-collector send --run taskrun \
      --url "${{ secrets.CDVIZ_URL }}" \
      --header "Authorization: Bearer ${{ secrets.CDVIZ_TOKEN }}" \
      -- npm run build

- name: Test # expects JUnit XML output from npm test
  run: |
    cdviz-collector send --run testsuiterun_junit \
      --url "${{ secrets.CDVIZ_URL }}" \
      --header "Authorization: Bearer ${{ secrets.CDVIZ_TOKEN }}" \
      -- npm test

Add CDVIZ_URL and CDVIZ_TOKEN as repository secrets (Settings → Secrets and variables → Actions). See the GitLab CI and Jenkins guides for equivalent setups.

Cross-Reference with an Artifact (Optional)

If you built a Docker image earlier in the pipeline, pass its digest with --metadata to link test results to that exact image:

cdviz-collector send --run testsuiterun_junit \
  --metadata "tested_artifact_id=pkg:oci/my-app@sha256:$IMAGE_SHA" \
  --url "$CDVIZ_URL" \
  --header "Authorization: Bearer $CDVIZ_TOKEN" \
  -- npm test

CDviz records a testedAgainst link between the test run and the artifact — useful for tracing which image version a test failure was against.

What You Get

Test trend dashboards — pass/fail rates per suite over time
Step durations — how long build, test, and deploy steps take per commit
Failure context — which suite failed, on which branch, at which commit
Artifact traceability — which tests ran against which image (when tested_artifact_id is set)

Beyond GitHub Stars: Tracking Real Adoption of My Open-Source Projects

David Bernard — Wed, 25 Mar 2026 15:13:02 +0000

I've been maintaining open-source tools for years.
For most of that time, I had no idea if anyone was actually using them.

Few stars. Not forks. Downloads — the thing that tells you someone ran your binary at least once.

The problem

GitHub shows download counts per release asset — but only the current total. No history.

Was there a spike after that blog post you wrote?
Did your last release get picked up faster than the one before?
Is your project quietly dying, or just slow to spread?

Stars are worse: people star repos they never use. A project with 500 stars might have 3 regular users.

npm/crates.io/PyPI have their own dashboards — they are nice for libraries and source downloads, but don't show packaged/pre-built release trends and miss the GitHub release binary entirely.

As an OSS maintainer of binary (not library), you're flying blind on actual adoption.

What I wanted

Historical view: downloads over time, per release
Trend detection: growing, stagnating, or declining?
Cross-release comparison: did v0.5.0 get picked up faster than v0.4.0?
Event correlation: Did that announcement actually move the needle?
Embeddable: something I can drop into a README

What I built

download-history — polls the GitHub API every few hours, stores daily snapshots, and visualizes trends across releases. Type owner/repo, get charts.

Charts are interactive in the browser. Also available as static SVGs for README embeds — updated daily:

![Downloads](https://api.download-history.cdviz.dev/chart/github.com/owner/repo/60d.svg)

Works for both public and private repositories (requires an access token for private repositories).
14-day free trial, no credit card, no account needed. Then 5€/year for up to 2 repositories.

What I actually learned from my own data

kubectl-view-allocations — my most popular project. Unexplained spike in December 2025 / January 2026. No new release. No announcement. Something spread it — a newsletter, someone's blog post, a company's internal tooling. I have no idea what. Without the historical chart, I'd never have noticed it happened at all. ("All time" starts with data capture)

ffizer — the opposite story. Nearly zero downloads even after new releases. That's not a product problem. That's an awareness problem. Different diagnosis, different
fix.

jdx/mise (not mine, used as reference and because I use it daily) — releases every 1–5 days, used on CI & desktop. Downloads don't spike around releases because users pull it continuously.
Context shapes how you read the charts.

The data doesn't always give you answers. But it gives you better questions.

Closing

If you maintain an OSS project that ships binaries, you probably have the same blind spot.

download-history.cdviz.dev — free 14-day trial, no sign-up. I built it for myself; if it's useful to you too, great.

Next: tracking GitHub Packages (containers, npm, Maven) and possibly GitLab — let me know if that matters to you.

What metrics do you track for your OSS projects? I'm curious what signals actually matter to other maintainers.

CDEvents in Action #6: Monitor Every Kubernetes Deployment with One Helm Command

David Bernard — Tue, 17 Mar 2026 23:00:00 +0000

After this, every Deployment, StatefulSet, and DaemonSet change in your cluster generates a CDEvent automatically — no matter how it was deployed.

Episode #5 explained the gap. This episode closes it.

What You Need

CDviz running with cdviz-collector reachable from inside the cluster
Kubernetes v1.19+ with kubectl access
Helm 3

The Command

helm install cdviz-collector oci://ghcr.io/cdviz-dev/charts/cdviz-collector \
  --set kubewatch.enabled=true \
  --namespace cdviz \
  --create-namespace

That single flag (kubewatch.enabled=true) deploys kubewatch alongside cdviz-collector and wires them together:

kubewatch watches Deployment/StatefulSet/DaemonSet changes cluster-wide (can be configured)
cdviz-collector receives kubewatch CloudEvents and transforms them to CDEvents
RBAC is configured automatically (read-only ClusterRole)

See Kubernetes (via Kubewatch) Integration for details.

Verify It Works

1. Check both pods are running:

kubectl get pods -n cdviz
# NAME                              READY   STATUS
# cdviz-collector-xxx               1/1     Running
# kubewatch-xxx                     1/1     Running

2. Trigger a test deployment:

kubectl create deployment test-nginx --image=nginx:latest

3. Confirm the CDEvent arrived:

kubectl logs -n cdviz -l app=cdviz-collector --tail=20 | grep service.deployed

You should see a service.deployed event within a few seconds. Check your Grafana dashboard — the deployment appears there too.

4. Clean up:

kubectl delete deployment test-nginx

What Gets Captured

Kubernetes change	CDEvent type
Deployment created	`service.deployed`
Image or config updated	`service.upgraded`
Deployment deleted	`service.removed`
StatefulSet / DaemonSet changes	same as above

The provided transformer for kubewatch event defines the service ID as "{{ namespace }}/{{ resource_name }}/{{ container_name }}" (where resource_name is the name of the Deployment, StatefulSet, or DaemonSet) to avoid collisions. In our example: default/test-nginx/nginx.

Limiting Scope (Optional)

By default, kubewatch watches all namespaces. To limit to specific ones:

helm upgrade cdviz-collector oci://ghcr.io/cdviz-dev/charts/cdviz-collector \
  --set kubewatch.enabled=true \
  --set kubewatch.namespaceToWatch="production,staging" \
  --namespace cdviz

This reduces event volume and avoids noise from system namespaces.

CDEvents in Action #5: The Kubernetes Deployment Blind Spot

David Bernard — Tue, 10 Mar 2026 23:00:00 +0000

ArgoCD gives you GitOps visibility. But what about the operator who ran kubectl apply during an incident? Or the platform team's helm upgrade? Those are invisible — and they're the ones that tend to cause problems.

The Gap ArgoCD Leaves

In Episode #4, you learned to capture CDEvents passively from ArgoCD webhooks — no pipeline changes, instant visibility into GitOps deployments.

But ArgoCD only sees what ArgoCD manages.

In a real cluster, deployments happen in multiple ways:

kubectl apply -f deployment.yaml — ops team responding to an incident
helm upgrade payment-api ./chart — platform team releasing a patch
kubectl set image deployment/api api=v2.1.0 — someone testing a hotfix
ArgoCD sync — your GitOps flow

Only the last one shows up in ArgoCD. The first three are invisible.

This isn't a criticism of ArgoCD. It's the right tool for what it does. The gap is that your cluster has more activity than your GitOps tool manages.

What Native Kubernetes Monitoring Adds

Instead of watching what ArgoCD knows about, you watch the Kubernetes API directly. When any Deployment, StatefulSet, or DaemonSet changes in the cluster — regardless of how it was introduced — a CDEvent is fired.

	ArgoCD notifications	Native k8s monitoring
Trigger	ArgoCD sync	Any k8s resource change
Coverage	ArgoCD-managed apps only	Every deployment method
Git context	Yes — commit, author, PR	No
Event volume	Low	Low–medium
Setup	Webhook + transformer	One Helm flag
Best for	Rich context per GitOps app	Complete cluster coverage

Use Both Together

These approaches complement each other — they don't compete.

ArgoCD notifications → service.deployed events with git commit, author, and PR context for your GitOps apps
Native k8s monitoring → service.deployed events for everything else, the kubectl runs, the manual hotfixes, the platform team's Helm releases

Combined, you have complete visibility across your cluster. When something breaks, you can see every deployment that happened — not just the ones that went through GitOps.

[!TIP]
The one thing to watch: if an app is managed by ArgoCD and you have native monitoring enabled, you may see duplicate events for ArgoCD syncs. These are easy to filter, but worth knowing up front.
Or you can use a different granularity level:

with ArgoCD: service is an ArgoCD Application

with native k8s monitoring: service is a Container (or a Deployment, StatefulSet, ...)

This is the strategy used by CDviz's built-in transformers.

CDEvents in Action #4: Webhook Transformers and Passive Monitoring

David Bernard — Mon, 20 Oct 2025 13:02:09 +0000

Stop modifying every pipeline. Learn how to collect CDEvents from platforms that already send webhooks - GitHub, GitLab, ArgoCD - by transforming their native events automatically.

From Active to Passive Monitoring

In Episode #3, you learned active integration - modifying pipelines to send CDEvents directly. This works great for new services, but what about:

100+ existing repositories you don't want to touch
Legacy pipelines that are fragile and risky to modify
Third-party tools (ArgoCD, GitHub Actions) that already send events
Compliance requirements demanding complete observability without pipeline changes
Multiple platforms (GitHub + GitLab + Jenkins) creating integration fatigue

The solution: Passive monitoring using webhook transformers. Instead of changing pipelines, you configure platforms to send their native webhooks to cdviz-collector, which transforms them into CDEvents automatically.

Active vs. Passive Integration

Understanding the difference between the two approaches:

Episode #3 (Active Integration)
├─ Modify each pipeline to send CDEvents
├─ Direct control over event content
├─ Requires touching every pipeline
└─ Best for: New services, custom events

Episode #4 (Passive Integration) ← You are here
├─ Configure webhook once per platform
├─ Automatic transformation of platform events
├─ No pipeline modifications required
└─ Best for: Existing services, standard platform events

Key insight: These approaches complement each other. Use passive integration for broad coverage, add active integration for custom events.

Three Webhook Integration Patterns

Learn how to transform native platform events into CDEvents:

Platform	Webhook Type	CDEvents Generated	Setup Complexity
GitHub	Repository webhooks	Pipeline, task, artifact, issue, PR events	Low
GitLab	Project/group webhooks	Pipeline, job, artifact, issue, MR events	Low
ArgoCD	Notifications webhooks	Deployment, incident, removal events	Medium

Platform Comparison

Feature	GitHub	GitLab	ArgoCD
Event Coverage	Workflows, jobs, releases, issues, PRs	Pipelines, jobs, releases, issues, MRs	Sync operations, health status, deployments
Authentication	HMAC-SHA256 signature	Token header	Network isolation or Authorization header
Transformer	Community (VRL)	Pro (VRL)	Community (VRL)
Configuration	Repository or Organization webhook	Project or Group webhook	Notifications ConfigMap
CDEvents Output	10+ event types	10+ event types	4+ event types

Pattern 1: GitHub Webhook Integration

Collect GitHub repository events and transform them into CDEvents automatically - workflows, jobs, releases, PRs, issues, and branches all generate CDEvents without touching your pipelines.

Quick Overview

GitHub webhooks automatically notify cdviz-collector about repository activity:

Workflows & Jobs → pipelineRun.* and taskRun.* events
Releases & Packages → artifact.published events
Pull Requests → change.* events
Issues → ticket.* events
Branches → branch.created/deleted events

🔗 Complete event mapping and setup guide

Minimal Configuration

cdviz-collector side (cdviz-collector.toml):

[remote.transformers-community]
type = "github"
owner = "cdviz-dev"
repo = "transformers-community"

[sources.github_webhook]
enabled = true
transformer_refs = ["github_events"]

[sources.github_webhook.extractor]
type = "webhook"
id = "000-github"

# Verify GitHub signature (HMAC-SHA256)
[sources.github_webhook.extractor.headers.x-hub-signature-256]
type = "signature"
signature_encoding = "hex"
signature_on = "body"
signature_prefix = "sha256="
token = "your-webhook-secret-here"

[transformers.github_events]
type = "vrl"
template_rfile = "transformers-community:///github_events/transformer.vrl"

GitHub side: Create webhook at organization or repository level

Payload URL: https://your-collector.example.com/webhook/000-github
Secret: Same token as collector configuration
Events: Workflow runs, jobs, releases, PRs, issues

🔗 Detailed GitHub webhook setup instructions

What You Get

✅ Organization-wide coverage: Configure once, all repositories tracked
✅ Zero pipeline changes: Automatic event generation
✅ Complete lifecycle: Queued → started → finished events
✅ Secure: HMAC-SHA256 signature verification

💡 Tip: For custom deployment context, combine with GitHub Action integration from Episode #3.

Pattern 2: GitLab Webhook Integration

Collect GitLab project events and transform them into CDEvents automatically - pipelines, jobs, releases, MRs, issues, and branches all generate CDEvents without touching your pipelines.

Quick Overview

GitLab webhooks automatically notify cdviz-collector about project activity:

Pipelines & Jobs → pipelineRun.* and taskRun.* events
Releases & Tags → artifact.published events
Merge Requests → change.* events (created, merged, abandoned, reviewed)
Issues → ticket.* events
Branches → branch.created/deleted events

🔗 Complete event mapping and setup guide

Minimal Configuration

cdviz-collector side (cdviz-collector.toml):

[remote.transformers-pro]
type = "github"
owner = "cdviz-dev"
repo = "transformers-pro"

[sources.gitlab_webhook]
enabled = true
transformer_refs = ["gitlab_events"]

[sources.gitlab_webhook.extractor]
type = "webhook"
id = "000-gitlab"
headers_to_keep = ["X-Gitlab-Event"]

# Verify GitLab token
[[sources.gitlab_webhook.extractor.headers]]
header = "X-Gitlab-Token"

[sources.gitlab_webhook.extractor.headers.rule]
type = "equals"
value = "your-secret-token-here"
case_sensitive = true

[transformers.gitlab_events]
type = "vrl"
template_rfile = "transformers-pro:///gitlab_events/transformer.vrl"

[!NOTE]
GitLab transformer is part of the Pro edition. See CDviz Plans.

GitLab side: Create a webhook at the group or project level

URL: https://your-collector.example.com/webhook/000-gitlab
Secret token: Same token as collector configuration
Trigger events: Pipeline, job, release, MR, issue events

🔗 Detailed GitLab webhook setup instructions

What You Get

✅ Group-wide coverage: Configure once, all projects tracked
✅ Zero pipeline changes: Automatic event generation
✅ Complete lifecycle: Queued → started → finished events
✅ Secure: Token-based authentication

💡 Tip: For Kubernetes deployment details, combine with ArgoCD integration (Pattern 3).

Pattern 3: ArgoCD Webhook Integration

Collect ArgoCD application lifecycle events and transform them into CDEvents automatically.

What Events ArgoCD Sends

ArgoCD notifications webhook can send:

Sync succeeded + healthy → service.deployed
Sync failed/error → incident.detected
Health degraded → incident.detected
App deleted → service.removed

Complete mapping: See ArgoCD Integration documentation

Configuration: cdviz-collector Side

Create a webhook source that receives and transforms ArgoCD events:

# cdviz-collector.toml

# Remote transformers repository configuration
[remote.transformers-community]
type = "github"
owner = "cdviz-dev"
repo = "transformers-community"

[sources.argocd_webhook]
enabled = true
transformer_refs = ["argocd_notifications"]

[sources.argocd_webhook.extractor]
type = "webhook"
id = "000-argocd"
headers_to_keep = []

# Optional: Verify Authorization header (when using external endpoints)
# [sources.argocd_webhook.extractor.headers.authorization]
# type = "secret"
# value = "Bearer your-secret-token-here"

# Optional: Inject environment metadata from ArgoCD destination
[sources.argocd_webhook.extractor.metadata]
environment_id = "/production/eu-1"

# Transformer from transformers-community repository
[transformers.argocd_notifications]
type = "vrl"
template_rfile = "transformers-community:///argocd_notifications/transformer.vrl"

What this does:

✅ Receives ArgoCD webhooks at http://your-collector/webhook/000-argocd
✅ Verifies authenticity using Authorization header
✅ Transforms ArgoCD notifications into CDEvents using VRL transformer
✅ Generates per-container service.deployed events automatically
✅ Routes CDEvents to configured sinks

Configuration: ArgoCD Side

Configure ArgoCD notifications to send webhooks:

Step 1: Create Webhook Service

Edit the argocd-notifications-cm ConfigMap:

kubectl edit configmap argocd-notifications-cm -n argocd

Add webhook service configuration with authentication:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-notifications-cm
  namespace: argocd
data:
  service.webhook.cdviz: |
    url: https://your-cdviz-collector.example.com/webhook/000-argocd
    headers:
    - name: Content-Type
      value: application/json
    - name: Authorization
      value: "Bearer your-secret-token-here"

Step 2: Create Notification Template

Add a unified template that sends the full application state:

template.webhook-cdviz: |
  webhook:
    cdviz:
      method: POST
      body: |
        {
          "timestamp": "{{ now | date "2006-01-02T15:04:05.000000Z07:00" }}",
          "context": {{ toJson .context }},
          "app": {{ toJson .app }}
        }

Key point: A single template handles all event types. Event detection logic is implemented in the VRL transformer, keeping ArgoCD configuration simple.

Step 3: Configure Triggers

Add triggers to filter and send relevant events:

triggers:
  trigger.on-deployed: |
    - description: Application is synced and healthy. Triggered once per commit.
      oncePer: app.status.sync.revision
      send: [webhook-cdviz]
      when: app.status.operationState != nil and app.status.operationState.phase in ['Succeeded'] and app.status.health.status == 'Healthy'

  trigger.on-health-degraded: |
    - description: Application has degraded
      send: [webhook-cdviz]
      when: app.status.health.status == 'Degraded'

  trigger.on-deleted: |
    - description: Application is being deleted
      send: [webhook-cdviz]
      when: app.metadata.deletionTimestamp != nil

  trigger.on-sync-failed: |
    - description: Application syncing has failed
      send: [webhook-cdviz]
      when: app.status.operationState != nil and app.status.operationState.phase in ['Error', 'Failed']

Step 4: Enable Notifications for Applications

Recommended: Configure default subscriptions to automatically apply notifications to all applications:

subscriptions: |
  - recipients:
    - cdviz
    triggers:
    - on-deployed
    - on-health-degraded
    - on-deleted
    - on-sync-failed

This approach reduces configuration at the application level and prevents forgetting to enable notifications for new applications.

Testing the Integration

Trigger an ArgoCD sync operation:

# Sync application manually
argocd app sync my-app

# Or push a change that triggers automatic sync
git commit -m "Update deployment" && git push

Expected CDEvents:

service.deployed - One event per container when sync succeeds and app is healthy
incident.detected - If sync fails or health degrades
service.removed - If application is deleted

What You Get Without Pipeline Changes

✅ Deployment visibility: Automatic service.deployed events for all ArgoCD apps
✅ Per-container events: Separate events for each container in the deployment
✅ Incident detection: Automatic incident.detected for sync failures and health issues
✅ PURL generation: Correct Package URL (PURL) for Helm charts, Git repos, OCI images
✅ GitOps correlation: Links deployments to source commits automatically

Advantage: ArgoCD is the deployment source of truth. Events reflect actual Kubernetes state, not just CI/CD pipeline intent.

Combining Active and Passive Integration

The most powerful observability strategy combines both approaches:

Recommended Architecture

┌─────────────────────────────────────────────────────────┐
│ GitHub/GitLab Webhooks (Passive)                        │
│ ├─ All workflows/pipelines → pipelineRun.* events       │
│ ├─ All jobs → taskRun.* events                          │
│ └─ Releases, PRs, issues → artifact.*, change.*, ...    │
└─────────────────────────────────────────────────────────┘
           ↓ Broad coverage, zero pipeline changes
┌─────────────────────────────────────────────────────────┐
│ GitHub Actions/GitLab CI Integration (Active)           │
│ ├─ Custom deployment context → service.deployed         │
│ ├─ Test results → testCaseRun.finished                  │
│ └─ Custom metadata → artifact.published                 │
└─────────────────────────────────────────────────────────┘
           ↓ Detailed context for critical workflows
┌─────────────────────────────────────────────────────────┐
│ ArgoCD Webhooks (Passive)                               │
│ ├─ Actual deployments → service.deployed                │
│ ├─ Health issues → incident.detected                    │
│ └─ Per-container events → fine-grained tracking         │
└─────────────────────────────────────────────────────────┘

Example: E-Commerce Platform

Scenario: 50 microservices, GitHub Actions for CI, ArgoCD for deployment

Passive Integration (broad coverage):

GitHub webhook → All workflows tracked automatically
ArgoCD webhook → All deployments tracked automatically
Zero pipeline modifications

Active Integration (detailed context):

Add send-cdevents action to 5 critical services
Include custom metadata: feature flags, canary percentage, rollback info
Send testCaseRun.finished events with test coverage

Result:

✅ 100% observability coverage via passive integration
✅ Rich context for critical services via active integration
✅ Minimal maintenance burden

Migration Strategy: Passive First, Active Later

Progressively adopt webhook integrations across your organization:

Phase 1: Enable Passive Monitoring (Week 1)

Configure GitHub/GitLab webhook at organization/group level
Set up cdviz-collector with webhook sources
Deploy ArgoCD notifications with default subscriptions
Validate events appearing in CDviz dashboards

Effort: 1-2 days for platform team
Impact: Immediate visibility across all repositories and deployments

Phase 2: Validate Coverage (Week 2-3)

Review dashboards to identify missing events
Check event quality (correct subject.id, environment, artifactId)
Identify gaps where passive integration isn't enough
Document custom event requirements

Effort: 1-2 weeks of observation
Impact: Understand where active integration adds value

Phase 3: Selective Active Integration (Week 4+)

Add active integration to top 5 critical services
Enhance with custom metadata (deployment strategy, SLO targets)
Send test events (testCaseRun.finished, testSuiteRun.finished)
Measure improvement in observability quality

Effort: 1-2 days per service
Impact: Rich context for critical services without modifying all pipelines

Migration Checklist

[ ] Identify platforms sending webhooks (GitHub, GitLab, ArgoCD)
[ ] Configure webhook at organization/group level (not per-repository)
[ ] Set up cdviz-collector with remote transformers
[ ] Verify webhook signature/token authentication
[ ] Test webhook delivery with sample events
[ ] Monitor CDviz dashboards for event coverage
[ ] Document gaps requiring active integration
[ ] Selectively add active integration for critical services
[ ] Measure observability improvement

Webhook Security Best Practices

Protect your webhook endpoints from unauthorized access:

GitHub HMAC-SHA256 Signature Verification

GitHub signs webhooks using HMAC-SHA256. The collector validates signatures automatically:

[sources.github_webhook.extractor.headers.x-hub-signature-256]
type = "signature"
signature_encoding = "hex"
signature_on = "body"
signature_prefix = "sha256="
token = "your-webhook-secret-here"

What this does:

✅ Verifies webhook came from GitHub
✅ Prevents replay attacks
✅ Rejects tampered payloads
❌ Blocks unauthorized requests

Best practice: Use a strong random token (32+ characters) and rotate periodically.

GitLab Token Header Validation

GitLab sends a static token in the X-Gitlab-Token header:

[[sources.gitlab_webhook.extractor.headers]]
header = "X-Gitlab-Token"

[sources.gitlab_webhook.extractor.headers.rule]
type = "equals"
value = "your-secret-token-here"
case_sensitive = true

What this does:

✅ Verifies webhook came from GitLab
✅ Simple token-based authentication
❌ Blocks unauthorized requests

Best practice: Use a UUID or strong random token, store in secrets manager.

ArgoCD: Network Isolation + Optional Header Auth

ArgoCD offers flexible security options depending on your deployment:

Option 1: Internal network (simplest)

When collector runs inside the same Kubernetes cluster:

ArgoCD side:

service.webhook.cdviz: |
  url: http://cdviz-collector.cdviz:8080/webhook/000-argocd
  headers:
  - name: Content-Type
    value: application/json

Collector side: No authentication required (rely on NetworkPolicies)

✅ No public internet exposure
✅ Use Kubernetes NetworkPolicies to restrict access
✅ Simple configuration

Option 2: Authorization header (external endpoints or defense-in-depth)

When collector is external or you want additional security:

ArgoCD side:

service.webhook.cdviz: |
  url: https://your-cdviz-collector.example.com/webhook/000-argocd
  headers:
  - name: Content-Type
    value: application/json
  - name: Authorization
    value: "Bearer your-secret-token-here"

Collector side:

[sources.argocd_webhook.extractor.headers.authorization]
type = "secret"
value = "Bearer your-secret-token-here"

✅ Works with external collectors
✅ Standard HTTP Authorization header
✅ Blocks unauthorized requests

Best practice: Use Option 1 (network isolation) when possible, add Option 2 (Authorization header) for external endpoints or defense-in-depth.

Transformer Versioning and Updates

Remote transformers enable centralized updates without changing collector configuration:

Using Specific Transformer Versions

Pin to a specific tag for stability:

[remote.raw_github]
type = "http"
endpoint = "https://raw.githubusercontent.com"

[transformers.github_events]
type = "vrl"
template_rfile = "raw_github:///cdviz-dev/transformers-community/refs/tags/v1.0.0/github_events/transformer.vrl"

Using Latest Transformers

Track the latest version automatically:

[remote.transformers-community]
type = "github"
owner = "cdviz-dev"
repo = "transformers-community"

[transformers.github_events]
type = "vrl"
template_rfile = "transformers-community:///github_events/transformer.vrl"

Trade-off:

✅ Automatic bug fixes and improvements
❌ Risk of breaking changes

Key Takeaways

🎯 Passive first: Webhook integration provides broad coverage without pipeline changes
🔧 Combine approaches: Passive for coverage, active for custom context
📊 Platform coverage: GitHub, GitLab, ArgoCD webhooks transform automatically
🔒 Security built-in: HMAC signatures, token validation, network isolation
📈 Incremental adoption: Start with webhooks, add active integration selectively
⚙️ Centralized transformers: VRL logic versioned in remote repositories
🚀 Zero pipeline changes: Organization-level webhook = all repositories covered

Webhook transformers make CDEvents observability achievable at scale. Configure once, gain visibility across all repositories and deployments without modifying pipelines.

Resources

GitHub Webhook Integration - Complete configuration guide
GitLab Webhook Integration - Complete configuration guide
ArgoCD Notifications Integration - Complete configuration guide
Transformers Documentation - VRL transformer reference
Episode #3: Direct CI/CD Integration - Active integration patterns
GitHub Actions Integration - Custom events in workflows

CDEvents in Action #3: Direct CI/CD Pipeline Integration

David Bernard — Tue, 07 Oct 2025 17:41:09 +0000

Automate CDEvents directly from your CI/CD pipelines. Learn three universal integration patterns - from curl+bash to platform plugins - with production-ready best practices for any CI/CD system.

From Manual to Automated

In Episode #2, you learned how to send CDEvents manually using curl, bash scripts, and cdviz-collector send. Now it's time to automate this within your CI/CD pipelines.

Manual event sending works for testing, but production requires:

Automatic execution: Events sent without manual intervention
Pipeline integration: Events triggered by deployments, tests, builds
Context enrichment: Include git commits, build numbers, environments
Error handling: Graceful failures that don't break pipelines
Secrets management: Secure authentication without exposing tokens

This episode focuses on direct integration - modifying your pipelines to send CDEvents. In later episodes, we'll explore passive monitoring approaches that collect events without changing every pipeline.

Three Universal Integration Patterns

These patterns work across all CI/CD systems - GitHub Actions, Jenkins, GitLab CI, CircleCI, and any platform with shell support:

Pattern	Description	Best For	Complexity
Pattern A: Curl + bash script	Direct HTTP POST with bash	Constrained environments, minimal dependencies	Low
Pattern B: cdviz-collector send	Install collector CLI, send events via command	Multiple destinations, flexibility	Medium
Pattern C: Platform-specific plugin	Use native actions/plugins/orbs	Simplest when available	Very Low

This ordering reflects progressive complexity: Pattern A shows the foundational HTTP mechanics, Pattern B adds tooling benefits, and Pattern C provides platform integration convenience.

Pattern Decision Matrix

Use Pattern A (curl + bash) if:

Your environment restricts installing binaries
You only need simple HTTP POST
You want minimal dependencies
You're comfortable maintaining bash scripts

Use Pattern B (cdviz-collector send) if:

You need to send to various destination types (HTTP, Kafka, Database, S3)
You want automatic ID and timestamp generation
You need advanced features (transformers, signatures, validation)
You're building for long-term flexibility

Use Pattern C (platform-specific plugin) if:

Your platform has a native CDEvents plugin/action
You want the simplest possible setup

Platform Compatibility Matrix

Before diving into detailed examples, here's how each pattern maps to popular CI/CD platforms:

Platform	Pattern A (Curl + Bash)	Pattern B (cdviz-collector)	Pattern C (Plugin)
Jenkins	✅ Yes	✅ Yes	❓ Plugins TBD
GitLab CI	✅ Yes	✅ Yes	❌ No native
GitHub Actions	✅ Yes	✅ Yes	✅ send-cdevents@v1
CircleCI	✅ Yes	✅ Yes	❓ Orbs TBD
Azure DevOps	✅ Yes	✅ Yes	❓ Tasks TBD
Bitbucket Pipelines	✅ Yes	✅ Yes	❌ No native
Generic/Custom	✅ If bash available	✅ If bash/curl available	❌ No native

Key Takeaway: Patterns A and B work universally on any platform with shell access. Pattern C provides the simplest experience but depends on platform-specific plugin availability.

Pattern Examples: From Curl to Plugin

The following sections show one detailed example per pattern, demonstrating the progression from foundational HTTP mechanics to platform-integrated convenience.

Pattern A: Curl + Bash (Jenkins) - Most Portable

When to use: Restricted environments, can't install binaries, minimal dependencies

Jenkins Declarative Pipeline using direct HTTP POST with bash - works anywhere with curl and openssl:

// Jenkinsfile
pipeline {
    agent any

    environment {
        CDEVENTS_ENDPOINT_URL = credentials('cdevents-endpoint-url')
        API_TOKEN = credentials('api-token')
    }

    stages {
        stage('Deploy') {
            steps {
                sh './deploy.sh'

                // Send deployment event with curl
                sh '''
                    cat > body.json <<EOF
                    {
                      "context": {
                        "version": "0.4.1",
                        "source": "${BUILD_URL}",
                        "type": "dev.cdevents.service.deployed.0.2.0",
                        "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
                      },
                      "subject": {
                        "id": "my-namespace/my-service",
                        "type": "service",
                        "content": {
                          "environment": {"id": "production"},
                          "artifactId": "pkg:oci/my-service@sha256:{digest}?repository_url=docker.io/my-org/my-service&tag={version}"
                        }
                      }
                    }
                    EOF

                    SIGNATURE=$(openssl dgst -hex -sha256 -hmac "$API_TOKEN" body.json)
                    SIGNATURE=${SIGNATURE#* }

                    curl -X POST "$CDEVENTS_ENDPOINT_URL" \
                      -H "Content-Type: application/json" \
                      -H "X-Signature: sha256=$SIGNATURE" \
                      --data @body.json

                    rm body.json
                '''
            }
        }
    }
}

What this does:

✅ Zero external dependencies (uses curl + openssl)
✅ Works in any environment with bash
✅ Full control over event payload and HTTP request
✅ HMAC signature authentication for secure delivery

Adaptation for other platforms: Replace Jenkins-specific variables ($BUILD_URL, $GIT_COMMIT) with your platform's equivalents. The curl command works identically across all systems.

Pattern B: cdviz-collector send (GitLab CI) - More Flexible

When to use: Need multiple destinations, advanced configuration, automatic ID/timestamp generation

GitLab CI using cdviz-collector CLI for enhanced features:

# .gitlab-ci.yml
stages:
  - build
  - deploy

variables:
  CDEVENTS_ENDPOINT_URL: $CDEVENTS_ENDPOINT_URL # From CI/CD variables

build:
  stage: build
  script:
    - npm install
    - npm run build

deploy:
  stage: deploy
  script:
    # Install cdviz-collector (cache this in practice)
    - curl -LO https://github.com/cdviz-dev/cdviz-collector/releases/latest/download/cdviz-collector-linux-x86_64
    - chmod +x cdviz-collector-linux-x86_64
    - mv cdviz-collector-linux-x86_64 /usr/local/bin/cdviz-collector

    # Deploy application
    - ./deploy.sh

    # Send deployment event (minimal format - collector generates ID/timestamp)
    - |
      cdviz-collector send --data '{
        "context": {
          "version": "0.4.1",
          "source": "'"${CI_PIPELINE_URL}"'",
          "type": "dev.cdevents.service.deployed.0.2.0"
        },
        "subject": {
          "id": "/my-namespace/'"${CI_PROJECT_NAME}"'",
          "type": "service",
          "content": {
            "environment": {"id": "production"},
            "artifactId": "pkg:oci/'"${CI_PROJECT_NAME}"'@sha256:{digest}?repository_url=registry.example.com/'"${CI_PROJECT_NAME}"'&tag='"${CI_COMMIT_SHORT_SHA}"'"
          }
        }
      }' --url "${CDEVENTS_ENDPOINT_URL}" \
         --header "Authorization: Bearer ${CDEVENTS_AUTH_TOKEN}"

What this does:

✅ Automatic ID and timestamp generation (no manual context.id or context.timestamp)
✅ Built-in validation of CDEvent format
✅ Support for various destination types (HTTP, Kafka, S3, Database, and more)
✅ Advanced authentication (HMAC, Bearer tokens, custom headers)
✅ Transformers and data manipulation capabilities

Adaptation for other platforms: Install cdviz-collector binary, replace GitLab variables ($CI_PIPELINE_URL, $CI_COMMIT_SHA) with your platform's equivalents.

→ cdviz-collector send documentation

Pattern C: Platform Plugin (GitHub Actions) - Easiest

When to use: Simplest approach for GitHub users, platform-native integration

GitHub Actions using the send-cdevents action for zero-configuration setup:

# .github/workflows/deploy.yml
name: Deploy Service

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy application
        run: |
          echo "Deploying to production..."
          # Your deployment commands here

      - name: Send deployment event
        uses: cdviz-dev/send-cdevents@v1
        with:
          data: |
            {
              "context": {
                "version": "0.4.1",
                "source": "https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}",
                "type": "dev.cdevents.service.deployed.0.2.0"
              },
              "subject": {
                "id": "/my-namespace/${{ github.event.repository.name }}",
                "type": "service",
                "content": {
                  "environment": {"id": "production"},
                  "artifactId": "pkg:oci/${{ github.event.repository.name }}@sha256:{digest}?repository_url=ghcr.io/${{ github.repository }}&tag=${{ github.ref_name }}"
                }
              }
            }
          url: ${{ secrets.CDEVENTS_ENDPOINT_URL }}

What this does:

✅ Automatic ID and timestamp generation
✅ Built-in validation of CDEvent format
✅ Native GitHub Actions integration
✅ Secure secrets management
✅ Zero installation required

Adaptation for other platforms: Check if your platform has a native CDEvents plugin (see Platform Compatibility Matrix). If not, use Pattern A or B.

→ send-cdevents action documentation

Complete Multi-Event Workflow Example

Real-world CI/CD pipelines generate multiple events tracking the entire software delivery lifecycle. This GitHub Actions example shows a simplified instrumentation:

# .github/workflows/complete-pipeline.yml
name: Complete CI/CD Pipeline

on:
  push:
    branches: [main]

jobs:
  build-test-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      # Build started
      - name: Build started event
        uses: cdviz-dev/send-cdevents@v1
        with:
          data: |
            {
              "context": {
                "version": "0.4.1",
                "source": "https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}",
                "type": "dev.cdevents.taskrun.started.0.2.0"
              },
              "subject": {
                "id": "build-job/${{ github.run_id }}",
                "type": "taskRun",
                "content": {
                  "taskName": "build"
                }
              }
            }
          url: ${{ secrets.CDEVENTS_ENDPOINT_URL }}

      # Build application
      - name: Build
        run: |
          npm install
          npm run build

      # Build finished
      - name: Build finished event
        if: always()
        uses: cdviz-dev/send-cdevents@v1
        with:
          data: |
            {
              "context": {
                "version": "0.4.1",
                "source": "https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}",
                "type": "dev.cdevents.taskrun.finished.0.2.0"
              },
              "subject": {
                "id": "build-job/${{ github.run_id }}",
                "type": "taskRun",
                "content": {
                  "taskName": "build",
                  "outcome": "${{ job.status }}"
                }
              }
            }
          url: ${{ secrets.CDEVENTS_ENDPOINT_URL }}

      # Test execution
      - name: Run tests
        id: test
        run: npm test
        continue-on-error: true

      # Test finished
      - name: Test finished event
        if: always()
        uses: cdviz-dev/send-cdevents@v1
        with:
          data: |
            {
              "context": {
                "version": "0.4.1",
                "source": "https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}",
                "type": "dev.cdevents.testcaserun.finished.0.2.0"
              },
              "subject": {
                "id": "test-suite/${{ github.run_id }}",
                "type": "testCaseRun",
                "content": {
                  "outcome": "${{ steps.test.outcome }}"
                }
              }
            }
          url: ${{ secrets.CDEVENTS_ENDPOINT_URL }}

      # Deploy
      - name: Deploy to production
        if: steps.test.outcome == 'success'
        run: |
          echo "Deploying to production..."

      # Deployment event
      - name: Deployment event
        if: steps.test.outcome == 'success'
        uses: cdviz-dev/send-cdevents@v1
        with:
          data: |
            {
              "context": {
                "version": "0.4.1",
                "source": "https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}",
                "type": "dev.cdevents.service.deployed.0.2.0"
              },
              "subject": {
                "id": "${{ github.event.repository.name }}/production",
                "type": "service",
                "content": {
                  "environment": {"id": "production"},
                  "artifactId": "pkg:oci/${{ github.event.repository.name }}@sha256:{digest}?repository_url=ghcr.io/${{ github.repository }}&tag=${{ github.ref_name }}"
                }
              }
            }
          url: ${{ secrets.CDEVENTS_ENDPOINT_URL }}

⚠️ Note on Complete Instrumentation: This example shows simplified instrumentation with 4 events. A fully instrumented CI/CD pipeline would generate:

pipelinerun.started + pipelinerun.finished (workflow level)
taskrun.started + taskrun.finished (for each job/stage)
testsuiterun.started + testsuiterun.finished (test suite execution)
testrun.started + testrun.finished (individual test cases)
artifact.packaged + artifact.published (when building/pushing OCI images)

Full instrumentation provides complete observability but requires more integration work. Start with key lifecycle events (build, test, deploy) and expand based on observability needs.

Interested in a dedicated article on complete pipeline instrumentation patterns? Let us know (via comment) !

Authentication & Security

All patterns support secure delivery with platform-native secrets management.

Adding Authentication to Your Pattern

Pattern A (Curl + Bash) - Already includes HMAC signature (see Jenkins example above).

Pattern B (cdviz-collector send) - Add Bearer token header:

# GitLab CI example - add authentication
deploy:
  script:
    # ... (existing deployment steps)
    - |
      cdviz-collector send --data '{...}' \
        --url "${CDEVENTS_ENDPOINT_URL}" \
        --header "Authorization: Bearer ${CDEVENTS_AUTH_TOKEN}"  # ← Add this

Pattern C (GitHub Actions) - Add HMAC signature via config:

# GitHub Actions - add HMAC signature
- name: Send with signature
  uses: cdviz-dev/send-cdevents@v1
  with:
    data: |
      {...}  # Your event payload
    url: ${{ secrets.CDEVENTS_ENDPOINT_URL }}
    config: | # ← Add this section
      [sinks.http.headers.x-signature-256]
      type = "signature"
      algorithm = "sha256"
      prefix = "sha256="
  env:
    CDVIZ_COLLECTOR__SINKS__HTTP__HEADERS__X_SIGNATURE_256__TOKEN: ${{ secrets.CDEVENTS_ENDPOINT_TOKEN }}

Error Handling

Prevent CDEvents delivery failures from breaking your pipeline:

# GitHub Actions
- name: Send event
  continue-on-error: true # ← Pipeline continues even if event fails
  uses: cdviz-dev/send-cdevents@v1

// Jenkins
try {
    sh 'cdviz-collector send ...'
} catch (Exception e) {
    echo "Failed to send CDEvent: ${e}"  // Log but don't fail
}

# GitLab CI
send_event:
  script:
    - cdviz-collector send ... || true # ← Continue on failure

My Opinionated CDEvents Best Practices

When creating CDEvents, choosing good values for key fields improves observability and event correlation.

Note: Some examples in this article simplify these rules for clarity. Follow these practices in production deployments.

context.source - Event Origin

Rule: Use the URL of the specific workflow/job execution, not just the repository.

Why: Enables tracing events back to the exact pipeline run that generated them.

# ✅ Good - Specific workflow run
"source": "https://github.com/myorg/myrepo/actions/runs/12345"
"source": "https://gitlab.com/myorg/myrepo/-/pipelines/67890"
"source": "https://jenkins.example.com/job/deploy/123"

# ❌ Avoid - Too generic - conflict when aggregated within a bigger scope
"source": "github.com/myorg/myrepo"
"source": "myrepo"

subject.id - Event Subject Identifier

Rule: Use unique, hierarchical identifiers scoped to your organization where all events are collected.

Why: Enables filtering and grouping events by service, environment, or component when events from multiple sources are aggregated together.

Important: Do NOT use subject.source - it's confusing and optional. Instead, make subject.id unique within your organization's scope and let context.source identify the event origin.

# ✅ Good - Unique within organization, hierarchical, semantic
"subject.id": "my-service/production"
"subject.id": "frontend/staging/web-app"
"subject.id": "backend/dev/api-gateway"
"subject.id": "/team/my-service/production"  # Include team for larger orgs

# ❌ Avoid - Not unique or too generic within your scope
"subject.id": "550e8400-e29b-41d4-a716-446655440000"  # UUID (use context.id for that)
"subject.id": "run-12345"  # Run-specific (use context.id for that)
"subject.id": "production"  # Too generic - which service?

environment.id - Deployment Environment

Rule: Use consistent, lowercase environment names across all services.

Why: Enables environment-level dashboards and alerts.

# ✅ Good - Consistent naming
"environment": {"id": "production"}
"environment": {"id": "staging"}
"environment": {"id": "dev"}

# ❌ Avoid - Inconsistent naming
"environment": {"id": "prod"}     # vs "production"
"environment": {"id": "STAGING"}  # vs "staging"
"environment": {"id": "dev-123"}  # too specific

artifactId - Package URL (PURL)

Rule: Follow the Package URL specification for your artifact type.

Why: Enables universal artifact identification and dependency tracking.

Common Patterns:

# OCI images (Docker/container registries)
# Note: OCI type doesn't support namespace - use query params for registry/repo
"artifactId": "pkg:oci/my-app@sha256:abc123def456...?repository_url=ghcr.io/myorg/my-app&tag=v1.2.3"
"artifactId": "pkg:oci/nginx@sha256:def456abc123...?repository_url=docker.io/library/nginx&tag=latest"

# NPM packages
"artifactId": "pkg:npm/lodash@4.17.21"

# Maven artifacts
"artifactId": "pkg:maven/org.springframework/spring-core@5.3.10"

# Generic packages
"artifactId": "pkg:generic/my-app@1.2.3"

Common Gotchas:

Digest vs Tag: Use digest (@sha256:...) for immutability, not commit SHA - this is the image digest, not the source code commit
OCI Namespace Limitation: pkg:oci/ type does NOT support namespace in the path - use repository_url query parameter instead
Registry Encoding: OCI requires repository_url query param; other types may encode registry differently
Version Semantics: For OCI, the version is the image digest, not the git commit that built it
Type-Specific Rules: Each PURL type (pkg:oci/, pkg:npm/, etc.) has unique encoding rules - always check the spec

→ Full PURL specification

Automatic ID and Timestamp Generation

Rule: Let tools generate context.id and context.timestamp when possible.

Why: Avoids manual errors and ensures content-based deduplication.

{
  "context": {
    "version": "0.4.1",
    // ✅ Omit "id" - cdviz-collector generates content-based ID
    "source": "https://github.com/myorg/myrepo/actions/runs/12345",
    "type": "dev.cdevents.service.deployed.0.2.0"
    // ✅ Omit "timestamp" - cdviz-collector uses current time
  }
}

Key Takeaways

🎯 Three universal patterns: Curl+bash → cdviz-collector → platform plugins (progressive complexity)
🔧 One pattern per platform: Jenkins (Pattern A), GitLab CI (Pattern B), GitHub Actions (Pattern C)
📊 Cross-platform compatibility: All patterns work on any platform with shell access
🔒 Security built-in: Native secrets management, HMAC signatures, error handling
📝 CDEvents best practices: Use workflow URLs for source, hierarchical subject IDs, PURL for artifacts
⚙️ Auto-generated fields: Let tools generate context.id and context.timestamp
📈 Start simple: Begin with key lifecycle events (build, test, deploy), expand as needed

Direct CI/CD integration gives you full control over CDEvents generation. These patterns work universally, letting you implement observability regardless of your tooling.

Next Steps

Try these experiments:

Start with Pattern A (curl+bash) to understand the HTTP mechanics
Upgrade to Pattern B (cdviz-collector) for production flexibility
Use Pattern C (platform plugin) if available on your platform
Apply CDEvents best practices (workflow URLs, hierarchical IDs, PURL)
Add authentication (HMAC signatures) for production deployments

Coming next in Episode #4: Advanced patterns including Jenkins plugins, shared libraries, multi-pipeline orchestration, and reusable components for enterprise CI/CD.

Also explore: Episodes 5-7 will cover passive monitoring - collecting events without modifying pipelines, perfect for legacy systems.

Resources

send-cdevents GitHub Action - Complete action reference
cdviz-collector send documentation - CLI command reference
Episode #2: Send Your First CDEvent - Foundation for these patterns
CDEvents Specification - Complete event standard reference

CDEvents in Action #2: Send Your First CDEvent

David Bernard — Wed, 01 Oct 2025 14:10:01 +0000

You've tested receiving CDEvents. Now learn how to send them from your pipelines with three progressive approaches: basic curl for testing, production bash scripts with security, and the recommended cdviz-collector send command.

The Producer Problem

In Episode #1, you learned how to simulate receiving CDEvents. Now you need to send events from your actual pipelines and tools.

But sending events properly means handling:

Correct CDEvent format: Valid JSON structure and required fields
Security: Authentication and request signing
Unique identifiers: Content-based IDs for deduplication
Accurate timestamps: ISO 8601 format with timezone
Multiple destinations: Database, webhooks, Kafka, S3

Starting with hardcoded curl commands helps you understand the basics. Then you'll graduate to production-ready solutions.

Quick Setup: Test Your Sending

Before we start sending events, let's set up a local test consumer to validate what we send. As we learned in episode 1, cdviz-collector connect makes this easy.

Launch a Local Test Consumer

Create a minimal configuration file:

# cdviz-collector-debug.toml
[http]
host = "0.0.0.0"
port = 8080

[sinks.debug]
enabled = true
type = "debug"
format = "json"
destination = "stdout"

[sources.cdevents_webhook]
enabled = true

[sources.cdevents_webhook.extractor]
type = "webhook"
id = "000-cdevents"

Launch the collector:

cdviz-collector connect -v --config ./cdviz-collector-debug.toml

What this does:

✅ Accepts CDEvents at http://localhost:8080/webhook/000-cdevents
✅ Validates CDEvent format and rejects invalid events
✅ Shows events in real-time on stdout as they arrive
✅ Provides immediate feedback for your testing

Keep this running in one terminal while you test sending events from another terminal.

Three Approaches to Send CDEvents

Each approach serves different needs and skill levels:

Approach	Best For	Setup Time	Security	Flexibility
Basic curl	Learning, quick testing	30 seconds	❌ None	Low
Production bash script	CI/CD without dependencies	5 minutes	✅ HMAC	Medium
cdviz-collector send ⭐	Production use, multiple destinations	2 minutes	✅ Full auth	High

Let's explore each approach and understand when to use them.

Approach 1: Basic Curl - Understanding the Structure

When to use: Learning CDEvents structure, quick prototyping, understanding HTTP basics

Perfect for: Developers new to CDEvents who want hands-on experience

Send a Basic CDEvent

# Send a deployment event with hardcoded values
curl -X POST http://localhost:8080/webhook/000-cdevents \
  -H "Content-Type: application/json" \
  -d '{
    "context": {
      "version": "0.4.1",
      "id": "test-123",
      "source": "my-pipeline",
      "type": "dev.cdevents.service.deployed.0.2.0",
      "timestamp": "2024-01-15T10:30:00Z"
    },
    "subject": {
      "id": "my-service",
      "type": "service",
      "content": {
        "environment": {"id": "production"},
        "artifactId": "pkg:oci/my-service@v1.2.3"
      }
    }
  }'

Check your test consumer terminal - you should see the event appear immediately.

What You Learn

✅ CDEvent structure: See exactly what fields are required
✅ HTTP basics: Understand headers and request format
✅ Quick iteration: Test different event types rapidly
✅ Immediate validation: See results in test consumer
❌ No security: No authentication or request signing
❌ Static IDs: Hardcoded ID causes deduplication issues
❌ Not production-ready: Missing security and proper ID generation

Best practice: Use basic curl to understand CDEvents structure, then graduate to more robust approaches.

Approach 2: Production-Ready Bash Script

When to use: CI/CD integration with minimal dependencies (bash, curl, openssl, uuidgen), production pipelines

Perfect for: Teams that need security but can't install cdviz-collector

Production-Ready Script Example

This script demonstrates three critical production features:

HMAC-SHA256 signature for request authentication
Unique ID using UUID v7 (time-ordered)
Current timestamp for accurate event timing

#!/usr/bin/env bash
#
# send-cdevent.sh - Production-ready CDEvent sender
#
set -euo pipefail

# Configuration (can be parameterized via environment variables)
API_TOKEN="${API_TOKEN:-your-secret-token-here}"
WEBHOOK_URL="${WEBHOOK_URL:-http://localhost:8080/webhook/000-cdevents}"

# Generate unique ID (UUID v7 - time-ordered)
EVENT_ID=$(uuidgen -7)

# Create CDEvent payload
cat > body.json <<EOF
{
  "context": {
    "version": "0.4.1",
    "id": "$EVENT_ID",
    "source": "my-pipeline",
    "type": "dev.cdevents.service.deployed.0.2.0",
    "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
  },
  "subject": {
    "id": "my-service",
    "type": "service",
    "content": {
      "environment": {"id": "production"},
      "artifactId": "pkg:oci/my-service@v1.2.3"
    }
  }
}
EOF

# Generate HMAC-SHA256 signature
SIGNATURE=$(openssl dgst -hex -sha256 -hmac "$API_TOKEN" body.json)
SIGNATURE=${SIGNATURE#* }  # Remove "SHA256(filename)= " prefix

# Send the CDEvent with signature
curl -X POST "$WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -H "X-Signature: sha256=$SIGNATURE" \
  --data @body.json

# Cleanup
rm -f body.json

echo "CDEvent sent successfully with ID: $EVENT_ID"

How to Use the Production Script

# Basic usage with defaults
./send-cdevent.sh

# Production usage with environment variables
export API_TOKEN="your-production-secret"
export WEBHOOK_URL="https://events.company.com/webhook"

./send-cdevent.sh

# Parameterize the script further by editing hardcoded values
# (service name, environment, artifact ID, etc.)

Understanding the Security Features

1. HMAC-SHA256 Signature

SIGNATURE=$(openssl dgst -hex -sha256 -hmac "$API_TOKEN" body.json)

Cryptographic proof that the sender has the secret token
Prevents unauthorized event submission
Verifiable by the receiver without sending the token

2. UUID v7 for Unique IDs

EVENT_ID=$(uuidgen -7)

Time-ordered UUIDs (includes timestamp component)
Guaranteed uniqueness without coordination
Sortable by creation time
No content-based ID chicken-and-egg problem

3. Current Timestamp

"timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"

ISO 8601 format with UTC timezone
Accurate event timing for correlation
Prevents replay attacks when combined with signature

Validating Signatures with cdviz-collector

To test signature validation, update your test consumer configuration to verify the HMAC signature by adding:

# cdviz-collector-debug.toml

...

# Validate HMAC signature
[sources.cdevents_webhook.extractor.headers.x-signature]
type = "signature"
token = "your-secret-token-here"  # Must match API_TOKEN in script
algorithm = "sha256"
prefix = "sha256="

Restart your test consumer with the updated configuration:

cdviz-collector connect -v --config ./cdviz-collector-debug.toml

Now when you run your script, the collector will Reject events with invalid or missing signatures.

Try sending with the wrong token to see rejection:

# This will be rejected
export API_TOKEN="wrong-token"
./send-cdevent.sh

What You Learn

✅ Production security: HMAC signatures for authentication
✅ Unique IDs: Time-ordered UUIDs for guaranteed uniqueness
✅ Accurate timing: Current timestamps in correct format
✅ Minimal dependencies: Requires only bash, curl, openssl, uuidgen (common Unix tools)
✅ CI/CD ready: Easy to integrate into existing pipelines
❌ No content-based deduplication: UUIDs are always unique (unlike content-based CIDs)
❌ Limited destinations: Only sends to one HTTP endpoint
❌ Manual parameterization: Must edit script or use environment variables

Best practice: Use production bash scripts when you can't install cdviz-collector but need production-grade security.

Approach 3: cdviz-collector send - Recommended ⭐

When to use: Production deployments, multiple destinations, simplicity

Perfect for: Teams wanting production features without custom scripting

[!NOTE]
You already installed cdviz-collector for the test consumer setup. If you need to install it on a different machine, see the complete installation guide.

Step 1: Send Your First Event (Simple)

The simplest approach - let cdviz-collector generate IDs and timestamps:

# Minimal CDEvent - automatic ID and timestamp
cdviz-collector send --data '{
  "context": {
    "version": "0.4.1",
    "source": "my-pipeline",
    "type": "dev.cdevents.service.deployed.0.2.0"
  },
  "subject": {
    "id": "my-service",
    "type": "service",
    "content": {
      "environment": {"id": "production"},
      "artifactId": "pkg:oci/my-service@v1.2.3"
    }
  }
}' --url http://localhost:8080/webhook/000-cdevents

What just happened:

✅ Collector generated a content-based CID automatically
✅ Collector added current timestamp automatically
✅ Event validated against CDEvents specification
✅ Sent to the webhook endpoint

Check your test consumer - the event appears with generated ID and timestamp!

Step 2: Add Authentication

Create a configuration file for authentication:

# send-config.toml
[sinks.http]
enabled = true
destination = "http://localhost:8080/webhook/000-cdevents"

# Add HMAC signature (same as bash script)
[sinks.http.headers.x-signature]
type = "signature"
token = "your-secret-token-here"
algorithm = "sha256"
prefix = "sha256="

Now send with authentication:

# Send with automatic signature generation
cdviz-collector send \
  --data '{
    "context": {
      "version": "0.4.1",
      "source": "my-pipeline",
      "type": "dev.cdevents.service.deployed.0.2.0"
    },
    "subject": {
      "id": "my-service",
      "type": "service",
      "content": {
        "environment": {"id": "production"},
        "artifactId": "pkg:oci/my-service@v1.2.3"
      }
    }
  }' \
  --config send-config.toml

Step 3: Production Deployment

For production, use environment variables to override configuration values securely:

# send-production.toml
[sinks.http]
enabled = true
destination = "https://events.company.com/webhook"

# HMAC signature (token will be overridden by environment variable)
[sinks.http.headers.x-signature]
type = "signature"
token = "placeholder"  # Will be overridden by CDVIZ_COLLECTOR__SINKS__HTTP__HEADERS__X_SIGNATURE__TOKEN
algorithm = "sha256"
prefix = "sha256="

# Additional production headers (value will be overridden by environment variable)
[sinks.http.headers.authorization]
type = "secret"
value = "placeholder"  # Will be overridden by CDVIZ_COLLECTOR__SINKS__HTTP__HEADERS__AUTHORIZATION__VALUE

Deploy in production using environment variable overrides:

# Set secrets via environment variables that override TOML configuration
export CDVIZ_COLLECTOR__SINKS__HTTP__HEADERS__X_SIGNATURE__TOKEN="your-production-secret"
export CDVIZ_COLLECTOR__SINKS__HTTP__HEADERS__AUTHORIZATION__VALUE="Bearer your-api-token"

# Send events in production
cdviz-collector send \
  --data @event.json \
  --config send-production.toml

[!TIP]
Configuration values can be overridden using environment variables with the pattern CDVIZ_COLLECTOR__SECTION__SUBSECTION__KEY. This allows keeping secrets out of configuration files. See Environment Overrides documentation for complete details.

What You Learn

✅ Simplicity: Minimal JSON, automatic ID/timestamp generation
✅ Production security: Built-in authentication without scripting
✅ Configuration-based: Secrets in config files, not code
✅ Format validation: Built-in CDEvent validation
✅ Flexibility: Easy to change destinations without code changes
✅ Best practices: Follows CDEvents recommendations automatically

❌ External dependency: Requires installing cdviz-collector
❌ Learning curve: Need to understand configuration format

Best practice: Use cdviz-collector send for all production deployments. It's simpler, more secure, and more flexible than custom scripts.

[!NOTE]
Beyond HTTP: cdviz-collector send can send to any sink type - just Kafka, just Database, just S3, or any combination of multiple destinations simultaneously. One command can target HTTP + Database, multiple Kafka topics, or any mix of available sinks. See the complete sinks documentation for all sink types and configuration examples.
Let us know if you'd like to see examples in future episodes!

Choosing Your Sending Approach

Decision Framework

Start with basic curl if:

You're learning CDEvents and want to understand the structure
You need quick experimentation without setup
You're prototyping and testing locally

Use production bash script if:

You need production security (HMAC signatures)
You can't install external dependencies in your CI/CD
You only need to send to one HTTP endpoint
You're comfortable maintaining bash scripts

Use cdviz-collector send if (⭐ Recommended):

You want production-ready features without custom scripting
You need to send to multiple destinations
You want automatic ID and timestamp generation
You prefer configuration over code
You're building for long-term maintainability

Progression Strategy

Recommended learning path:

Basic curl (5 minutes) → Understand CDEvent structure
Test with cdviz-collector connect (5 minutes) → Validate your events
cdviz-collector send (10 minutes) → Production implementation ⭐

For most teams, cdviz-collector send provides the best balance of simplicity, security, and flexibility.

Key Takeaways

🎯 Start simple: Begin with curl to understand CDEvents structure
🔒 Add security: Production requires HMAC signatures and proper IDs
⭐ Use the right tool: cdviz-collector send for production deployments
📊 Test locally: Use cdviz-collector connect to validate events
🚀 Multiple destinations: Send to HTTP, Database, Kafka, S3 simultaneously
📈 Follow best practices: Let tools generate IDs and timestamps automatically

Understanding how to send CDEvents properly is essential for SDLC observability. These three approaches give you options for every scenario, from learning to production.

Next Steps

Try these experiments:

Send a basic curl event to your local test consumer
Enhance the bash script with your own authentication
Install cdviz-collector and send with automatic ID generation
Configure multiple destinations in a single send command

In the next episode, we'll explore GitHub Actions integration - how to automatically send CDEvents from your GitHub workflows.

Resources

CDviz Documentation

cdviz-collector send documentation - Complete command reference
HTTP Sink documentation - Authentication patterns
Episode #1: Simulate a Consumer - Learn to test event reception

Alternative Tools

cdevents-tools CLI - CDEvents-native CLI for generation and sending
CDEvents Specification - Complete event standard reference

CDEvents in Action #1: Simulate a Consumer

David Bernard — Tue, 16 Sep 2025 19:18:33 +0000

Before you build your CDEvents integration, test your approach. Three methods help you understand event flows and validate your strategy before writing production code.

The Testing Problem

You understand why CDEvents matter for pipeline visibility. Now you want to integrate, but you're facing the classic integration challenge:

How do I know my events will work?
What should I expect to receive?
How do I test without building everything first?

Building an event consumer before understanding the data flow is like writing SQL queries before seeing the database schema. You need to simulate receiving events first.

Three Approaches to Simulate CDEvents Consumption

Each approach serves different needs and skill levels:

Approach	Best For	Setup Time	Real Data
webhook.site	Quick testing, event structure exploration	30 seconds	❌ Manual only
CDviz docker compose	Full pipeline simulation, realistic testing	3 minutes	✅ Demo events
cdviz-collector connect ⭐	Local development, production debugging	2 minutes	✅ Real events

Let's explore each approach and learn when to use them.

Approach 1: webhook.site - Quick Event Structure Testing

When to use: Exploring CDEvents structure, quick prototyping, learning event schemas

Perfect for: Developers new to CDEvents who want to see event structure immediately

Step 1: Get Your Unique Webhook URL

Visit webhook.site
Copy your unique URL (looks like https://webhook.site/12345678-abcd-...)
Leave the tab open to see incoming requests

Step 2: Send a Test CDEvent

# Send a deployment event to your webhook.site URL
curl -X POST https://webhook.site/YOUR-UNIQUE-ID \
  -H "Content-Type: application/json" \
  -d '{
    "context": {
      "version": "0.4.1",
      "id": "test-123",
      "source": "my-pipeline",
      "type": "dev.cdevents.service.deployed.0.2.0",
      "timestamp": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"
    },
    "subject": {
      "id": "my-service",
      "type": "service",
      "content": {
        "environment": {"id": "production"},
        "artifactId": "pkg:oci/my-service@v1.2.3"
      }
    }
  }'

Step 3: Analyze the Event Structure

Switch back to webhook.site to see your event. Notice:

Headers: Content-Type, user agent, IP address
Body: Complete CDEvent structure
Timing: When the event was received
Size: Event payload size

What You Learn

✅ Event structure: See exactly what CDEvents look like
✅ Header requirements: Understand HTTP headers needed
✅ JSON schema: Valid CDEvent format and required fields
✅ Quick iteration: Test different event types rapidly

❌ No processing: Events just display, no storage or correlation
❌ Manual only: You must send events yourself
❌ No authentication: Simple HTTP POST only

Best practice: Use webhook.site to understand CDEvents structure before building your consumer logic.

Approach 2: CDviz docker compose - Realistic Pipeline Testing

When to use: Testing complete event flows, understanding CDviz integration, realistic event scenarios

Perfect for: Teams evaluating CDviz, developers building CDEvents integration, demonstrating event flows with visual dashboards

Step 1: Start CDviz Demo Environment

# Clone and start the full CDviz stack
git clone https://github.com/cdviz-dev/cdviz.git
cd cdviz/demos/stack-compose
docker compose up

What starts up:

CDviz collector (event ingestion)
PostgreSQL + TimescaleDB (event storage)
Grafana (visualization dashboards)
Demo event generator (realistic test data)

Step 2: Observe Automatic Demo Events

Open localhost:3000 for Grafana dashboards. You'll immediately see:

Service deployments across different environments
Pipeline executions with success/failure patterns
Artifact promotions through staging to production
Timeline visualization showing event correlations

Step 3: Send Your Own Events

The CDviz collector accepts events at http://localhost:8080/webhook/000-cdevents:

# Send a custom deployment event
curl -X POST http://localhost:8080/webhook/000-cdevents \
  -H "Content-Type: application/json" \
  -d '{
    "context": {
      "version": "0.4.1",
      "id": "my-test-deployment",
      "source": "my-testing",
      "type": "dev.cdevents.service.deployed.0.2.0",
      "timestamp": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"
    },
    "subject": {
      "id": "my-namespace/my-test-service/my-container",
      "type": "service",
      "content": {
        "environment": {"id": "testing"},
        "artifactId": "pkg:oci/my-test-service@v2.1.0"
      }
    }
  }'

Result: Your event appears in Grafana dashboards alongside demo events, showing realistic integration.

Step 4: Explore Event Correlation

Browse different Grafana dashboards to understand:

Service Timeline: How your events fit into deployment flows
Environment View: Cross-environment event correlation
Activity Feed: Chronological event stream
Direct Database: Query PostgreSQL directly for custom analysis

What You Learn

✅ Complete integration: Full event processing pipeline
✅ Visual feedback: See events in realistic dashboards
✅ Event correlation: Understand how events relate to each other
✅ Storage patterns: Events stored in PostgreSQL for analysis
✅ Production simulation: Realistic event processing behavior

❌ Resource intensive: Requires Docker and multiple containers
❌ Complex setup: More moving parts than simple webhook testing

Best practice: Use CDviz docker compose when evaluating CDEvents for your team or testing integration patterns.

Approach 3: cdviz-collector connect - Recommended for Development ⭐

When to use: Local development, troubleshooting integrations, validating event flows

Perfect for: Developers building CDEvents integration, DevOps engineers debugging event flows

Step 1: Install cdviz-collector CLI

All installation options are documented at CDviz Collector Installation Guide

brew install cdviz-dev/tap/cdviz-collector

If native pre-built binary is not available for your platform (e.g. Windows) you can fallback to the docker image.

Step 2: Launch with a local debug configuration

Create a configuration with a webhook as source (input) and a debug sink (output)

# cdviz-collector-debug.toml

[http]
host = "0.0.0.0"
port = 8080

[sinks.debug]
enabled = true
type = "debug"
format = "json"
destination = "stdout"

[sources.cdevents_webhook]
enabled = true

[sources.cdevents_webhook.extractor]
type = "webhook"
id = "000-cdevents"

Launch

cdviz-collector connect -v --config ./cdviz-collector-debug.toml

What this does:

Starts a local CDviz collector instance
Shows real-time events as they arrive on stdout
Validates CDEvent format and rejects invalid events
Provides a lightweight development environment without Docker

Step 3: Send Your Own Events

# Send a custom deployment event
curl -X POST http://localhost:8080/webhook/000-cdevents \
  -H "Content-Type: application/json" \
  -d '{
    "context": {
      "version": "0.4.1",
      "id": "my-test-deployment",
      "source": "my-testing",
      "type": "dev.cdevents.service.deployed.0.2.0",
      "timestamp": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"
    },
    "subject": {
      "id": "my-namespace/my-test-service/my-container",
      "type": "service",
      "content": {
        "environment": {"id": "testing"},
        "artifactId": "pkg:oci/my-test-service@v2.1.0"
      }
    }
  }'

What You Learn

✅ CDEvent validation: Immediate feedback on event format and structure
✅ Lightweight development: No Docker required, fast startup
✅ Real-time debugging: See events as they arrive with validation feedback
✅ Configuration flexibility: Easy to modify behavior via TOML config

❌ Command-line only: No visual interface like Grafana
❌ Local only: Events not persisted or aggregated

Best practice: Use cdviz-collector connect as your primary development tool for CDEvents integration.

Choosing Your Testing Approach

Decision Framework

Start with webhook.site if:

You're new to CDEvents and want to understand event structure
You need quick experimentation with different event formats
You're prototyping and don't need full pipeline simulation

Use CDviz docker compose if:

You're evaluating CDviz for your organization
You want to see realistic event flows and correlations
You need to test integration patterns before production deployment
You want to explore Grafana dashboards and event visualization

Use cdviz-collector connect if (⭐ Recommended):

You're developing CDEvents integration locally
You want fast feedback on event validation
You prefer lightweight tools without Docker overhead
You need flexible configuration for different scenarios

Progression Strategy

Recommended learning path:

webhook.site (5 minutes) → Understand CDEvent structure
cdviz-collector connect (10 minutes) → Validate and debug locally ⭐
CDviz docker compose (15 minutes) → See complete integration with dashboards

For most developers, cdviz-collector connect provides the best balance of simplicity and functionality for ongoing development work.

This progression gives you theoretical knowledge, practical experience, and production debugging skills.

Next Steps: From Consumer to Producer

Now that you understand how to receive and inspect CDEvents, you're ready to learn how to send them from your own tools and pipelines.

Try these experiments:

Pick one simulation approach above and test it
Send different CDEvent types (service.deployed, taskrun.finished, artifact.published)
Note what you learned about event structure and timing

This foundation will help you build robust CDEvents integration in your own systems.

Key Takeaways

🎯 Test first: Simulate receiving events before building producers
🔧 Multiple tools: Different approaches serve different testing needs
⭐ Recommended approach: cdviz-collector connect for most development work
📊 Visual integration: CDviz docker compose for complete pipeline visualization
📈 Progressive learning: Start simple (webhook.site) then build practical skills

Understanding how to consume CDEvents is essential before producing them. These simulation approaches give you the foundation to build robust CDEvents integration.

Resources:

webhook.site - Instant webhook testing
CDviz Demo Setup - Full docker compose stack
CDEvents Specification - Complete event standard reference
CDviz Documentation - Complete installation and configuration guides

CDEvents in Action #0: Monitor Your Software Factory

David Bernard — Thu, 21 Aug 2025 11:12:53 +0000

You have an impressive CI/CD stack: GitHub, Jenkins, Kubernetes, Datadog, PagerDuty. But when leadership asks "How fast do we deploy?" you're opening 6
browser tabs and building spreadsheets.

The Current Reality

Before CDviz: You manually correlate data from scattered tools

Each tool has its own data, but few tools communicate with each other. You become the integration layer.

What CDviz Actually Provides Today

Event Collection: Collects events (CDEvents, native HTTP events, or states) and produces standardized CDEvents from your existing tools
Storage: PostgreSQL database with TimescaleDB extension for time-series CDEvent storage
Visualization: Pre-built Grafana dashboards for deployment tracking and execution metrics

Current Dashboards

Service and artifact deployment timeline across stages (registry, environments, etc.)
CDEvents activity feed with real-time updates
Duration metrics for tasks, pipelines, and tests
Queries to annotate runtime metrics with version information

What's Not Included (Yet)

DORA metrics calculations (you build the SQL queries)
Automated incident correlation (data is available, custom queries required)
Multi-team comparisons (possible but requires additional configuration)

5-Minute Demo: See the Difference

# Start CDviz locally
git clone https://github.com/cdviz-dev/cdviz.git
cd cdviz/demos/stack-compose
docker compose up

# Send a deployment event
curl -i -X POST http://localhost:8080/webhook/000-cdevents \
  -H "Content-Type: application/json" \
  -d '{
    "context": {
      "version": "0.4.1",
      "id": "0",
      "source": "demo",
      "type": "dev.cdevents.service.deployed.0.2.0",
      "timestamp": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"
    },
    "subject": {
      "id": "my-namespace/my-service/my-container",
      "type": "service",
      "content": {
        "environment": {
          "id": "my-group/my-region"
        },
        "artifactId": "pkg:oci/my-service@v1.2.3"
      }
    }
  }'

# View dashboard
open localhost:3000/d/demo_service_deployed/service3a-demo

Result: Event appears immediately in timeline. No manual correlation needed.

Some events are generated automatically by the demo. Browse the other dashboard to see some possibilities.

The Value: Time and Accuracy

Before CDviz:

Query GitHub: 5 minutes
Check Jenkins: 3 minutes
Correlate timestamps: 10 minutes
Build report: 15 minutes
Total: 33 minutes per request

After CDviz integration:

Open dashboard: 1 minute
Total: 1 minute

Real Questions CDviz Helps Answer

✅ "What version is running in production right now?"
✅ "When did we last deploy service X?"
✅ "Show me all deployments from last week"
✅ "What's our deployment frequency?"

🔄 "How do teams compare?" (data available, dashboard TBD)
❌ "What's our lead time?" (needs commit events integration)

Next Steps

You can look at CDviz's documentation until the coming articles about how to instrument and generate CDEvents, how to improve communication between tools via CDEvents + CDviz.

Add a friendly HTTP polling to your API with Retry-After

David Bernard — Sun, 15 May 2022 17:26:19 +0000

Polling is a way to handle long, delayed, queued, asynchron work without blocking a TCP connection. To do (long) polling on http server we need at least 2 endpoints:

The endpoint to start the work (eg: POST /start_work or POST /workfor REST like api)
The endpoint to provide the result of the work when ready, or a "not ready yet" status to tell "retry later" (eg GET /work/{work_id})

This approach implies a per endpoint logic :-( , handled by the Caller!

How to read work_id from the result of POST /start_work ? Is the status-code is 200 or 202 ?
How to convert work_id into url request for GET /work/{work_id} and handle the response (ready vs not ready) ?
What is the retry interval? Is it defined in the documentation, as an arbitrary value or as optional info in the response ?

Concept Evolution: use http redirect & retry-after

The server provides not the interval but an estimation for when to try next time via Retry-After http attribute (case insensitive).
The server provides the endpoint to get the result via the 303 SEE_OTHER status code and the Location http attribute (and indirectly triggers the retry).
The information are provided via http status code & attributes like handling of authentication, trace, circuit breaker, rate-limit...

So on caller side, the logic can be handled in a endpoint agnostic way (eg at the user-agent wrapper level), and reuse for every endpoint that use polling.

On server side, switching between polling and direct response is transparent for the caller.

✅ Pros

server can adjust Retry-After, with estimation based on current load, progress of the work,...
server can adjust the location of the response maybe to add complementary query parameters,...
the protocol becomes is agnostic of the endpoint (may could become a "standard")
the caller & user-agent are free to handle the polling as they want, it could like in the first example (with more information) or with a more complex way with queue intermediate state, via sidecar or proxy...
- user-agent is free to follow redirect automatically or not, and to handle them as a blocking or non-blocking way
- user-agent handle retry-after like retries on
- rate-limit: 429 (Too Many Request) + Retry-After
- downtime: 503 (Service Unavailable) + Retry-After
- ...
- the work_id & polling can be (nearly) hide to the Caller, it's like a regular POST request that return the response

❌ Cons

the Caller should handle response of GET /work/{work_id} as response of POST /start_work (both possible error,...)
often the implementation of user agent about following redirect, should be changed or handled by the wrapper
- the user-agent should change the method from POST to GET on redirection (allowed for 301 (Move Permanently), 302 (Found), 303 (See Other)), this behavior can be coded at the user-agent wrapper level.
- some user-agent don't handle Retry-After (remember http header are case insensitive)
- Some user-agent have a maximum number of redirect (eg with curl Maximum (50) redirects followed)

References

Extracted from RFC 7231 - Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content similar info available at M

303 See Other

... This status code is applicable to any HTTP method. It is primarily used to allow the output of a POST action to redirect the user agent to a selected resource, since doing so provides the information corresponding to the POST response in a form that can be separately identified, bookmarked, and cached, independent of the original request. ...

Retry-After > ... When sent with any 3xx (Redirection) response, Retry-After indicates the minimum time that the user agent is asked to wait before issuing the redirected request. ...

Extracted from Retry-After - HTTP | MDN

The Retry-After response HTTP header indicates how long the user agent should wait before making a follow-up request. There are three main cases this header is used:

When sent with a 503 (Service Unavailable) response, this indicates how long the service is expected to be unavailable.

When sent with a 429 (Too Many Requests) response, this indicates how long to wait before making a new request.

When sent with a redirect response, such as 301 (Moved Permanently), this indicates the minimum time that the user agent is asked to wait before issuing the redirected request.

Implementations (aka PoC)

🚧
WARNING: the code is not optimal, and lot of improvements can be done. PR & feedbacks are welcomed (improvements, implementation for other clients,...)
🚧

A basic server

For the PoC, I created a basic http service in Rust. The code is available at sandbox_http/polling/server-axum at development · davidB/sandbox_http.

async fn start_work(Extension(works): Extension<WorkDb>) -> impl IntoResponse {
    let mut rng: StdRng = SeedableRng::from_entropy();
    let work_id = Uuid::new_v4();
    let duration = Duration::from_secs(rng.gen_range(1..=20));
    let end_at = Instant::now() + duration;

    let get_url = format!("/work/{}", work_id);
    let next_try = duration.as_secs() / 2;

    let mut works = works.lock().expect("acquire works lock to start_work");
    works.insert(
        work_id,
        Work {
            work_id,
            end_at,
            duration,
            nb_get_call: 0,
        },
    );
    (
        StatusCode::SEE_OTHER,
        [
            (http::header::LOCATION, get_url),
            (http::header::RETRY_AFTER, format!("{}", next_try)),
        ],
    )
}

async fn work(Path(work_id): Path<Uuid>, Extension(works): Extension<WorkDb>) -> impl IntoResponse {
    let mut works = works.lock().expect("acquire works lock to get_work");
    tracing::info!(?work_id, "request work result");
    match works.get_mut(&work_id) {
        None => (StatusCode::NOT_FOUND).into_response(),
        Some(work) => {
            if work.end_at > Instant::now() {
                work.nb_get_call += 1;

                let get_url = format!("/work/{}", work.work_id);
                let next_try = 1;
                (
                    StatusCode::SEE_OTHER,
                    [
                        (http::header::LOCATION, get_url),
                        (http::header::RETRY_AFTER, format!("{}", next_try)),
                    ],
                )
                    .into_response()
            } else {
                (StatusCode::OK, Json(work.clone())).into_response()
            }
        }
    }
}

Do not forgot to protect the endpoint (like others) with a kind of rate-limit

Caller with curl

curl -v --location "http://localhost:8080/start_work" -d ""

Do not use -X POST but -d "" else redirection 303 does not switch from POST to GET.
Failed because curl doesn't support Retry-After when follow redirection (see date in the sample below).
Loop stops due to "maximum redirect", without this security overload on client and server.

*   Trying 127.0.0.1:8080...
* Connected to localhost (127.0.0.1) port 8080 (#0)
> POST /start_work HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.82.0
> Accept: */*
> Content-Length: 0
> Content-Type: application/x-www-form-urlencoded
> 
* Mark bundle as not supporting multiuse
< HTTP/1.1 303 See Other
< location: /work/20913b17-1df3-40ed-b26a-df50414ecc1c
< retry-after: 8
< access-control-allow-origin: *
< vary: origin
< vary: access-control-request-method
< vary: access-control-request-headers
< content-length: 0
< date: Sun, 15 May 2022 13:07:56 GMT
< 
* Connection #0 to host localhost left intact
* Issue another request to this URL: 'http://localhost:8080/work/20913b17-1df3-40ed-b26a-df50414ecc1c'
* Switch to GET
* Found bundle for host localhost: 0x5586add25af0 [serially]
* Can not multiplex, even if we wanted to!
* Re-using existing connection! (#0) with host localhost
* Connected to localhost (127.0.0.1) port 8080 (#0)
> GET /work/20913b17-1df3-40ed-b26a-df50414ecc1c HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.82.0
> Accept: */*
> 
* Mark bundle as not supporting multiuse
< HTTP/1.1 303 See Other
< location: /work/20913b17-1df3-40ed-b26a-df50414ecc1c
< retry-after: 1
< access-control-allow-origin: *
< vary: origin
< vary: access-control-request-method
< vary: access-control-request-headers
< content-length: 0
< date: Sun, 15 May 2022 13:07:56 GMT
< 

...

* Connection #0 to host localhost left intact
* Issue another request to this URL: 'http://localhost:8080/work/20913b17-1df3-40ed-b26a-df50414ecc1c'
* Found bundle for host localhost: 0x5586add25af0 [serially]
* Can not multiplex, even if we wanted to!
* Re-using existing connection! (#0) with host localhost
* Connected to localhost (127.0.0.1) port 8080 (#0)
> GET /work/20913b17-1df3-40ed-b26a-df50414ecc1c HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.82.0
> Accept: */*
> 
* Mark bundle as not supporting multiuse
< HTTP/1.1 303 See Other
< location: /work/20913b17-1df3-40ed-b26a-df50414ecc1c
< retry-after: 1
< access-control-allow-origin: *
< vary: origin
< vary: access-control-request-method
< vary: access-control-request-headers
< content-length: 0
< date: Sun, 15 May 2022 13:07:56 GMT
< 
* Connection #0 to host localhost left intact
* Maximum (50) redirects followed
curl: (47) Maximum (50) redirects followed

Caller with your favorite programming language

There is lot chance that the Retry-After is not well supported by your http client / user-agent. So
- Test it, or notify your API consumers & customers to test it
- Open a ticket/issue to the project to request support or make a PR
- provide a workaround solution (until official support):
- Disable the default follow redirection,
- Implement follow redirect with support of Retry-After into your wrapper
The way to handle delay can be shared with retry for "rate-limit", "downtime", "circuit-breaker"

As demonstration purpose I make a sample with reqwest one of the most used http client in Rust.
You can look at it at sandbox_http/polling_with_reqwest.rs at development · davidB/sandbox_http

The output of the test:

running 1 test
110ns : check info, then continue, retry or follow
4.002665744s : check info, then continue, retry or follow
5.004217149s : check info, then continue, retry or follow
6.007647326s : check info, then continue, retry or follow
7.010080187s : check info, then continue, retry or follow
8.012471894s : check info, then continue, retry or follow
[tests/polling_with_reqwest.rs:152] &body = WorkOutput {
    nb_get_call: 4,
    duration: 8s,
}
test polling_with_reqwest ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 8.03s

🎉 Success:

The first retry is after 4s because we defined on server as half of the duration of the work,
Following call as a duration around 1s
The http client doesn't included endpoint dedicated rules (no parse of the body, no build of url,...)
Supporting an other endpoint with polling doesn't require additional code
Bonus: support of downtime, cirsuit-break & rate-limit returning Retry-After

Experimentations on Bazel: Python (3), linter & pytest

David Bernard — Mon, 03 May 2021 19:36:42 +0000

In the previous articles,we saw how to launch linter for python with a custom rule, and in the one before how to launch pytest test. In this article, we'll see how to combine both usage in more friendly way (IMHO).

Since the previous article, I did more experimentations (on my side), and I was limited by my current knowledge about how to implement rules (and managed dependency). But with bazel's macro, we could fix (or reduce) some issues:

duplication of pytest's boilerplate every BUILD.bazel and *test.py
duplication between pytest and potential linter
too many custom code to please bazel

Create the macro

Create the empty tools/pytest/BUILD.bazel , just to initiate the package.

Create the macro tools/pytest/defs.bzl, it is like the existing py_test defined in exp_python/webapp/BUILD.bazel but with the call inside a function and some part configurable.

"""experience wrap py_test"""

load("@rules_python//python:defs.bzl", "py_test")
load("@my_python_deps//:requirements.bzl", "requirement")

def pytest_test(name, srcs, deps = [], args = [], **kwargs):
    """
        Call pytest
    """
    py_test(
        name = name,
        srcs = [
            "//tools/pytest:pytest_wrapper.py",
        ] + srcs,
        main = "//tools/pytest:pytest_wrapper.py",
        args = [
            "--capture=no",
        ] + args + ["$(location :%s)" % x for x in srcs],
        python_version = "PY3",
        srcs_version = "PY3",
        deps = deps + [
            requirement("pytest"),
        ],
        **kwargs
    )

load to import definition of symbols
pytest_test is the macro, in fact a function that call py_test
//tools/pytest:pytest_wrapper.py is the wrapper to call pytest (see below)
name, srcs, deps, args are the argument of that will customize
**kwargs allow to forward some args from the caller side for the part that are not overwitten by the macro
["$(location :%s)" % x for x in srcs] is to append at the end of the call the list of source file to process, to have the path of those file (srcs is a list of string at this point), we call $(location ...) to have the path in the execution context of the py_test and and the prefix : is to convert the file name into a label. It's hacky but it works

Then create the wrapper that will call pytest tools/pytest/pytest_wrapper.py

import sys
import pytest

# if using 'bazel test ...'
if __name__ == "__main__":
    sys.exit(pytest.main(sys.argv[1:]))

Replace the current call to py_test by a call to hour macro in exp_python/webapp/BUILD.bazel.

load("//tools/pytest:defs.bzl", "pytest_test")
...

# py_test(
#     name = "test",
#     srcs = [
#         "test.py",
#     ],
#     # main = "test.py",
#     args = [
#         "--capture=no",
#     ],
#     python_version = "PY3",
#     srcs_version = "PY3",
#     deps = [
#         ":webapp",
#         requirement("requests"),
#         requirement("fastapi"),
#         requirement("pytest"),
#     ],
# )

pytest_test(
    name = "test",
    srcs = ["test.py"],
    deps = [
        ":webapp",
        requirement("requests"),
        # requirement("fastapi"),
    ],
)

We keep commented the previous code for comparison, it's shorter and we move into a central shared place code that could be shared with other python package. Give a try...

❯ bazel test //exp_python/webapp:test
ERROR: /home/david/src/github.com/davidB/sandbox_bazel/exp_python/webapp/BUILD.bazel:32:12: no such target '//tools/pytest:pytest_wrapper.py': target 'pytest_wrapper.py' not declared in package 'tools/pytest'; however, a source file of this name exists.  (Perhaps add 'exports_files(["pytest_wrapper.py"])' to tools/pytest/BUILD?) defined by /home/david/src/github.com/davidB/sandbox_bazel/tools/pytest/BUILD.bazel and referenced by '//exp_python/webapp:test'
ERROR: /home/david/src/github.com/davidB/sandbox_bazel/exp_python/webapp/BUILD.bazel:32:12: no such target '//tools/pytest:pytest_wrapper.py': target 'pytest_wrapper.py' not declared in package 'tools/pytest'; however, a source file of this name exists.  (Perhaps add 'exports_files(["pytest_wrapper.py"])' to tools/pytest/BUILD?) defined by /home/david/src/github.com/davidB/sandbox_bazel/tools/pytest/BUILD.bazel and referenced by '//exp_python/webapp:test'
ERROR: Analysis of target '//exp_python/webapp:test' failed; build aborted: Analysis failed
INFO: Elapsed time: 0.704s
INFO: 0 processes.
FAILED: Build did NOT complete successfully (18 packages loaded, 19 targets configured)
FAILED: Build did NOT complete successfully (18 packages loaded, 19 targets configured)

Ok, we need to fix some stuff, because it's a macro we need to expose pytest_wrapper.py to caller of the macro. So just follow the recommendation and change the empty tools/pytest/BUILD.bazel into

exports_files(["pytest_wrapper.py"])

Retry...

❯ bazel test //exp_python/webapp:test
INFO: Analyzed target //exp_python/webapp:test (26 packages loaded, 15198 targets configured).
INFO: Found 1 test target...
Target //exp_python/webapp:test up-to-date:
  bazel-bin/exp_python/webapp/test
INFO: Elapsed time: 2.242s, Critical Path: 0.99s
INFO: 5 processes: 3 internal, 2 linux-sandbox.
INFO: Build completed successfully, 5 total actions
//exp_python/webapp:test                                                 PASSED in 0.7s

Executed 1 out of 1 test: 1 test passes.
There were tests whose specified size is too big. Use the --test_verbose_timeout_warnings command line option to see which ones these aINFO: Build completed successfully, 5 total actions

First victory.

We can now remove the boilerblate to call pytest at the end of exp_python/webapp/test.py because it is now provided by the shared tools/pytest/pytest_wrapper.py.

from fastapi.testclient import TestClient
from exp_python.webapp.main import app

client = TestClient(app)


def test_read_main():
    response = client.get("/status")
    assert response.status_code == 200
    assert response.json() == {"status": "UP", "version": "0.1.0"}

You can mofidy the test to force the fail, and check if it'll fail as expected.

Use Pytest to launch linter

Pytest have lot of plugin/extension to launch tool like black, pylint, flake8, mypy,... So instead of create one linter call we can configure pytest run all linter.

Add linter into third_party/requirements.txt

...
#test
requests==2.25.1
pytest==6.1.2

#tools
black==20.8b1
pytest-black==0.3.12
pytest-mypy==0.8.1
pytest-pylint==0.18.0
pylint==2.8.2

Configure tools/pytest/defs.bzl to also launch linter and configure the call to pytest (it's like a script and a configuration)

"""experience wrap py_test"""

load("@rules_python//python:defs.bzl", "py_test")
load("@my_python_deps//:requirements.bzl", "requirement")

def pytest_test(name, srcs, deps = [], args = [], **kwargs):
    """
        Call pytest
    """
    py_test(
        name = name,
        srcs = [
            "//tools/pytest:pytest_wrapper.py",
        ] + srcs,
        main = "//tools/pytest:pytest_wrapper.py",
        args = [
            "--capture=no",
            "--black",
            "--pylint",
            "--mypy",
        ] + args + ["$(location :%s)" % x for x in srcs],
        python_version = "PY3",
        srcs_version = "PY3",
        deps = deps + [
            requirement("pytest"),
            requirement("pytest-black"),
            requirement("pytest-pylint"),
            requirement("pytest-mypy"),
        ],
        **kwargs
    )

Run it

❯ bazel test //exp_python/webapp:test
INFO: Analyzed target //exp_python/webapp:test (20 packages loaded, 2332 targets configured).
INFO: Found 1 test target...
FAIL: //exp_python/webapp:test (see /home/david/.cache/bazel/_bazel_david/76e87152cc51687aee6e05b5bdcf89aa/execroot/__main__/bazel-out/k8-fastbuild/testlogs/exp_python/webapp/test/test.log)
INFO: From Testing //exp_python/webapp:test:
==================== Test output for //exp_python/webapp:test:
============================= test session starts ==============================
platform linux -- Python 3.9.2, pytest-6.1.2, py-1.10.0, pluggy-0.13.1
rootdir: /home/david/.cache/bazel/_bazel_david/76e87152cc51687aee6e05b5bdcf89aa/sandbox/linux-sandbox/3/execroot/__main__/bazel-out/k8-fastbuild/bin/exp_python/webapp/test.runfiles/__main__
plugins: black-0.3.12, pylint-0.18.0, mypy-0.8.1
collected 5 items
--------------------------------------------------------------------------------
Linting files
....Unable to create directory /home/david/.pylint.d
Unable to create file /home/david/.pylint.d/exp_python.__init__1.stats: [Errno 2] No such file or directory: '/home/david/.pylint.d/exp_python.__init__1.stats'

--------------------------------------------------------------------------------

exp_python/webapp/test.py FFF..

=================================== FAILURES ===================================
______________________ [pylint] exp_python/webapp/test.py ______________________
C:  1, 0: Missing module docstring (missing-module-docstring)
C:  7, 0: Missing function or method docstring (missing-function-docstring)
__________________________ exp_python/webapp/test.py ___________________________
1: error: Cannot find implementation or library stub for module named 'fastapi.testclient'
1: note: See https://mypy.readthedocs.io/en/latest/running_mypy.html#missing-imports
_________________________________ test session _________________________________
mypy exited with status 1.
===================================== mypy =====================================
exp_python/webapp/main.py:1: error: Cannot find implementation or library stub for module named 'fastapi'
Found 2 errors in 2 files (checked 1 source file)
=========================== short test summary info ============================
FAILED exp_python/webapp/test.py::PYLINT
FAILED exp_python/webapp/test.py::mypy
FAILED exp_python/webapp/test.py::mypy-status
========================= 3 failed, 2 passed in 1.99s ==========================
================================================================================
Target //exp_python/webapp:test up-to-date:
  bazel-bin/exp_python/webapp/test
INFO: Elapsed time: 3.841s, Critical Path: 3.45s
INFO: 5 processes: 3 internal, 2 linux-sandbox.
INFO: Build completed, 1 test FAILED, 5 total actions
//exp_python/webapp:test                                                 FAILED in 3.0s
  /home/david/.cache/bazel/_bazel_david/76e87152cc51687aee6e05b5bdcf89aa/execroot/__main__/bazel-out/k8-fastbuild/testlogs/exp_python/webapp/test/test.log

INFO: Build completed, 1 test FAILED, 5 total actions

Seems to work (or failed as expected, linter detect issue)

Now extend pytest_test to lint over every *.py of the package (and let pytest detects test). As we check every python file, we also need to add all their dependencies.

pytest_test(
    name = "test",
    srcs = glob(["*.py"]),
    deps = [
        ":run",
        ":webapp",
        requirement("requests"),
        requirement("fastapi"),
    ],
)

To fix the linter issue (I comments mypy, not useful for the purpose of this article), provide a configuration file for pylint and disable a pylint rule localy into run.py (full code available into the repo, see bellow). So the final tools/pytest/defs.bzl looks like (with a configuration file for the demo, provide as data to py_test and as args)

"""Wrap pytest"""

load("@rules_python//python:defs.bzl", "py_test")
load("@my_python_deps//:requirements.bzl", "requirement")

def pytest_test(name, srcs, deps = [], args = [], data = [], **kwargs):
    """
        Call pytest
    """
    py_test(
        name = name,
        srcs = [
            "//tools/pytest:pytest_wrapper.py",
        ] + srcs,
        main = "//tools/pytest:pytest_wrapper.py",
        args = [
            "--capture=no",
            "--black",
            "--pylint",
            "--pylint-rcfile=$(location //tools/pytest:.pylintrc)",
            # "--mypy",
        ] + args + ["$(location :%s)" % x for x in srcs],
        python_version = "PY3",
        srcs_version = "PY3",
        deps = deps + [
            requirement("pytest"),
            requirement("pytest-black"),
            requirement("pytest-pylint"),
            # requirement("pytest-mypy"),
        ],
        data = [
            "//tools/pytest:.pylintrc",
        ] + data,
        **kwargs
    )

And modify tools/pytest/BUILD.bazel to export configuration files.

exports_files([
    "pytest_wrapper.py",
    ".pylintrc",
])

Clean up

Remove code and reference to pytest_check (that we introduce previously), it's no longer needed. Now we have

❯ tree -a -I '.vscode|bazel-*|.venv|.git'                                                                                      21:16:36
.
├── .bazelrc
├── .bazelversion
├── BUILD.bazel
├── exp_genrule
│   ├── a.txt
│   ├── b.txt
│   └── BUILD.bazel
├── exp_python
│   └── webapp
│       ├── BUILD.bazel
│       ├── main.py
│       ├── __pycache__
│       │   └── main.cpython-39.pyc
│       ├── run.py
│       └── test.py
├── .github
│   ├── dependabot.yml
│   └── workflows
│       └── ci.yml
├── .gitignore
├── .python-version
├── setup_localdev.sh
├── third_party
│   ├── BUILD.bazel
│   └── requirements.txt
├── tools
│   ├── pytest
│   │   ├── BUILD.bazel
│   │   ├── defs.bzl
│   │   ├── .pylintrc
│   │   └── pytest_wrapper.py
│   └── workspace_status.sh
└── WORKSPACE.bazel

Limits of the solution

Dependencies of test, runtime, tools are all mixed (no isolation), but it's the common (crappy ?) way to work in python ecosystem.
The macro is harder to extract as a workspace, tools for reuse into an other project, but in the other side the code is small enough to be copied and customized for each need
No split in the output of bazel every linter and test will be show as 1 test into report of bazel.

At the end, currently it's the most pleasant solution I found to have pytest, linters run by bazel without too many (and duplicate) boilerplate into each package. A central configuration place, and pretty simple to extends if pytest as the extension (else we can tweak the pytest_wrapper.py to do complementary stuff by example).

To be continued

It's not the end, we'll continue to setup other stuff like depending of another package (a python lib), make a docker image,...

The sandbox_bazel is hosted on github (not with the same history, due to errors), use tag to have the expected view at end of article: article/6_python_3. I'll be happy to have your comments on this article, or to discuss on github repo.

Experimentations on Bazel: Python (2), linter

David Bernard — Sun, 02 May 2021 15:34:12 +0000

Time to add code formatter, checkers, linters and other tools that help to keep python code runnable, less buggy and more resilient to evolution.

Setup formatter for Editor

psf/black: The uncompromising Python code formatter will be used. Add it to thrid_party/requirements.txt

...

#tools
black==20.8b1

Relaunch ./setup_localdev.sh and configure your editor to use it (if its can use virtual env), for example for vscode .vscode/settings.json

{
    "python.pythonPath": ".venv/bin/python",
    "python.formatting.provider": "black"
}

Setup formatter for Bazel with bazel-linting-system

But bazel currently doesn't use it (to format or to check the format). After a quick search, thundergolfer/bazel-linting-system: 🌿💚 Experimental system for registering, configuring, and invoking source-code linters in Bazel. seems to be the solution, it's based on bazel's aspect something that we didn't explore or experiment yet. So give it a try by following instruction

Add to WORKSPACE.bazel

http_archive(
    name = "linting_system",
    sha256 = "",
    strip_prefix = "bazel-linting-system-0.4.0",
    url = "https://github.com/thundergolfer/bazel-linting-system/archive/v0.4.0.zip",
)

load("@linting_system//repositories:repositories.bzl", linting_sys_repositories = "repositories")
linting_sys_repositories()

load("@linting_system//repositories:go_repositories.bzl", linting_sys_deps = "go_deps")
linting_sys_deps()

Create tools/linting/aspect.bzl

load("@linting_system//:generator.bzl", "linting_aspect_generator")

lint = linting_aspect_generator(
    name = "lint",
    linters = [
        "@//tools/linting:python",
    ]
)

Create tools/linting/BUILD.bazel

load("@linting_system//:rules.bzl", "linter")

package(default_visibility = ['//visibility:public'])

linter(
    name = "python",
    executable_path = "/usr/local/bin/black",
)

Run it to test

bazel build //... \
    --aspects //tools/linting:aspect.bzl%lint \
    --output_groups=report

...
bazel-out/k8-fastbuild/bin/exp_python/double/test_linter_exe: line 26: /usr/local/bin/black: No such file or directory
...

As expected 😉 it failed because we do not have black installed on the system, and it's better when the build system take care of the installation of tool (for repeatability, and to ease the developer setup (less step and

Create tools/linting/python_linter.py

import black
import sys

if __name__ == "__main__":
    sys.exit(black.main())

manual operation)). But we can try to create a tool that will call black (or any other linter).

Modify tools/linting/BUILD.bazel to build python_linter and to use it as linter.

load("@linting_system//:rules.bzl", "linter")
load("@rules_python//python:defs.bzl", "py_binary")
load("@my_python_deps//:requirements.bzl", "requirement")

package(default_visibility = ["//visibility:public"])

py_binary(
    name = "python_linter",
    srcs = ["python_linter.py"],
    python_version = "PY3",
    srcs_version = "PY3",
    deps = [
        requirement("black"),
    ],
)
...

Try to run it python_linter

❯ bazel run //tools/linting:python_linter -- --version        
...
python_linter.py, version 20.8b1

OK, seems to work, update linter to use python_linter

...

linter(
    name = "python",
    executable = "python_linter",
)

Note that we use executable and not executable_path, after look at the rule description

linter = rule(
    implementation = _linter_impl,
    attrs = {
        "executable_path": attr.string(
            doc="Absolute path to the linter that will run",
            mandatory=False,
        ),
        "executable": attr.label(
            executable=True,
            cfg="host",
            doc="Label for an executable linter",
        ),
        "config": attr.label(
            allow_files=True,
            doc="Configuration file for linter",
        ),
        "config_option": attr.string(
            doc="The option used by the linter to pass a path to a configuration file",
        ),
        "config_str": attr.string(
            doc="Raw string configuration options to be passed to linter",
        )
    },
)

Try again

❯ bazel build //... \                                                                                                          20:48:18
          --aspects //tools/linting:aspect.bzl%lint \
          --output_groups=report
DEBUG: Rule 'linting_system' indicated that a canonical reproducible form can be obtained by modifying arguments sha256 = "a254c73bdde03214b62cacdb570229ed1a1814a2ed749448a1db4e90b18ac0a1"
DEBUG: Repository linting_system instantiated at:
  /home/david/src/github.com/davidB/sandbox_bazel/WORKSPACE.bazel:41:13: in <toplevel>
Repository rule http_archive defined at:
  /home/david/.cache/bazel/_bazel_david/76e87152cc51687aee6e05b5bdcf89aa/external/bazel_tools/tools/build_defs/repo/http.bzl:336:31: in <toplevel>
INFO: Analyzed 9 targets (0 packages loaded, 0 targets configured).
INFO: Found 9 targets...
ERROR: /home/david/src/github.com/davidB/sandbox_bazel/exp_python/webapp/BUILD.bazel:32:10: MirrorAndLint exp_python/webapp/__linting_system/run/exp_python/webapp/run.py failed: (Exit 1): run_linter_exe failed: error executing command bazel-out/k8-fastbuild/bin/exp_python/webapp/run_linter_exe 'exp_python/webapp/run.py;bazel-out/k8-fastbuild/bin/exp_python/webapp/__linting_system/run/exp_python/webapp/run.py'

Use --sandbox_debug to see verbose messages from the sandbox run_linter_exe failed: error executing command bazel-out/k8-fastbuild/bin/exp_python/webapp/run_linter_exe 'exp_python/webapp/run.py;bazel-out/k8-fastbuild/bin/exp_python/webapp/__linting_system/run/exp_python/webapp/run.py'

Use --sandbox_debug to see verbose messages from the sandbox
Traceback (most recent call last):
  File "/home/david/.cache/bazel/_bazel_david/76e87152cc51687aee6e05b5bdcf89aa/sandbox/linux-sandbox/38/execroot/__main__/bazel-out/host/bin/tools/linting/python_linter", line 388, in <module>
    Main()
  File "/home/david/.cache/bazel/_bazel_david/76e87152cc51687aee6e05b5bdcf89aa/sandbox/linux-sandbox/38/execroot/__main__/bazel-out/host/bin/tools/linting/python_linter", line 288, in Main
    module_space = FindModuleSpace()
  File "/home/david/.cache/bazel/_bazel_david/76e87152cc51687aee6e05b5bdcf89aa/sandbox/linux-sandbox/38/execroot/__main__/bazel-out/host/bin/tools/linting/python_linter", line 118, in FindModuleSpace
    raise AssertionError('Cannot find .runfiles directory for %s' % sys.argv[0])
AssertionError: Cannot find .runfiles directory for bazel-out/host/bin/tools/linting/python_linter
INFO: Elapsed time: 0.151s, Critical Path: 0.04s
INFO: 5 processes: 5 internal.
FAILED: Build did NOT complete successfully

What does it mean ? I don't know and I don't know how to fix it. I tried without success

executable = "//tools/linting:python_linter", same error
executable_path = "$(location //tools/linting:python_linter)", failed with location: command not found.

I keep the experimentation on a branch exp/linting_system and we'll try something different, make out own tools.

Make a build tool as part of project

It's something interesting to try, create as part of the project a tool to build the project. Start by revert changes made in the previous section, but keep it as inspiration to start.
Create tools/python_check/BUILD.bazel

load("@rules_python//python:defs.bzl", "py_binary")
load("@my_python_deps//:requirements.bzl", "requirement")

package(default_visibility = ["//visibility:public"])

py_binary(
    name = "python_check",
    srcs = ["python_check.py"],
    python_version = "PY3",
    srcs_version = "PY3",
    deps = [
        requirement("black"),
    ],
)

Create tools/python_check/python_check.py

import black
import sys

if __name__ == "__main__":
    sys.exit(black.main())

Try it

❯ bazel run //tools/python_check -- --version 
python_check.py, version 20.8b1

Now try to use it in exp_python/webapp/BUILD.bazel by adding

genrule(
    name = "check",
    srcs = glob(["**/*.py"]),
    outs = ["check.log"],
    cmd_bash = """(
        $(location //tools/python_check) --check --verbose $(SRCS)
        ) | tee $@
    """,
    tools = ["//tools/python_check"],
)

Try

❯ bazel build //exp_python/webapp:check 
...
/home/david/src/github.com/davidB/sandbox_bazel/exp_python/webapp/main.py already well formatted, good job.
would reformat /home/david/src/github.com/davidB/sandbox_bazel/exp_python/webapp/run.py
would reformat /home/david/src/github.com/davidB/sandbox_bazel/exp_python/webapp/test.py
Oh no! 💥 💔 💥
2 files would be reformatted, 1 file would be left unchanged.
...

Basic seems to work. What happens if instead of "--check", we let black format the code ?

/home/david/src/github.com/davidB/sandbox_bazel/exp_python/webapp/main.py already well formatted, good job.
error: cannot format /home/david/src/github.com/davidB/sandbox_bazel/exp_python/webapp/run.py: [Errno 30] Read-only file system: '/home/david/src/github.com/davidB/sandbox_bazel/exp_python/webapp/run.py'
error: cannot format /home/david/src/github.com/davidB/sandbox_bazel/exp_python/webapp/test.py: [Errno 30] Read-only file system: '/home/david/src/github.com/davidB/sandbox_bazel/exp_python/webapp/test.py'
Oh no! 💥 💔 💥
1 file left unchanged, 2 files failed to reformat.

Bazel block us to change source file, it's a pain for a formatter, but it's not a bad idea and it follows the way that bazel build commands could be run on remote build server (via CI or bazel remote execution), and that source is own and managed by the developer. But maybe bazel run could ?

❯ bazel run //tools/python_check -- --check $PWD/exp_python/**/*.py
...
would reformat /home/david/src/github.com/davidB/sandbox_bazel/exp_python/webapp/run.py
would reformat /home/david/src/github.com/davidB/sandbox_bazel/exp_python/webapp/test.py
Oh no! 💥 💔 💥
2 files would be reformatted, 1 file would be left unchanged.

$PWD because when running, the current folder is modified, so without absolute path we got Error: Invalid value for '[SRC]...': Path 'exp_python/webapp/main.py' does not exist.
**/*.py should be change if your shell doesn't support this syntax.

Try to format

❯ bazel run //tools/python_check -- $PWD/exp_python/**/*.py
...
INFO: Build completed successfully, 1 total action
reformatted /home/david/src/github.com/davidB/sandbox_bazel/exp_python/webapp/run.py
reformatted /home/david/src/github.com/davidB/sandbox_bazel/exp_python/webapp/test.py
All done! ✨ 🍰 ✨
2 files reformatted, 1 file left unchanged.

sandbox_bazel on  development [!?⇡] via 🐍 v3.9.4 
❯ bazel run //tools/python_check -- --check $PWD/exp_python/**/*.py
...
INFO: Build completed successfully, 1 total action
All done! ✨ 🍰 ✨
3 files would be left unchanged.

Hourra, we have a bazel build command able to check the code and some bazel run able to check or to update the source code.

Linting & check as test

The goal all of checkers and linters is to evaluate the quality of the code and to detect issue and to suggest improvement, like for test. So it'll make more sens to run checks via bazel test than bazel build.

❯ bazel test //exp_python/...
INFO: Analyzed 4 targets (0 packages loaded, 0 targets configured).
INFO: Found 3 targets and 1 test target...
INFO: Elapsed time: 0.091s, Critical Path: 0.01s
INFO: 1 process: 1 internal.
INFO: Build completed successfully, 1 total action
//exp_python/webapp:test                                        (cached) PASSED in 0.7s

Executed 0 out of 1 test: 1 test passes.
There were tests whose specified size is too big. Use the --test_verbose_timeout_warnings command line option to see which ones these aINFO: Build completed successfully, 1 total action

We can add a test_suite into exp_python/webapp/BUILD.bazel that depends of both py_test(name="test"...) and our genrule(name="check"...).

test_suite(
    name = "quality",
    tests = [
        "check",
        "test",
    ],
)

❯ bazel test //exp_python/...                                                                                                  12:07:31
ERROR: /home/david/src/github.com/davidB/sandbox_bazel/exp_python/webapp/BUILD.bazel:55:11: in test_suite rule '//exp_python/webapp:quality': expecting a test or a test_suite rule but '//exp_python/webapp:check' is not one.
WARNING: Target pattern parsing failed.
INFO: Analyzed 4 targets (1 packages loaded, 7 targets configured).
INFO: Found 3 targets and 1 test target...
INFO: From Executing genrule //exp_python/webapp:check:
/home/david/src/github.com/davidB/sandbox_bazel/exp_python/webapp/main.py wasn't modified on disk since last run.
/home/david/src/github.com/davidB/sandbox_bazel/exp_python/webapp/run.py wasn't modified on disk since last run.
/home/david/src/github.com/davidB/sandbox_bazel/exp_python/webapp/test.py wasn't modified on disk since last run.
All done! ✨ 🍰 ✨
3 files would be left unchanged.
ERROR: command succeeded, but there were errors parsing the target pattern
INFO: Elapsed time: 0.408s, Critical Path: 0.27s
INFO: 2 processes: 1 internal, 1 linux-sandbox.
FAILED: Build did NOT complete successfully
//exp_python/webapp:test                                        (cached) PASSED in 0.7s

Executed 0 out of 1 test: 1 test passes.
There were tests whose specified size is too big. Use the --test_verbose_timeout_warnings command line option to see which ones these are.
All tests passed but there were other errors during the build.
FAILED: Build did NOT complete successfully

check is executed but bazel is not happy in accordance to the doc of test_suite.tests (genrule are like *_binary)

No *_binary targets are accepted however, even if they happen to run a test.

It's time create our first custom rule (inspired by the Rules Tutorial - Bazel and the examples/rules at master · bazelbuild/examples.

Create tools/python_check/defs.bzl where we create a rule python_check that try to mimic the genrule that we want to convert

"""Launch the python_check tool"""

def _python_check_test_impl(ctx):
    args = ["--check", "--verbose"] + [f.path for f in ctx.files.srcs]

    ctx.actions.run_shell(
        inputs = ctx.files.srcs,
        outputs = [ctx.outputs.log],
        progress_message = "Check into %s" % ctx.outputs.log.short_path,
        command = "(%s %s) | tee '%s'" %
                  (ctx.executable.tool.path, " ".join(args), ctx.outputs.log.path),
    )

python_check = rule(
    implementation = _python_check_test_impl,
    attrs = {
        "srcs": attr.label_list(allow_files = True),
        "log": attr.output(mandatory = True),
        "tool": attr.label(
            executable = True,
            cfg = "exec",
            allow_files = True,
            default = Label("//tools/python_check"),
        ),
    },
)

A rule is composed of the declaration xxx = rule(...) and its implementation.

Then replace the genrule(name="check"...) by a call to python_check into exp_python/webapp/BUILD.bazel

load("@rules_python//python:defs.bzl", "py_binary", "py_library", "py_test")
load("@my_python_deps//:requirements.bzl", "requirement")
load("//tools/python_check:defs.bzl", "python_check")

...

python_check(
    name = "check",
    srcs = glob(["**/*.py"]),
    log = "check.log",
)
...

❯ bazel build //exp_python/webapp:check                                                                                        13:31:43
INFO: Analyzed target //exp_python/webapp:check (1 packages loaded, 4 targets configured).
INFO: Found 1 target...
Target //exp_python/webapp:check up-to-date:
  bazel-bin/exp_python/webapp/check.log
INFO: Elapsed time: 0.092s, Critical Path: 0.01s
INFO: 1 process: 1 internal.
INFO: Build completed successfully, 1 total action

now make python_check a test rule:

python_check = rule(
    ...
    test = True,
)

Re-try

❯ bazel test //exp_python/...
ERROR: /home/david/src/github.com/davidB/sandbox_bazel/tools/python_check/defs.bzl:14:20: Invalid rule class name 'python_check', test rule class names must end with '_test' and other rule classes must not
...

OK so we need to rename python_check into python_check_test into tools/python_check/defs.bzl and exp_python/webapp/BUILD.bazel and re-try

❯ bazel test //exp_python/...
ERROR: /home/david/src/github.com/davidB/sandbox_bazel/exp_python/webapp/BUILD.bazel:45:18: in python_check_test rule //exp_python/webapp:check: 
/home/david/src/github.com/davidB/sandbox_bazel/tools/python_check/defs.bzl:3:5: The rule 'python_check_test' is executable. It needs to create an executable File and pass it as the 'executable' parameter to the DefaultInfo it returns.
...

Seems that from the error message and the sample examples/line_length.bzl at master · bazelbuild/examples, that we should modify also our _impl function to return a DefaultInfo instead of running the command directly. As a test we can also remove the log attributes because the output of test is the exit code and stdout/stderr managed by bazel directly. So Update tools/python_check/defs.bzl to

"""Launch the python_check tool"""

def _python_check_test_impl(ctx):
    args = ["--check", "--verbose"] + [f.path for f in ctx.files.srcs]
    command = "%s %s" % (ctx.executable.tool.path, " ".join(args))

    # Write the file, it is executed by 'bazel test'.
    ctx.actions.write(
        output = ctx.outputs.executable,
        content = command,
    )

    # To ensure the files needed by the command are available, we put them in
    # the runfiles.
    runfiles = ctx.runfiles(files = [ctx.executable.tool] + ctx.files.srcs)
    return [DefaultInfo(runfiles = runfiles)]

python_check_test = rule(
    implementation = _python_check_test_impl,
    attrs = {
        "srcs": attr.label_list(allow_files = True),
        "tool": attr.label(
            executable = True,
            cfg = "exec",
            allow_files = True,
            default = Label("//tools/python_check"),
        ),
    },
    test = True,
)

Remove the log attribute on the caller side

python_check_test(
    name = "check",
    srcs = glob(["**/*.py"]),
)

Re-try

❯ bazel test //exp_python/...                                                                                                  14:54:01
INFO: Analyzed 4 targets (1 packages loaded, 7 targets configured).
INFO: Found 2 targets and 2 test targets...
FAIL: //exp_python/webapp:check (see /home/david/.cache/bazel/_bazel_david/76e87152cc51687aee6e05b5bdcf89aa/execroot/__main__/bazel-out/k8-fastbuild/testlogs/exp_python/webapp/check/test.log)
INFO: From Testing //exp_python/webapp:check:
==================== Test output for //exp_python/webapp:check:
/home/david/.cache/bazel/_bazel_david/76e87152cc51687aee6e05b5bdcf89aa/sandbox/linux-sandbox/15/execroot/__main__/bazel-out/k8-fastbuild/bin/exp_python/webapp/check.runfiles/__main__/exp_python/webapp/check: line 1: bazel-out/k8-opt-exec-2B5CBBC6/bin/tools/python_check/python_check: No such file or directory
================================================================================
INFO: Elapsed time: 0.210s, Critical Path: 0.06s
INFO: 2 processes: 2 linux-sandbox.
INFO: Build completed, 1 test FAILED, 2 total actions
//exp_python/webapp:test                                        (cached) PASSED in 0.7s
//exp_python/webapp:check                                                FAILED in 0.0s
  /home/david/.cache/bazel/_bazel_david/76e87152cc51687aee6e05b5bdcf89aa/execroot/__main__/bazel-out/k8-fastbuild/testlogs/exp_python/webapp/check/test.log

Executed 1 out of 2 tests: 1 test passes and 1 fails locally.
There were tests whose specified size is too big. Use the --test_verbose_timeout_warnings command line option to see which ones these a
INFO: Build completed, 1 test FAILED, 2 total actions

Failed but looks like what we expect check is now part of the test flow. But we still have issues with the path of our python_check executable or/and the way we defined the runfiles.

try to replace ctx.executable.tool.path by ctx.executable.tool.short_path

❯ bazel test //exp_python/...                                                                                                  16:29:55
INFO: Analyzed 4 targets (1 packages loaded, 7 targets configured).
INFO: Found 2 targets and 2 test targets...
FAIL: //exp_python/webapp:check (see /home/david/.cache/bazel/_bazel_david/76e87152cc51687aee6e05b5bdcf89aa/execroot/__main__/bazel-out/k8-fastbuild/testlogs/exp_python/webapp/check/test.log)
INFO: From Testing //exp_python/webapp:check:
==================== Test output for //exp_python/webapp:check:
Traceback (most recent call last):
  File "/home/david/.cache/bazel/_bazel_david/76e87152cc51687aee6e05b5bdcf89aa/sandbox/linux-sandbox/44/execroot/__main__/bazel-out/k8-fastbuild/bin/exp_python/webapp/check.runfiles/__main__/tools/python_check/python_check", line 388, in <module>
    Main()
  File "/home/david/.cache/bazel/_bazel_david/76e87152cc51687aee6e05b5bdcf89aa/sandbox/linux-sandbox/44/execroot/__main__/bazel-out/k8-fastbuild/bin/exp_python/webapp/check.runfiles/__main__/tools/python_check/python_check", line 322, in Main
    assert os.path.exists(main_filename), \
AssertionError: Cannot exec() '/home/david/.cache/bazel/_bazel_david/76e87152cc51687aee6e05b5bdcf89aa/sandbox/linux-sandbox/44/execroot/__main__/bazel-out/k8-fastbuild/bin/exp_python/webapp/check.runfiles/__main__/tools/python_check/python_check.py': file not found.

It means that short_path works but the tool is missing some dependencies. In fact we only include the entry file and not its runtime dependencies. So change the way to build runfiles by

    runfiles = ctx.runfiles(files = ctx.files.srcs)
    runfiles = runfiles.merge(ctx.attr.tool[DefaultInfo].default_runfiles)

Then

❯ bazel test //exp_python/...
INFO: Analyzed 4 targets (0 packages loaded, 0 targets configured).
INFO: Found 2 targets and 2 test targets...
INFO: Elapsed time: 0.895s, Critical Path: 0.80s
INFO: 3 processes: 4 linux-sandbox.
INFO: Build completed successfully, 3 total actions
//exp_python/webapp:check                                                PASSED in 0.3s
//exp_python/webapp:test                                                 PASSED in 0.7s

Executed 2 out of 2 tests: 2 tests pass.
There were tests whose specified size is too big. Use the --test_verbose_timeout_warnings command line option to see which ones these aINFO: Build completed successfully, 3 total actions

Seems to work, try to introduce issue format issue (like previously) to check if detected.

❯ bazel test //exp_python/...
INFO: Analyzed 4 targets (0 packages loaded, 0 targets configured).
INFO: Found 2 targets and 2 test targets...
FAIL: //exp_python/webapp:check (see /home/david/.cache/bazel/_bazel_david/76e87152cc51687aee6e05b5bdcf89aa/execroot/__main__/bazel-out/k8-fastbuild/testlogs/exp_python/webapp/check/test.log)
INFO: From Testing //exp_python/webapp:check:
==================== Test output for //exp_python/webapp:check:
/home/david/src/github.com/davidB/sandbox_bazel/exp_python/webapp/run.py wasn't modified on disk since last run.
/home/david/src/github.com/davidB/sandbox_bazel/exp_python/webapp/test.py wasn't modified on disk since last run.
would reformat /home/david/src/github.com/davidB/sandbox_bazel/exp_python/webapp/main.py
Oh no! 💥 💔 💥
1 file would be reformatted, 2 files would be left unchanged.
================================================================================
INFO: Elapsed time: 0.907s, Critical Path: 0.78s
INFO: 3 processes: 4 linux-sandbox.
INFO: Build completed, 1 test FAILED, 3 total actions
//exp_python/webapp:test                                                 PASSED in 0.7s
//exp_python/webapp:check                                                FAILED in 0.3s
  /home/david/.cache/bazel/_bazel_david/76e87152cc51687aee6e05b5bdcf89aa/execroot/__main__/bazel-out/k8-fastbuild/testlogs/exp_python/webapp/check/test.log

Executed 2 out of 2 tests: 1 test passes and 1 fails locally.
There were tests whose specified size is too big. Use the --test_verbose_timeout_warnings command line option to see which ones these aINFO: Build completed, 1 test FAILED, 3 total actions

🎉 issue is detected.

After reading the documentation for the cfg, we thing that the target is maybe a better value (simply because python always mixe all dependencies (tools, test, runtime,...) it's crappy but it's is way to work). So we now have tools/python_check/defs.bzl like

"""Launch the python_check tool"""

def _python_check_test_impl(ctx):
    # TODO find a better way to build the command/script and to escape/enclose args
    args = ["--check"] + [f.path for f in ctx.files.srcs]
    command = "%s '%s'" % (ctx.executable.tool.short_path, "' '".join(args))

    # Write the file, it is executed by 'bazel test'.
    # ctx.outputs.executable is the default value for DefaultInfo.executable
    ctx.actions.write(
        output = ctx.outputs.executable,
        content = command,
    )

    # To ensure the files needed by the command are available, we put them in
    # the runfiles.
    runfiles = ctx.runfiles(files = ctx.files.srcs)
    runfiles = runfiles.merge(ctx.attr.tool[DefaultInfo].default_runfiles)
    return [DefaultInfo(
        runfiles = runfiles,
    )]

python_check_test = rule(
    implementation = _python_check_test_impl,
    attrs = {
        "srcs": attr.label_list(allow_files = True),
        "tool": attr.label(
            executable = True,
            cfg = "target",
            default = Label("//tools/python_check"),
        ),
    },
    test = True,
)

We also remove the test_suite from exp_python/webapp/BUILD.bazel to simplify.

On more thing before the pause, we can enable CI to run test in .github/workflows/ci.yml

name: CI

on: [push, pull_request]

jobs:
  test:
    # virtual environments: https://github.com/actions/virtual-environments
    runs-on: ubuntu-20.04

    steps:
      # Caches and restores the bazelisk download directory, the bazel build directory.
      - name: Cache bazel
        uses: actions/cache@v2.1.4
        with:
          path: |
            ~/.cache/bazelisk
            ~/.cache/bazel
          key: ${{ runner.os }}-bazel-cache

      # Checks-out your repository under $GITHUB_WORKSPACE, which is the CWD for
      # the rest of the steps
      - uses: actions/checkout@v2

      - name: Run the test
        run: bazel test //...
      - name: Build the code
        run: bazel build //...

To be continued

It's not the end, we'll continue to setup linter and other stuff, but we're in a state enough to pause (it'was a long article again).

The sandbox_bazel is hosted on github (not with the same history, due to errors), use tag to have the expected view at end of article: article/5_python_2. I'll be happy to have your comments on this article, or to discuss on github repo.

DEV Community: David Bernard

CDEvents in Action #7: Instrument Any CI Step in a Few Lines

The Pattern

Choose the Right --run Type

CI Auto-Detection

GitHub Actions Example

Cross-Reference with an Artifact (Optional)

What You Get

Beyond GitHub Stars: Tracking Real Adoption of My Open-Source Projects

The problem

What I wanted

What I built

What I actually learned from my own data

Closing

CDEvents in Action #6: Monitor Every Kubernetes Deployment with One Helm Command

What You Need

The Command

Verify It Works

What Gets Captured

Limiting Scope (Optional)

CDEvents in Action #5: The Kubernetes Deployment Blind Spot

The Gap ArgoCD Leaves

What Native Kubernetes Monitoring Adds

Use Both Together

CDEvents in Action #4: Webhook Transformers and Passive Monitoring

From Active to Passive Monitoring

Active vs. Passive Integration

Three Webhook Integration Patterns

Platform Comparison

Pattern 1: GitHub Webhook Integration

Quick Overview

Minimal Configuration

What You Get

Pattern 2: GitLab Webhook Integration

Quick Overview

Minimal Configuration

What You Get

Pattern 3: ArgoCD Webhook Integration

What Events ArgoCD Sends

Configuration: cdviz-collector Side

Configuration: ArgoCD Side

Step 1: Create Webhook Service

Step 2: Create Notification Template

Step 3: Configure Triggers

Step 4: Enable Notifications for Applications

Testing the Integration

What You Get Without Pipeline Changes

Combining Active and Passive Integration

Recommended Architecture

Example: E-Commerce Platform

Migration Strategy: Passive First, Active Later

Phase 1: Enable Passive Monitoring (Week 1)

Phase 2: Validate Coverage (Week 2-3)

Phase 3: Selective Active Integration (Week 4+)

Migration Checklist

Webhook Security Best Practices

GitHub HMAC-SHA256 Signature Verification

GitLab Token Header Validation

ArgoCD: Network Isolation + Optional Header Auth

Transformer Versioning and Updates

Using Specific Transformer Versions

Using Latest Transformers

Key Takeaways

Resources

CDEvents in Action #3: Direct CI/CD Pipeline Integration

From Manual to Automated

Three Universal Integration Patterns

Pattern Decision Matrix

Platform Compatibility Matrix

Pattern Examples: From Curl to Plugin

Pattern A: Curl + Bash (Jenkins) - Most Portable

Pattern B: cdviz-collector send (GitLab CI) - More Flexible

Pattern C: Platform Plugin (GitHub Actions) - Easiest

Complete Multi-Event Workflow Example

Authentication & Security

Adding Authentication to Your Pattern

Error Handling

My Opinionated CDEvents Best Practices

context.source - Event Origin

subject.id - Event Subject Identifier

Choose the Right `--run` Type