From 99f814ff8437290cb15654402016bf6598dee8b7 Mon Sep 17 00:00:00 2001 From: "george.bafaloukas" Date: Mon, 22 Jun 2026 14:42:43 +0100 Subject: [PATCH 01/15] =?UTF-8?q?fix(ping-identity):=20address=20dev-exper?= =?UTF-8?q?ience=20feedback=20=E2=80=94=20tone,=20durability,=20AIC=20nami?= =?UTF-8?q?ng,=20skill=20purpose?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Implements actionable items from Dave Ernsting's dev-experience feedback. - Remove negative framing about Ping docs/product (node-fundamentals.md intro, Okta/Auth0 migration note) — state what content is and enables, not what docs lack - Remove temporal/release-channel statements that go stale (Rapid-channel dates, "not yet GA", "from Q3 2026") — replace with capability + link to live docs - Align pingone-st prose to "PingOne Advanced Identity Cloud (AIC)" across taxonomies and authoring rules; keep the locked pingone-st schema enum / directory tag - Add editorial-principles rule (accuracy, tone, durability) to authoring rules (both rules/authoring-rules.md and shared/templates/AUTHORING-RULES.md) - Add "What this skill does for you" line to all six SKILL.md files stating whether each generates artifacts, guides through docs, or both (direction C) ID4AI skill purpose line is worded as conceptual/non-executable to match the product reality; final framing pending PM decision (tracked separately). Validated: scripts/validate_skills.py OK (6 skills, 66 anchors); prompt validator OK. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../skills/ping-app-integration/SKILL.md | 2 ++ .../skills/ping-foundation/SKILL.md | 2 ++ .../curated/pingone-st/am-services.md | 2 +- .../skills/ping-identity-for-ai/SKILL.md | 2 ++ .../curated/agent-security-patterns.md | 2 +- .../curated/identity-for-ai-overview.md | 2 +- .../skills/ping-orchestration/SKILL.md | 2 ++ .../pingone-st/nodes/node-fundamentals.md | 2 +- .../skills/ping-quickstart/SKILL.md | 6 ++-- .../curated/common-starting-patterns.md | 2 +- .../skills/ping-universal-services/SKILL.md | 3 +- .../curated/mfa-region-and-service-model.md | 2 +- rules/authoring-rules.md | 29 ++++++++++++++++++- shared/taxonomies/capability-map.md | 2 +- shared/taxonomies/platform-families.md | 14 ++++----- shared/taxonomies/service-map.md | 8 ++--- shared/templates/AUTHORING-RULES.md | 29 ++++++++++++++++++- 17 files changed, 87 insertions(+), 24 deletions(-) diff --git a/plugins/ping-identity/skills/ping-app-integration/SKILL.md b/plugins/ping-identity/skills/ping-app-integration/SKILL.md index d59ec41..0a68132 100644 --- a/plugins/ping-identity/skills/ping-app-integration/SKILL.md +++ b/plugins/ping-identity/skills/ping-app-integration/SKILL.md @@ -11,6 +11,8 @@ metadata: Implementation skill for integrating Ping Identity into web, mobile, and application SDK experiences. +**What this skill does for you:** Generates app-side integration code — SDK wiring, OIDC/PKCE flows, token handling — and guides you through the SDK docs and troubleshooting where code generation alone is not enough. Primarily an artifact-generating skill. + ## Invocation Invoke explicitly with `/ping-app-integration` or by saying "use ping-app-integration to...". diff --git a/plugins/ping-identity/skills/ping-foundation/SKILL.md b/plugins/ping-identity/skills/ping-foundation/SKILL.md index 4fd5d87..f7b73d6 100644 --- a/plugins/ping-identity/skills/ping-foundation/SKILL.md +++ b/plugins/ping-identity/skills/ping-foundation/SKILL.md @@ -11,6 +11,8 @@ metadata: Platform setup, administration, and core configuration for all Ping Identity deployments. Covers tenant and environment setup, apps, directories, policies, branding, and on-premises software administration. MCP tools handle execution; this skill supplies architecture patterns, sequencing, configuration constraints, and guardrails. +**What this skill does for you:** Generates configuration and drives setup directly through MCP tools where they exist (PingOne, AIC); where a tool does not exist, it guides you through the docs with the correct sequencing, field constraints, and guardrails. Both modes are available — it uses whichever the platform supports for the task. + ## Invocation Invoke explicitly with `/ping-foundation` or by saying "use ping-foundation to...". diff --git a/plugins/ping-identity/skills/ping-foundation/references/curated/pingone-st/am-services.md b/plugins/ping-identity/skills/ping-foundation/references/curated/pingone-st/am-services.md index 42c6838..d973252 100644 --- a/plugins/ping-identity/skills/ping-foundation/references/curated/pingone-st/am-services.md +++ b/plugins/ping-identity/skills/ping-foundation/references/curated/pingone-st/am-services.md @@ -222,7 +222,7 @@ Per-input validation rules invoked by `ValidatedUsernameNode`, `ValidatedPasswor Default user profile attribute exposure. Foundational; rarely modified. ### Email Service -**Currently unused on AIC.** Email delivery is handled by IDM Notifications, not this AM service. Do not invest time configuring this — configure email under IDM (Identity Management → Email). +**Not used on AIC.** Email delivery is handled by IDM Notifications, not this AM service. Do not invest time configuring this — configure email under IDM (Identity Management → Email). ### Dashboard Service *(See Global services above.)* diff --git a/plugins/ping-identity/skills/ping-identity-for-ai/SKILL.md b/plugins/ping-identity/skills/ping-identity-for-ai/SKILL.md index 2ff20be..c9a09f6 100644 --- a/plugins/ping-identity/skills/ping-identity-for-ai/SKILL.md +++ b/plugins/ping-identity/skills/ping-identity-for-ai/SKILL.md @@ -11,6 +11,8 @@ metadata: AI-era identity patterns: Identity for AI, Verified Trust, agent identity, agent security, and AI application authentication. +**What this skill does for you:** Guides you through architecture, patterns, and design decisions for securing AI agents with Ping. It is currently conceptual rather than executable — there are no dedicated ID4AI MCP tools, so it does not generate ID4AI-specific configuration. For the parts that map to existing platform capabilities (e.g. agent client credentials, PingGateway routes), it hands off to `ping-foundation` and `ping-app-integration`, which generate config and code. + ## Invocation Invoke explicitly with `/ping-identity-for-ai` or by saying "use ping-identity-for-ai to...". diff --git a/plugins/ping-identity/skills/ping-identity-for-ai/references/curated/agent-security-patterns.md b/plugins/ping-identity/skills/ping-identity-for-ai/references/curated/agent-security-patterns.md index bc4d558..0e6141d 100644 --- a/plugins/ping-identity/skills/ping-identity-for-ai/references/curated/agent-security-patterns.md +++ b/plugins/ping-identity/skills/ping-identity-for-ai/references/curated/agent-security-patterns.md @@ -46,7 +46,7 @@ Registered agents appear in the AI Agents list (Directory > AI Agents in the Pin AIC provides a dedicated DCR endpoint for AI agents: `/aiagent/register` (in addition to the standard `/register`). This endpoint onboards AI agents as dynamic OAuth 2.0 clients with agent-specific defaults. -> **Availability:** Production-ready as of 2026-06-03. Currently available on the **Rapid channel** only; Regular channel promotion is planned. +> **Availability:** Channel availability changes over time — check the [AIC AI Agents release notes](https://docs.pingidentity.com/pingoneaic/release-notes/rapid-channel/ai-agents.html) before relying on this endpoint in a given tenant. AIC AI agents can perform tasks on behalf of end users through a delegated token exchange process (RFC 8693), maintaining distinct accountability and granular access control. diff --git a/plugins/ping-identity/skills/ping-identity-for-ai/references/curated/identity-for-ai-overview.md b/plugins/ping-identity/skills/ping-identity-for-ai/references/curated/identity-for-ai-overview.md index d9b7e2f..05e4455 100644 --- a/plugins/ping-identity/skills/ping-identity-for-ai/references/curated/identity-for-ai-overview.md +++ b/plugins/ping-identity/skills/ping-identity-for-ai/references/curated/identity-for-ai-overview.md @@ -75,7 +75,7 @@ Ping Identity's Identity for AI solution covers five distinct problem areas. Eac ### Agent Identity - **PingOne** — AI Agents feature; register agents as first-class OAuth 2.0 identities with lifecycle management. License: Agent IAM Core (contact Ping Sales). -- **PingOne AIC** — `/aiagent/register` DCR endpoint for dynamic agent onboarding; AI Agents admin UI in realm left-nav. **Available on Rapid channel as of 2026-06-03; Regular channel promotion planned.** +- **PingOne AIC** — `/aiagent/register` DCR endpoint for dynamic agent onboarding; AI Agents admin UI in realm left-nav. Check the [AIC release notes](https://docs.pingidentity.com/pingoneaic/release-notes/rapid-channel/ai-agents.html) for current channel availability. - **PingFederate** — Dynamic client registration (DCR) for agent self-enrollment at runtime. ### Agent Security diff --git a/plugins/ping-identity/skills/ping-orchestration/SKILL.md b/plugins/ping-identity/skills/ping-orchestration/SKILL.md index b14f352..03e0d6b 100644 --- a/plugins/ping-identity/skills/ping-orchestration/SKILL.md +++ b/plugins/ping-identity/skills/ping-orchestration/SKILL.md @@ -11,6 +11,8 @@ metadata: Design and build authentication flows, orchestration logic, and journey-based experiences across Ping Identity platforms. MCP tools handle execution; this skill supplies design patterns, node sequencing, branching logic, and platform-specific constraints. +**What this skill does for you:** Builds journeys and flows directly through MCP tools where they exist (AIC journeys); where a tool does not exist, it guides you through the design with node sequencing, branching logic, and platform constraints. Both modes are available — it uses whichever the platform supports for the task. + ## Invocation Invoke this skill explicitly with `/ping-orchestration` or by saying "use ping-orchestration to...". diff --git a/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/nodes/node-fundamentals.md b/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/nodes/node-fundamentals.md index c9fdbda..5f1c475 100644 --- a/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/nodes/node-fundamentals.md +++ b/plugins/ping-identity/skills/ping-orchestration/references/curated/pingone-st/nodes/node-fundamentals.md @@ -15,7 +15,7 @@ slug: "https://docs.pingidentity.com/auth-node-ref/latest/overview.html" # AIC — Node Fundamentals -Tribal knowledge and non-obvious invariants about how nodes behave in AIC journeys. Rules here are validated from live AIC sessions — they are not documented clearly in official docs and are common sources of bugs. +Behavioural invariants and composition rules for nodes in AIC journeys, validated against live AIC sessions. This file complements the per-node reference docs with the cross-node behaviour an agent needs to wire journeys correctly the first time. ## Scope diff --git a/plugins/ping-identity/skills/ping-quickstart/SKILL.md b/plugins/ping-identity/skills/ping-quickstart/SKILL.md index 0f4ba20..43e61e8 100644 --- a/plugins/ping-identity/skills/ping-quickstart/SKILL.md +++ b/plugins/ping-identity/skills/ping-quickstart/SKILL.md @@ -11,6 +11,8 @@ metadata: Front door for all Ping Identity work. Detects the user's platform, identifies what they are trying to accomplish, and routes them to the correct skill. +**What this skill does for you:** Orientation and routing only — it determines your platform and goal and hands off to the skill that does the work. It does not itself generate configuration or walk through product docs. + ## Invocation Invoke this skill explicitly with `/ping-quickstart` or by saying "use ping-quickstart to...". @@ -19,10 +21,9 @@ Invoke this skill explicitly with `/ping-quickstart` or by saying "use ping-quic Trigger on ANY of the following — including questions, evaluation discussions, and advisory requests: -- "Where do I start with Ping Identity?" +- "Where do I start with Ping Identity?" / "I'm new to Ping — what should I set up first?" - "Which Ping product do I need?" - "Help me choose between PingOne, PingOne Advanced Identity Cloud, and PingFederate" -- "I'm new to Ping — what should I set up first?" - "I inherited a Ping deployment and don't know where to begin" - "We're evaluating Ping Identity — what should we be asking?" - "Pros and cons of PingOne vs PingOne Advanced Identity Cloud vs PingFederate; cloud or on-prem?" @@ -32,7 +33,6 @@ Trigger on ANY of the following — including questions, evaluation discussions, - "We want to add identity verification / KYC — where do we start?" - "What's the recommended starting point for Ping employee identity?" - "What license do I need for DaVinci / Protect / Verify?" -- "I inherited a Ping deployment — where do I start?" - "Test this end to end / validate my Ping setup / how do I prove the path works before going live" **Catch-all rule:** Trigger this skill whenever the user's platform or starting point is unknown or unclear, when they use "where do we start", "what should we set up first", "what's the recommended starting point", or "not sure whether to use [product A] or [product B]" framing. Trigger on migration intents (ForgeRock → Ping, Okta → Ping, Auth0 → Ping). Trigger when platform is not yet specified and the user is in evaluation or orientation mode. diff --git a/plugins/ping-identity/skills/ping-quickstart/references/curated/common-starting-patterns.md b/plugins/ping-identity/skills/ping-quickstart/references/curated/common-starting-patterns.md index fd9dfd7..91f6b5d 100644 --- a/plugins/ping-identity/skills/ping-quickstart/references/curated/common-starting-patterns.md +++ b/plugins/ping-identity/skills/ping-quickstart/references/curated/common-starting-patterns.md @@ -160,7 +160,7 @@ Known gotchas: ## Note: Migrating from Okta or Auth0 -No public migration guide or toolset currently exists on Ping's docs for Okta or Auth0 migration. Direct the customer to their Account Executive or open a support case. Partner tooling is available but not documented on official Ping docs. +Okta and Auth0 migrations are handled as guided engagements rather than self-service. Direct the customer to their Account Executive or open a support case to access migration tooling and partner support. --- diff --git a/plugins/ping-identity/skills/ping-universal-services/SKILL.md b/plugins/ping-identity/skills/ping-universal-services/SKILL.md index 5835e13..60260d0 100644 --- a/plugins/ping-identity/skills/ping-universal-services/SKILL.md +++ b/plugins/ping-identity/skills/ping-universal-services/SKILL.md @@ -11,6 +11,8 @@ metadata: Shared strategic services used across PingOne, PingOne Advanced Identity Cloud (AIC), and Ping Software Suite — invoked from flows rather than administered as standalone products. Covers PingOne Protect (risk), PingOne Verify (identity proofing / KYC), PingOne Credentials (verifiable credentials), PingOne IGA (governance), PingOne Authorize (fine-grained authorization), and cross-platform SSO. +**What this skill does for you:** Generates service and policy configuration and drives it through MCP tools where they exist; where a tool does not exist, it guides you through the docs with the policy fields, thresholds, and node-wiring constraints for each service. Both modes are available — it uses whichever the platform supports for the task. + ## Invocation Invoke explicitly with `/ping-universal-services` or by saying "use ping-universal-services to...". @@ -35,7 +37,6 @@ Invoke explicitly with `/ping-universal-services` or by saying "use ping-univers - If the user mentions "add security" or "prevent suspicious logins" without naming a specific service, ask a clarifying question — the task may be Protect (risk scoring) or just MFA (orchestration). - If the task is **MFA node/connector wiring within a journey or flow** (not MFA policy or device management): use `ping-orchestration` — that is flow design, not service configuration. - If the task is generic app / SDK integration without referencing a named Universal Service: use `ping-app-integration`. -- **PingOne Recognize** — not yet GA; this skill will cover it when available. ## Multi-skill use cases diff --git a/plugins/ping-identity/skills/ping-universal-services/references/curated/mfa-region-and-service-model.md b/plugins/ping-identity/skills/ping-universal-services/references/curated/mfa-region-and-service-model.md index e733566..18b9a8a 100644 --- a/plugins/ping-identity/skills/ping-universal-services/references/curated/mfa-region-and-service-model.md +++ b/plugins/ping-identity/skills/ping-universal-services/references/curated/mfa-region-and-service-model.md @@ -93,7 +93,7 @@ Methods available depend on environment type and service model: | Windows / Mac login | — | — | ✓ (PingID service) | | RADIUS Gateway (VPN) | — | ✓ | ✓ | -> **Native region limitation (current):** Some PingID integrations (Windows/Mac login, desktop app, YubiKey OTP) are not yet available in native V2 regions. These will be introduced progressively from Q3 2026. Check `docs.pingidentity.com/pingone/strong_authentication_mfa/` for the latest availability. +> **Native region note:** Availability of some PingID integrations (Windows/Mac login, desktop app, YubiKey OTP) varies by region and is expanding over time. Check `docs.pingidentity.com/pingone/strong_authentication_mfa/` for the methods available in the target region before designing around them. --- diff --git a/rules/authoring-rules.md b/rules/authoring-rules.md index 3ecd4e7..bc0b725 100644 --- a/rules/authoring-rules.md +++ b/rules/authoring-rules.md @@ -116,14 +116,41 @@ slug: "" # canonical docs URL for this topic | Value | Platform | |---|---| | `pingone-mt` | PingOne (multi-tenant cloud) | -| `pingone-st` | PingOne ST (single-tenant) | +| `pingone-st` | PingOne Advanced Identity Cloud (AIC) | | `ping-software` | Ping Software Suite (on-premises) | | `cross-platform` | Spans multiple platform families | +> **Naming note:** The `pingone-st` value is a stable internal routing tag and directory name — it denotes **PingOne Advanced Identity Cloud (AIC)**. Always call the platform "PingOne Advanced Identity Cloud (AIC)" or "AIC" in prose. Never surface "PingOne ST" or "single-tenant" as the product name in author-facing or agent-facing text. + Use `cross-platform` only when the content genuinely applies without modification to two or more platform families. If a doc has platform-specific sections, pick the primary family and note variants in the body. --- +## 1a. Editorial principles — accuracy, tone, and durability + +Skills and MCP tool descriptions ride alongside the product and the official docs. They must not get ahead of shipped behaviour, and they must not editorialise about Ping's own products or documentation. + +**Follow the product — do not jump ahead of it.** Only document behaviour that is shipped and documented. If a capability is not yet supported by the product or has no stable querying logic, do not invent it in a skill or MCP description. When in doubt, defer to the official docs. + +**No statements that go stale.** Do not bake release timing, channel state, or version-promotion plans into reference prose. These rot between updates and mislead agents. + +- ❌ "Available on the Rapid channel as of 2026-06-03; Regular channel promotion planned." +- ❌ "Not yet GA; this skill will cover it when available." +- ❌ "These will be introduced progressively from Q3 2026." +- ✅ State the capability, then link to the live release notes / docs for current availability: "Check the [AIC release notes](…) for current channel availability." + +If availability genuinely gates usage, express it as a durable constraint plus a pointer to the authoritative source — not a dated promise. + +**No negative framing about Ping docs or products.** Reference files describe capability and behaviour neutrally. Do not characterise the official docs or product as deficient, and do not position skill content as compensating for them. + +- ❌ "Not documented clearly in official docs and a common source of bugs." +- ❌ "Tribal knowledge the docs don't cover." +- ✅ "Behavioural invariants validated against live sessions; complements the per-node reference docs." + +The test: state what the content **is** and what it **enables**, not what the docs or product **lack**. + +--- + ## 2. Curated anchors — how to write them ### Curated anchors (`references/curated/`) diff --git a/shared/taxonomies/capability-map.md b/shared/taxonomies/capability-map.md index ab275b7..67d4d2e 100644 --- a/shared/taxonomies/capability-map.md +++ b/shared/taxonomies/capability-map.md @@ -8,7 +8,7 @@ Maps user intents to the owning umbrella skill. Used by SKILL.md routing logic a |---|---|---| | Orientation / "Where do I start?" | ping-quickstart | Product detection, platform selection, initial direction | | Setup / Admin / Configuration | ping-foundation | Tenant setup, apps, directories, policies, branding, on-prem admin | -| Flows / Journeys / Orchestration | ping-orchestration | DaVinci flows, PingOne ST journeys, PingAM auth trees | +| Flows / Journeys / Orchestration | ping-orchestration | DaVinci flows, AIC journeys, PingAM auth trees | | AI identity / Agent trust | ping-identity-for-ai | Identity for AI, Verified Trust, agent security patterns | | Shared strategic services | ping-universal-services | Protect, Verify, Credentials, SSO, IGA, Neo, Authorize | | App / SDK / mobile integration | ping-app-integration | Web, mobile, SDK, browser flows, on-prem app integration | diff --git a/shared/taxonomies/platform-families.md b/shared/taxonomies/platform-families.md index ecbc308..803d2e1 100644 --- a/shared/taxonomies/platform-families.md +++ b/shared/taxonomies/platform-families.md @@ -11,13 +11,13 @@ Cloud-hosted administration surface: environment setup, tenant management, apps, **Routing tag:** `pingone-mt` -## PingOne ST +## PingOne Advanced Identity Cloud (AIC) -Fully managed identity platform built on PingAM/ForgeRock lineage. Distinct control plane, object model, and administration UI from PingOne MT. +Fully managed identity platform built on PingAM, PingIDM, and PingDS. Distinct control plane, object model, and administration UI from PingOne (multi-tenant cloud). -**Products:** PingOne ST, PingAM (within PingOne ST), PingIDM (within PingOne ST), PingDS (within PingOne ST) +**Products:** PingOne Advanced Identity Cloud (AIC), PingAM (within AIC), PingIDM (within AIC), PingDS (within AIC) -**Routing tag:** `pingone-st` +**Routing tag:** `pingone-st` (the tag is a stable internal identifier; the platform it denotes is AIC) ## Ping Software Suite (On-Premises) @@ -29,7 +29,7 @@ On-premises and self-managed deployments. Different deployment model, topology, ## Shared / Cross-Platform -Universal Services and patterns that span multiple platform families. Used when capability is invoked from both PingOne MT and PingOne ST contexts. +Universal Services and patterns that span multiple platform families. Used when capability is invoked from both PingOne (multi-tenant cloud) and AIC contexts. **Services:** PingOne Protect, PingOne Verify, PingOne Credentials, PingOne SSO, PingOne IGA, PingOne Neo, PingOne Authorize @@ -42,6 +42,6 @@ Universal Services and patterns that span multiple platform families. Used when Apply platform family routing before any capability or product routing: 1. Is the user working in PingOne admin console or PingOne APIs? → `pingone-mt` -2. Is the user working in PingOne ST tenant admin, identity cloud, or AM/IDM/DS? → `pingone-st` +2. Is the user working in AIC tenant admin, identity cloud, or AM/IDM/DS? → `pingone-st` 3. Is the user deploying, configuring, or operating on-prem software? → `ping-software` -4. Is the service invoked across both PingOne MT and PingOne ST? → `cross-platform` +4. Is the service invoked across both PingOne (multi-tenant cloud) and AIC? → `cross-platform` diff --git a/shared/taxonomies/service-map.md b/shared/taxonomies/service-map.md index 6b97b50..3e7ba08 100644 --- a/shared/taxonomies/service-map.md +++ b/shared/taxonomies/service-map.md @@ -4,12 +4,12 @@ Maps Ping Universal Services and strategic shared services to platform context a ## Universal Services -These services are consumed across PingOne MT and PingOne ST. They are not configuration destinations; they are capabilities invoked from within a platform. +These services are consumed across PingOne (multi-tenant cloud) and AIC. They are not configuration destinations; they are capabilities invoked from within a platform. | Service | Platform Context | Primary Skill | Notes | |---|---|---|---| -| PingOne Protect | PingOne MT, PingOne ST via connector | ping-universal-services | Risk signals, adaptive auth, bot detection | -| PingOne Verify | PingOne MT, PingOne ST via connector | ping-universal-services | Identity verification, document check, liveness | +| PingOne Protect | PingOne (MT), AIC via connector | ping-universal-services | Risk signals, adaptive auth, bot detection | +| PingOne Verify | PingOne (MT), AIC via connector | ping-universal-services | Identity verification, document check, liveness | | PingOne Credentials | PingOne MT | ping-universal-services | Verifiable credentials, digital wallet | | PingOne SSO | PingOne MT | ping-universal-services | Workforce SSO, app federation, SAML/OIDC | | PingOne IGA | PingOne MT | ping-universal-services | Identity governance, access requests, certifications | @@ -23,7 +23,7 @@ These services are tightly coupled to orchestration. Route to ping-orchestration | Service | Primary Skill | Notes | |---|---|---| | PingOne DaVinci | ping-orchestration | Flow builder, connector library, CIAM orchestration | -| PingOne ST Journeys / Trees | ping-orchestration | PingAM authentication trees, journey nodes | +| AIC Journeys / Trees | ping-orchestration | PingAM authentication trees, journey nodes | ## On-Premises Strategic Services diff --git a/shared/templates/AUTHORING-RULES.md b/shared/templates/AUTHORING-RULES.md index 3ecd4e7..bc0b725 100644 --- a/shared/templates/AUTHORING-RULES.md +++ b/shared/templates/AUTHORING-RULES.md @@ -116,14 +116,41 @@ slug: "" # canonical docs URL for this topic | Value | Platform | |---|---| | `pingone-mt` | PingOne (multi-tenant cloud) | -| `pingone-st` | PingOne ST (single-tenant) | +| `pingone-st` | PingOne Advanced Identity Cloud (AIC) | | `ping-software` | Ping Software Suite (on-premises) | | `cross-platform` | Spans multiple platform families | +> **Naming note:** The `pingone-st` value is a stable internal routing tag and directory name — it denotes **PingOne Advanced Identity Cloud (AIC)**. Always call the platform "PingOne Advanced Identity Cloud (AIC)" or "AIC" in prose. Never surface "PingOne ST" or "single-tenant" as the product name in author-facing or agent-facing text. + Use `cross-platform` only when the content genuinely applies without modification to two or more platform families. If a doc has platform-specific sections, pick the primary family and note variants in the body. --- +## 1a. Editorial principles — accuracy, tone, and durability + +Skills and MCP tool descriptions ride alongside the product and the official docs. They must not get ahead of shipped behaviour, and they must not editorialise about Ping's own products or documentation. + +**Follow the product — do not jump ahead of it.** Only document behaviour that is shipped and documented. If a capability is not yet supported by the product or has no stable querying logic, do not invent it in a skill or MCP description. When in doubt, defer to the official docs. + +**No statements that go stale.** Do not bake release timing, channel state, or version-promotion plans into reference prose. These rot between updates and mislead agents. + +- ❌ "Available on the Rapid channel as of 2026-06-03; Regular channel promotion planned." +- ❌ "Not yet GA; this skill will cover it when available." +- ❌ "These will be introduced progressively from Q3 2026." +- ✅ State the capability, then link to the live release notes / docs for current availability: "Check the [AIC release notes](…) for current channel availability." + +If availability genuinely gates usage, express it as a durable constraint plus a pointer to the authoritative source — not a dated promise. + +**No negative framing about Ping docs or products.** Reference files describe capability and behaviour neutrally. Do not characterise the official docs or product as deficient, and do not position skill content as compensating for them. + +- ❌ "Not documented clearly in official docs and a common source of bugs." +- ❌ "Tribal knowledge the docs don't cover." +- ✅ "Behavioural invariants validated against live sessions; complements the per-node reference docs." + +The test: state what the content **is** and what it **enables**, not what the docs or product **lack**. + +--- + ## 2. Curated anchors — how to write them ### Curated anchors (`references/curated/`) From b4d1274376e1fe8239a88e26ec540ebab04103a1 Mon Sep 17 00:00:00 2001 From: "george.bafaloukas" Date: Mon, 22 Jun 2026 17:06:23 +0100 Subject: [PATCH 02/15] feat(ping-identity): Ping CLI, config promotion, and API doc link updates MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Addresses gaps identified via Glean research sweep across all 6 skills. New curated anchors: - ping-foundation/cross-platform/ping-cli-basics.md — Ping CLI 1.0 unified configuration automation: install, profiles, CRUD, platform export for Terraform/CaC, CI/CD patterns, gotchas; boundaries vs MCP servers and Terraform providers - ping-foundation/cross-platform/config-promotion.md — cross-platform configuration promotion covering PingOne native promotion, AIC self-service promotions, and Ping CLI + Terraform GitOps; model selection table; hard limits and constraints (EA-framing follows editorial rule 1a — behavioural constraints only, no dated GA claims) - ping-orchestration/cross-platform/journey-and-flow-promotion.md — journey/ flow-specific promotion depth: ESV integrity checks, orphaned scripts, DaVinci flow versioning and promotion variables, environment lock impact, per-node considerations, rollback behaviour Skill routing: - ping-foundation/SKILL.md: new Cross-platform tooling section with Ping CLI and config-promotion routing rows; pingcli trigger added to description and When to use list - ping-orchestration/SKILL.md: config-promotion row added to Cross-platform orchestration patterns Eval coverage: - ping-foundation.yaml: T-80–T-82 (Ping CLI), T-83–T-85 (config promotion), N-07–N-08 - ping-orchestration.yaml: T-59–T-61 (journey/flow promotion) API docs link update (#7): - 5 legacy apidocs.pingidentity.com links replaced with verified developer.pingidentity.com/pingone-api/ canonical URLs across service-invocation-patterns.md, core-admin-patterns.md, and tenant-and-environment-setup.md - grep confirms zero remaining apidocs.pingidentity.com references All validators pass: 6 skills, 69 curated anchors, all prompt YAML valid. Layer 1 + Layer 2 evals: 100% pass rate across all 5 skills. Co-Authored-By: Claude Sonnet 4.6 (1M context) --- .gitignore | 1 + evals/prompts/ping-foundation.yaml | 56 +++++ evals/prompts/ping-orchestration.yaml | 23 ++ .../skills/ping-foundation/SKILL.md | 10 +- .../cross-platform/config-promotion.md | 191 +++++++++++++++ .../cross-platform/core-admin-patterns.md | 2 +- .../curated/cross-platform/ping-cli-basics.md | 221 ++++++++++++++++++ .../tenant-and-environment-setup.md | 2 +- .../skills/ping-orchestration/SKILL.md | 1 + .../journey-and-flow-promotion.md | 197 ++++++++++++++++ .../curated/service-invocation-patterns.md | 6 +- 11 files changed, 704 insertions(+), 6 deletions(-) create mode 100644 plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md create mode 100644 plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md create mode 100644 plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md diff --git a/.gitignore b/.gitignore index df7ebe2..fcfe641 100644 --- a/.gitignore +++ b/.gitignore @@ -22,3 +22,4 @@ docs/ *.local.json .env.local .env +.plans/ diff --git a/evals/prompts/ping-foundation.yaml b/evals/prompts/ping-foundation.yaml index a4881e9..e5dd814 100644 --- a/evals/prompts/ping-foundation.yaml +++ b/evals/prompts/ping-foundation.yaml @@ -175,6 +175,52 @@ trigger_prompts: expected_tier: curated notes: "Bare 'AIC' → pingone-st." + # ----- Config promotion (added 2026-06-22) ----- + + - id: T-83 + prompt: "How do I promote my PingOne configuration from sandbox to production — what's supported and what's not?" + expected_anchors: + - plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md + expected_tier: curated + notes: "PingOne native promotion scope + constraints." + + - id: T-84 + prompt: "We use AIC with dev, staging, and prod tenants. What's the right way to promote config between them?" + expected_anchors: + - plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md + expected_tier: curated + notes: "AIC self-service promotion topology → config-promotion anchor." + + - id: T-85 + prompt: "We want a Terraform-based config-as-code pipeline for promoting PingOne and PingFederate config across environments. Where do we start?" + expected_anchors: + - plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md + expected_tier: curated + notes: "Terraform GitOps promotion pattern → config-promotion anchor." + + # ----- Ping CLI automation (added 2026-06-22) ----- + + - id: T-80 + prompt: "How do I use pingcli to export my PingOne and PingFederate configuration as Terraform HCL?" + expected_anchors: + - plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md + expected_tier: curated + notes: "Explicit pingcli + Terraform export → cross-platform CLI anchor." + + - id: T-81 + prompt: "Set up multiple Ping CLI configuration profiles so I can promote DaVinci changes from dev to prod in CI/CD." + expected_anchors: + - plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md + expected_tier: curated + notes: "Multi-env profiles + CI/CD promotion → ping-cli-basics." + + - id: T-82 + prompt: "How do I authenticate pingcli to PingFederate and run admin API calls from a script?" + expected_anchors: + - plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md + expected_tier: curated + notes: "pingcli PingFederate auth + raw API → ping-cli-basics." + non_trigger_prompts: - id: N-01 prompt: "Build a DaVinci flow for customer login with risk-based step-up MFA." @@ -203,6 +249,16 @@ non_trigger_prompts: expected_skill: ping-quickstart notes: "Bare command with no platform named — must route to ping-quickstart for clarification first." + - id: N-07 + prompt: "Design a DaVinci flow that does passwordless login with passkeys." + expected_skill: ping-orchestration + notes: "DaVinci flow design belongs in ping-orchestration, not ping-foundation, even though pingcli can manage DaVinci resources." + + - id: N-08 + prompt: "How do I rotate the client secret on my PingOne Worker app?" + expected_skill: ping-foundation + notes: "Secret rotation is a platform admin task → core-admin-patterns.md, not config-promotion.md." + ambiguous_prompts: - id: A-01 prompt: "Configure MFA." diff --git a/evals/prompts/ping-orchestration.yaml b/evals/prompts/ping-orchestration.yaml index 5c65351..493fcf1 100644 --- a/evals/prompts/ping-orchestration.yaml +++ b/evals/prompts/ping-orchestration.yaml @@ -132,6 +132,29 @@ trigger_prompts: expected_tier: curated notes: "feedback: push MFA transaction approval trigger" + # ----- Config promotion (added 2026-06-22) ----- + + - id: T-59 + prompt: "I built a registration journey in our AIC dev tenant — how do I promote it to staging without breaking ESVs?" + expected_anchors: + - plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md + expected_tier: curated + notes: "AIC journey promotion + ESV gotcha → journey-and-flow-promotion anchor." + + - id: T-60 + prompt: "What's the best way to move a DaVinci flow from one PingOne environment to another and keep connector credentials per environment?" + expected_anchors: + - plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md + expected_tier: curated + notes: "DaVinci flow promotion variables → journey-and-flow-promotion anchor." + + - id: T-61 + prompt: "We have scripted decision nodes referencing environment-specific endpoints. How do we promote the journey across environments?" + expected_anchors: + - plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md + expected_tier: curated + notes: "Scripted Decision node + ESV placeholder during AIC promotion." + non_trigger_prompts: - id: N-01 prompt: "How do I install PingFederate on RHEL and configure initial admin settings?" diff --git a/plugins/ping-identity/skills/ping-foundation/SKILL.md b/plugins/ping-identity/skills/ping-foundation/SKILL.md index f7b73d6..d1e380f 100644 --- a/plugins/ping-identity/skills/ping-foundation/SKILL.md +++ b/plugins/ping-identity/skills/ping-foundation/SKILL.md @@ -1,6 +1,6 @@ --- name: ping-foundation -description: "Use when setting up, configuring, or administering any Ping Identity platform — PingOne, PingOne Advanced Identity Cloud (AIC), or Ping Advanced Identity Software (PingAM, PingFederate, PingAccess, PingDirectory, PingID). Covers tenant/environment creation, app registration (including Worker apps and service accounts for M2M API access), SSO, directories, policies, and branding. Requires a named or clearly implied platform." +description: "Use when setting up, configuring, or administering any Ping Identity platform — PingOne, PingOne Advanced Identity Cloud (AIC), or Ping Advanced Identity Software (PingAM, PingFederate, PingAccess, PingDirectory, PingID). Covers tenant/environment creation, app registration (including Worker apps and service accounts for M2M API access), SSO, directories, policies, branding, and CLI-driven configuration automation (pingcli, Terraform/CaC export, multi-env promotion). Requires a named or clearly implied platform." compatibility: Designed for Ping Identity platform tasks. MCP tools for PingOne and PingOne Advanced Identity Cloud (AIC) are used when available; console instructions provided as fallback. metadata: publisher: Ping Identity @@ -28,6 +28,7 @@ Trigger on ANY question about setting up, configuring, administering, or plannin - Configure authentication policies, sign-on policies, or branding - Administer PingFederate, PingAccess, PingDirectory, or PingID - Deploy or upgrade on-premises Ping software +- Automate configuration with Ping CLI (`pingcli`), export Terraform/CaC packages, or manage multi-environment promotion pipelines - Advisory: "How should I structure my tenant?", "What client type should I use?" ## When NOT to use this skill @@ -95,6 +96,13 @@ Trigger on ANY question about setting up, configuring, administering, or plannin | PingAccess web app and API protection | `references/curated/ping-software/pingaccess-basics.md` | | Cross-platform admin patterns (LDAP, OIDC, APIs) | `references/curated/cross-platform/core-admin-patterns.md` | +## Cross-platform tooling + +| Task | Anchor | +|---|---| +| CLI-driven config, multi-env profiles, Terraform/CaC export across PingOne, DaVinci, PingFederate | `references/curated/cross-platform/ping-cli-basics.md` | +| Promote configuration between environments (PingOne native promotion, AIC self-service promotions, Ping CLI + Terraform config-as-code) | `references/curated/cross-platform/config-promotion.md` | + ## MCP execution See `references/runtime/mcp-preflight.md` for MCP config and Cursor preflight steps. diff --git a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md new file mode 100644 index 0000000..6118f70 --- /dev/null +++ b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md @@ -0,0 +1,191 @@ +--- +title: "Configuration Promotion Across Environments" +product_family: cross-platform +products: ["pingone", "pingone-st", "pingfederate"] +capabilities: ["foundation"] +services: [] +audience: ["admin", "architect", "operator"] +use_cases: ["workforce", "customer", "cross-platform"] +doc_type: guide +status: current +canonical: true +last_updated: "2026-06-22" +slug: "https://developer.pingidentity.com/config-automation-promotion/configuration_promotion_landing_page.html" +--- + +# Configuration Promotion Across Environments + +How to move Ping Identity configuration between development, staging, and production environments across PingOne, AIC, and Ping Software. + +## Scope + +**Covers:** Choosing a promotion model; environment topology rules; what promotes vs what does not; promotion variables and ESV placeholders; hard limits and constraints; rollback; GitOps with Ping CLI + Terraform; model selection. + +**Does NOT cover:** Journey- and flow-specific promotion concerns — scripted decision node ESV gotchas, DaVinci flow versioning, environment lock impact on running journeys — see `ping-orchestration` → `references/curated/cross-platform/journey-and-flow-promotion.md`. Secret rotation — see `references/curated/cross-platform/core-admin-patterns.md`. Bulk user import and data migration (users, sessions, audit logs are never promoted — only static config moves). Ping CLI install and CRUD — see `references/curated/cross-platform/ping-cli-basics.md`. + +--- + +## Three promotion models + +| Model | Applies to | What moves | What does not move | Sequential constraint | +|---|---|---|---|---| +| **PingOne native promotion** | PingOne (multi-tenant cloud) | Applications, DaVinci flows and policies, sign-on policies, and most PingOne resources | Authorize, Credentials, Privilege, runtime user data, sessions, audit logs | Source/target same org; check live docs for current resource scope | +| **AIC self-service promotions** | PingOne Advanced Identity Cloud | Journeys, scripts, themes, AM/IDM static config, ESV references | Live users, sessions, user-created applications, runtime data | Sequential pairs only: dev→staging, staging→production. Non-sequential promotion not supported. | +| **Ping CLI + Terraform (config-as-code)** | PingOne, PingFederate, DaVinci, and supported universal services | Any resource exportable via `pingcli platform export`; Terraform-managed config | Per-resource, determined by provider support | None — Terraform manages state independently per target environment | + +--- + +## Environment topology + +### PingOne + +- Source and target must be in the **same PingOne organization**. +- The **Promotion Admin** role (or equivalent) is required in **both** the source and target environment. +- Both environments should expose the **same connected services** — promoting an application that references a service not enabled in the target will fail. +- Check the linked Ping documentation for resource types currently supported by the promotion API. + +### AIC + +- Promotion chain: **dev → staging → production**. Non-sequential (dev → production) is not supported. +- **Sandbox environments are excluded** from all promotion chains. Sandbox is a separate, isolated tier. +- If **UAT environments** are present, they are inserted into the chain: dev → UAT → staging → production. +- Rollback is available via API; it is not exposed in the admin console. + +### Ping Software (PingFederate, PingAccess, PingDirectory) + +- Configuration is managed via **server profiles** (Git-backed config-as-code). Promotion = merging and applying a server-profile branch. +- Use `pingcli platform export` to extract current running config as Terraform HCL as a starting point. + +--- + +## What promotes vs what does not + +| Category | PingOne native | AIC self-service | Terraform/Ping CLI | +|---|---|---|---| +| Applications and OAuth clients | ✓ | ✓ (static; user-created apps excluded) | ✓ | +| Authentication flows / journeys / trees | ✓ (DaVinci flows) | ✓ (AIC journeys and AM config) | ✓ | +| Policies (sign-on, flow) | ✓ | ✓ | ✓ | +| Themes and branding | ✓ | ✓ | ✓ | +| Scripts | n/a | ✓ | ✓ | +| ESV / environment variables | Promotion variables only | ESV references move; secrets must be pre-configured in target | Via Terraform provider variables | +| Users, sessions, audit logs | ✗ never | ✗ never | ✗ never | +| Runtime user data (devices, MFA enrollments) | ✗ never | ✗ never | ✗ never | +| PingOne Authorize, Credentials, Privilege | ✗ excluded | n/a | ✓ (where provider support exists) | + +--- + +## Promotion variables, ESVs, and placeholders + +Environment-specific values (connection endpoints, client IDs, URIs) must be externalised before promotion so the config is portable. + +| Platform | Mechanism | Key constraint | +|---|---|---| +| PingOne native | **Promotion variables** — named substitution tokens in the exported config | Defined in the source; must be assigned values in the target before applying | +| AIC | **Environment secrets and variables (ESVs)** | ESVs referenced in static config must exist in the upper environment. AIC's integrity check blocks promotion if any ESV is missing or if an encrypted secret is embedded directly in config rather than referenced via an ESV. | +| Terraform | **Terraform input variables / `.tfvars` files per environment** | Standard Terraform pattern; per-environment variable files hold the target-specific values | + +--- + +## Hard limits and constraints + +| Platform | Constraint | Details | +|---|---|---| +| PingOne native | 100 resources per promotion (auto-included dependencies excluded from count) | Larger environments require multiple staged promotions | +| PingOne native | Environment lock not required | Source environment remains writable during promotion | +| PingOne native | Rollback restores the most recent promotion's state in the target | Available via admin console and API | +| AIC | **Environment lock required** on source and target during promotion | Blocks ESV API and most admin APIs in the development environment; **authentication flows for end users are unaffected** | +| AIC | Promotions take 10–45 minutes | Service restart in the upper environment is part of the process | +| AIC | Rollback available via API only | Admin console does not expose rollback | +| Ping CLI export | Terraform HCL export scope varies by service | Not all services produce HCL; check the [product compatibility matrix](https://developer.pingidentity.com/pingcli/1.0/product-compatibility.html) | + +For current availability of specific resource types in native PingOne promotion, check the linked Ping documentation — this list changes as the feature evolves. + +--- + +## Rollback + +| Platform | Rollback model | How to trigger | +|---|---|---| +| PingOne native | Restores the target environment to its state before the most recent promotion | Admin console → Promote, or Configuration Management API | +| AIC | Restores the upper environment's prior static config set | API only (`POST /promotions/{id}/rollback`) | +| Terraform | `terraform destroy` + revert to prior state file or prior `apply` | Standard Terraform rollback — revert the commit and re-apply | + +--- + +## GitOps pattern with Ping CLI + Terraform + +For multi-product or multi-environment pipelines beyond a single org: + +1. `pingcli platform export --format HCL` — extract current config from a reference environment +2. Store HCL in version control alongside `*.tfvars` per target environment +3. Raise a PR; review diffs as configuration changes +4. Run `terraform plan` against the target environment (dry run) +5. Apply on merge: `terraform apply` +6. Verify post-apply via smoke tests or `pingcli pingone ... list` + +The `pingcli-plugin-terraformer` plugin adds opinionated post-processing to produce cleaner, version-control-ready HCL. For details see `references/curated/cross-platform/ping-cli-basics.md`. + +--- + +## Choosing a promotion model + +| Scenario | Recommended model | +|---|---| +| Single PingOne org, DaVinci-heavy config, in-console workflow preferred | PingOne native promotion | +| AIC tenant with dev/staging/prod chain, sequential promotion | AIC self-service promotions | +| Multi-product (PingOne + PingFederate), multi-org, or full CaC audit trail required | Ping CLI + Terraform | +| Mixed: PingOne apps + AIC journeys | Both: native/AIC for fast iteration; Terraform for baseline config and cross-product consistency | +| PingFederate federation config between servers | Server profiles (Git) + Terraform provider | + +--- + +## Prerequisites + +- **PingOne native:** Promotion Admin role in both source and target environments; both in the same org. +- **AIC:** AIC tenant admin access in both environments; ESVs pre-configured in the upper environment. +- **Ping CLI / Terraform:** PingOne Worker app with admin roles; PingFederate admin API OAuth client; Terraform CLI; Ping Identity Terraform providers installed. + +--- + +## Common variants + +| Variant | Notes | +|---|---| +| Single-org PingOne, console workflow | Use native promotion for quick dev→test iteration; graduate to Terraform for long-term state management | +| AIC standard chain (dev/staging/prod) | Self-service promotions; ESVs must exist in target before promoting | +| AIC with UAT | dev → UAT → staging → production; non-sequential skips not supported | +| Cross-org or multi-tenant | Only Terraform covers this; native promotion is same-org only | +| Community tooling (fr-config-manager, frodo) | Widely used by AIC customers for bespoke config management; not an official Ping product — see their respective GitHub repositories | + +--- + +## Common gotchas + +| Symptom | Cause | Fix | +|---|---|---| +| AIC promotion blocked by integrity check | Missing ESV or encrypted secret embedded in config | Create the missing ESV in the upper environment; replace inline secrets with ESV references | +| PingOne promotion fails on service dependency | Target env missing a service the source config references | Enable the service in the target environment before promoting | +| AIC promotion locks admin APIs longer than expected | Large config sets take 10–45 minutes; lock is held throughout | Schedule promotions during low-traffic windows; monitor the promotion status API | +| Rollback restores unexpected state | Multiple promotions in quick succession | Wait for each promotion to complete before running the next; check the promotion history before rollback | +| `pingcli platform export` produces empty package for a service | Service not yet in HCL export scope | Check the product compatibility matrix; use `pingcli pingone api` as a fallback for raw export | + +--- + +## Related references + +- `references/curated/cross-platform/ping-cli-basics.md` — Ping CLI install, profiles, CRUD, and Terraform export commands +- `references/curated/cross-platform/core-admin-patterns.md` — secret rotation, API patterns +- `references/curated/pingone-mt/tenant-and-environment-setup.md` — environment setup prerequisites +- `ping-orchestration` → `references/curated/cross-platform/journey-and-flow-promotion.md` — journey, script, and DaVinci flow promotion specifics + +--- + +## Source + +- [Configuration promotion overview](https://developer.pingidentity.com/config-automation-promotion/configuration_promotion_landing_page.html) +- [PingOne configuration management](https://docs.pingidentity.com/pingone/early-access-features/ea-p1_promote.html) +- [AIC self-service promotions](https://docs.pingidentity.com/pingoneaic/tenants/self-service-promotions.html) +- [AIC promotion FAQ](https://docs.pingidentity.com/pingoneaic/tenants/self-service-promotions-faqs.html) +- [AIC configuration placeholders (ESVs)](https://docs.pingidentity.com/pingoneaic/tenants/configuration-placeholders.html) +- [Ping CLI platform export](https://developer.pingidentity.com/pingcli/general/exporting-platform-configuration.html) +- [Ping Terraform provider](https://terraform.pingidentity.com) diff --git a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/core-admin-patterns.md b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/core-admin-patterns.md index c429bb4..bebdee6 100644 --- a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/core-admin-patterns.md +++ b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/core-admin-patterns.md @@ -151,7 +151,7 @@ Admin access to the relevant platform: PingOne organization admin, AIC superadmi ## Source -[PingOne API Reference](https://apidocs.pingidentity.com/pingone/platform/v1/api/) +[PingOne API Reference](https://developer.pingidentity.com/pingone-api/platform/introduction.html) [PingFederate Admin API](https://docs.pingidentity.com/pingfederate/latest/admin-api-reference/pf-admin-api-reference.html) [PingAccess Admin API](https://docs.pingidentity.com/pingaccess/latest/pa-admin-api/pa-admin-api.html) [PingDirectory Admin Guide](https://docs.pingidentity.com/pingdirectory/latest/pd-directory-server-administration-guide/pd-ds-admin-overview.html) diff --git a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md new file mode 100644 index 0000000..347c70f --- /dev/null +++ b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md @@ -0,0 +1,221 @@ +--- +title: "Ping CLI — Configuration Automation Basics" +product_family: cross-platform +products: ["pingone", "pingfederate", "davinci", "pingone-authorize", "pingone-mfa", "pingone-protect", "pingone-verify", "pingone-credentials"] +capabilities: ["foundation"] +services: ["protect", "verify", "mfa", "credentials", "authorize"] +audience: ["admin", "developer", "operator"] +use_cases: ["workforce", "customer", "cross-platform"] +doc_type: guide +status: current +canonical: true +last_updated: "2026-06-22" +slug: "https://developer.pingidentity.com/pingcli/" +--- + +# Ping CLI — Configuration Automation Basics + +Scriptable, deterministic configuration management across PingOne, PingFederate, DaVinci, and the Ping universal services using the `pingcli` command-line tool. + +## Scope + +**Covers:** Install and first-run, configuration profile model, connecting Ping services, CRUD via per-product subcommands, `pingcli platform export` for Configuration-as-Code / Terraform HCL, `pingcli request` for unmodeled endpoints, CI/CD patterns, and the migration from the legacy `pingctl` tool. + +**Does NOT cover:** Interactive agent-driven config — use the PingOne MCP Server or DaVinci MCP Server for that. Long-term Terraform state management — see the PingOne and PingFederate Terraform providers at `developer.pingidentity.com/terraform/`. DaVinci flow design — see `ping-orchestration`. PingFederate console or federation configuration — see `references/curated/ping-software/pingfederate-basics.md`. Per-service policy semantics (Protect risk, Verify KYC) — see `ping-universal-services`. + +--- + +## What Ping CLI is + +Ping CLI (`pingcli`) is the unified open-source CLI for managing configuration across PingOne, PingFederate, DaVinci, and the Ping universal services. It provides: + +- A consistent CRUD interface for admin operations without raw `curl` calls +- Multi-product Configuration-as-Code export (`pingcli platform export`) for Terraform integration +- Profile-based authentication so the same scripts run against dev, staging, and production +- Raw admin API access with managed auth for endpoints that don't yet have first-class commands + +For the current list of supported products and per-service CRUD availability, see the [product compatibility matrix](https://developer.pingidentity.com/pingcli/1.0/product-compatibility.html). + +> **Legacy note:** `pingctl` (earlier tool) is replaced by `pingcli`. Migrate by re-configuring profiles under the new tool. + +--- + +## Install + +| Platform | Method | Command | +|---|---|---| +| macOS | Homebrew (recommended) | `brew install pingidentity/tap/pingcli` | +| Linux | Package manager (apt/yum) or binary | See [Linux install guide](https://developer.pingidentity.com/pingcli/1.0/install/linux.html) | +| Windows | Binary download | See [Windows install guide](https://developer.pingidentity.com/pingcli/1.0/install/windows.html) | +| CI/CD | Docker image | `docker run pingidentity/pingcli:latest` | + +Verify: `pingcli version` + +--- + +## Configuration profiles + +Profiles are named groups of settings stored in `$HOME/.pingcli/config.yaml`. Use one profile per target environment (dev, staging, prod). + +| Operation | Command (1.0) | +|---|---| +| Create a profile | `pingcli config profiles create --name dev` | +| Switch active profile | `pingcli config profiles use dev` | +| List profiles | `pingcli config profiles list` | +| View active profile | `pingcli config view-profile` | +| Delete a profile | `pingcli config profiles delete dev` | + +> **Version note:** Ping CLI 0.8 used different subcommand names (`add-profile`, `set-active-profile`). If commands fail, verify your installed version with `pingcli version` and cross-check the [0.8 command reference](https://developer.pingidentity.com/pingcli/0.8/command_reference/pingcli_config.html) if needed. + +--- + +## Connecting Ping services + +Before using product subcommands, configure the service credentials in the active profile: + +| Service | Prerequisites | Key config fields | +|---|---|---| +| PingOne | Worker application (client credentials) | `clientId`, `clientSecret`, `environmentId`, `region` | +| PingFederate | Admin API OAuth client | `baseURL`, `clientId`, `clientSecret` | +| DaVinci | Same Worker app as PingOne | Shares PingOne credentials | +| Universal services (MFA, Protect, Verify, Authorize, Credentials) | Same Worker app as PingOne | Share PingOne credentials via PingOne connector | + +Use `pingcli init` for a guided first-run setup wizard. Configure manually with `pingcli config set`. + +**Regions:** PingOne regions affect the base URL — ensure the profile uses the correct region string (`com`, `eu`, `asia`, `sg`, `ca`). A wrong region causes 404 on environment lookups. + +--- + +## CRUD examples + +Per-product subcommands follow consistent `list`, `get`, `create`, `update`/`replace`, `delete` patterns: + +```bash +# PingOne — list environments +pingcli pingone environments list + +# PingOne — create an application from a JSON config file +pingcli pingone applications create -f app.json + +# DaVinci — list flows in an application +pingcli davinci flows list --application-id + +# PingOne MFA — replace a device policy +pingcli mfa device-policies replace -f policy.json + +# PingFederate — raw admin API call (GET /oauth/clients) +pingcli pingfederate api GET /oauth/clients +``` + +Universal-service connectors are accessible both at top level (`pingcli davinci ...`, `pingcli mfa ...`) and under the PingOne connector umbrella (`pingcli pingone davinci ...`). Both paths use the same PingOne Worker app credentials. + +--- + +## `pingcli platform export` + +Exports multi-product configuration as Configuration-as-Code packages, optionally as Terraform HCL `import {}` blocks. + +```bash +# Export all connected products +pingcli platform export + +# Export only PingOne services +pingcli platform export --service-group pingone + +# Export as Terraform HCL (requires pingcli-plugin-terraformer) +pingcli platform export --format HCL +``` + +**Export availability per product:** Not all products produce HCL today. `pingone-platform`, `pingone-sso`, `pingone-mfa`, `pingone-protect`, `pingone-authorize`, and `pingfederate` are supported; `pingone-davinci`, `pingone-credentials`, and `pingone-verify` are listed but export support is partial. Always check the [product compatibility page](https://developer.pingidentity.com/pingcli/1.0/product-compatibility.html) for the current status. + +**Terraformer plugin:** `pingcli-plugin-terraformer` (installed via `pingcli plugin add`) produces opinionated, ready-to-store HCL with post-processing suited for GitOps promotion pipelines. + +--- + +## Custom API requests + +For endpoints without a first-class subcommand, use the raw request interfaces. The CLI injects auth, base URL, and retry handling automatically. + +```bash +# Generic request (all products) +pingcli request GET /pingone/environments//applications + +# Product-specific wrappers (1.0) +pingcli pingone api GET /environments//applications +pingcli pingfederate api GET /oauth/clients +``` + +--- + +## CI/CD patterns + +```bash +# Non-interactive auth (client credentials — no browser prompt) +export PINGCLI_PINGONE_CLIENT_ID=... +export PINGCLI_PINGONE_CLIENT_SECRET=... +export PINGCLI_PINGONE_ENVIRONMENT_ID=... +export PINGCLI_PINGONE_REGION=com + +# JSON output for pipeline parsing +pingcli pingone applications list --output-format json + +# Detailed exit codes for conditional pipeline steps +pingcli -D platform export +# Exit 0 = success; 1 = error; 2 = success with warnings +``` + +**Profile-per-environment promotion pattern:** Create one profile per environment (dev/staging/prod), each binding to a different Worker app. A promotion script switches profiles and runs the export or create commands. + +--- + +## Prerequisites + +- PingOne: Worker application with the required admin roles; `clientId`, `clientSecret`, `environmentId`, and region. +- PingFederate: Admin API OAuth client; admin base URL (HTTPS, port 9999 by default). +- Network access from the CLI host to each product's admin API endpoint. +- For Terraform HCL export: `pingcli-plugin-terraformer` installed via `pingcli plugin add`. + +--- + +## Common variants + +| Variant | Notes | +|---|---| +| Single tenant, one profile | Default setup; one profile, one Worker app | +| Multi-environment promotion | One profile per env; promotion script switches profiles before export/create | +| Docker-only CI | Run `pingidentity/pingcli:latest` as a container step; pass credentials as env vars | +| Terraform GitOps | `pingcli platform export --format HCL` + Terraformer plugin + Terraform plan/apply in PR pipeline | +| Migrating from `pingctl` | Re-configure profiles under `pingcli`; `pingctl` commands are not compatible | + +--- + +## Common gotchas + +| Symptom | Cause | Fix | +|---|---|---| +| 404 on environment lookup | Wrong region in profile | Verify region string matches the PingOne tenant domain (e.g., `eu` for `pingone.eu`) | +| 403 on `applications create` | Worker app missing roles | Verify the Worker app has the required admin roles in the PingOne environment | +| 0.8 profile commands fail on 1.0 | Command names changed between versions | Run `pingcli version`; update scripts to use 1.0 command names (`profiles create`, not `add-profile`) | +| `platform export` returns empty package for a service | Service not yet supported for export | Check the product compatibility matrix; use `pingcli request` as fallback | +| `pingcli init` wizard skips a service | Service credentials not configured | Re-run `pingcli config set` for the missing service manually | + +--- + +## Related references + +- `references/curated/cross-platform/foundation-overview.md` — platform overview and admin model +- `references/curated/cross-platform/core-admin-patterns.md` — cross-product admin patterns +- `references/curated/pingone-mt/app-registration.md` — Worker app setup (prerequisite for PingOne auth) +- `references/curated/ping-software/pingfederate-basics.md` — PingFederate admin API context + +--- + +## Source + +- [Ping CLI overview](https://developer.pingidentity.com/pingcli/) +- [Install guide (1.0)](https://developer.pingidentity.com/pingcli/1.0/pingcli_landing_page.html) +- [Product compatibility matrix](https://developer.pingidentity.com/pingcli/1.0/product-compatibility.html) +- [Command reference (1.0)](https://developer.pingidentity.com/pingcli/1.0/command_reference/pingcli.html) +- [Exporting platform configuration](https://developer.pingidentity.com/pingcli/general/exporting-platform-configuration.html) +- [Configuration promotion overview](https://developer.pingidentity.com/config-automation-promotion/configuration_promotion_landing_page.html) +- [GitHub: pingidentity/pingcli](https://github.com/pingidentity/pingcli) diff --git a/plugins/ping-identity/skills/ping-foundation/references/curated/pingone-mt/tenant-and-environment-setup.md b/plugins/ping-identity/skills/ping-foundation/references/curated/pingone-mt/tenant-and-environment-setup.md index fcc2878..8f22d9c 100644 --- a/plugins/ping-identity/skills/ping-foundation/references/curated/pingone-mt/tenant-and-environment-setup.md +++ b/plugins/ping-identity/skills/ping-foundation/references/curated/pingone-mt/tenant-and-environment-setup.md @@ -205,4 +205,4 @@ Administrator role assignments cross environment boundaries: a user in the Admin [PingOne environments](https://docs.pingidentity.com/pingone/platformconsole/p1_c_environments.html) [PingOne MFA device policies](https://docs.pingidentity.com/pingone/mfa/p1_c_mfa_device_policies.html) [PingOne OIDC application setup](https://docs.pingidentity.com/pingone/platformconsole/p1_c_apps.html) -[PingOne API reference](https://apidocs.pingidentity.com/pingone/platform/v1/api/) +[PingOne API reference](https://developer.pingidentity.com/pingone-api/platform/introduction.html) diff --git a/plugins/ping-identity/skills/ping-orchestration/SKILL.md b/plugins/ping-identity/skills/ping-orchestration/SKILL.md index 03e0d6b..1b10ef3 100644 --- a/plugins/ping-identity/skills/ping-orchestration/SKILL.md +++ b/plugins/ping-identity/skills/ping-orchestration/SKILL.md @@ -97,6 +97,7 @@ Sub-routing by task and journey use case: see `references/curated/pingone-st/rou | Task | Reference | |---|---| | Passkeys / passwordless / FIDO2 design across PingOne, PingOne Advanced Identity Cloud (AIC), Ping Software | `references/curated/cross-platform/passkeys-and-passwordless.md` | +| Promote journeys, scripts, themes, or DaVinci flows between dev/staging/production | `references/curated/cross-platform/journey-and-flow-promotion.md` | --- diff --git a/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md b/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md new file mode 100644 index 0000000..af2cdc0 --- /dev/null +++ b/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md @@ -0,0 +1,197 @@ +--- +title: "Promoting Journeys, Scripts, and DaVinci Flows Between Environments" +product_family: cross-platform +products: ["pingone", "pingone-st"] +capabilities: ["orchestration"] +services: [] +audience: ["developer", "architect"] +use_cases: ["workforce", "customer"] +doc_type: guide +status: current +canonical: true +last_updated: "2026-06-22" +slug: "https://docs.pingidentity.com/pingoneaic/tenants/self-service-promotions.html" +--- + +# Promoting Journeys, Scripts, and DaVinci Flows Between Environments + +Journey-, script-, and DaVinci-flow-specific concerns when promoting between AIC and PingOne environments. + +## Scope + +**Covers:** What journey and flow config moves; AIC ESV and script gotchas; DaVinci flow versioning and promotion variables; environment lock impact on running journeys; per-node promotion considerations; rollback. + +**Does NOT cover:** General promotion model choice, tool selection, environment topology, and Terraform/CaC pipeline — see `ping-foundation` → `references/curated/cross-platform/config-promotion.md`. That anchor is the entry point; load this one only when the task involves journey- or flow-specific concerns. + +--- + +## What journey and flow config moves + +### AIC self-service promotions + +**Moves (static config):** +- Journeys (authentication trees) and all node configurations +- Scripted Decision node scripts +- Themes and hosted pages customisations +- AM service config (OAuth2 Provider, OIDC, Session, CORS, Social IdPs, WebAuthn, etc.) +- IDM managed-object schema and scripts +- ESV references (the reference moves; the ESV value itself must exist in the target) + +**Does not move (dynamic / runtime data):** +- Live user sessions +- User-created or self-registered applications +- MFA device enrollments +- User profile data and custom attributes + +### PingOne DaVinci flows + +**Moves via native PingOne promotion:** +- Flow definitions (all versions) +- Flow policies +- Connector configurations (connection IDs and settings) + +**Key gotcha:** Connector credentials (client IDs, secrets, API keys) are environment-specific. Use **promotion variables** to externalise them so the promoted flow references the target environment's credential values, not the source's. + +--- + +## AIC: ESV and script gotchas + +### ESV integrity check + +AIC runs an integrity check before starting any promotion. Promotion is **blocked** if: +- A static config item references an ESV that does not exist in the target environment +- An encrypted secret is embedded directly in config rather than referenced via an ESV + +**Fix before promoting:** Create the missing ESVs in the upper environment. Replace any inline secrets with ESV references using the AIC admin console (Environments → Environment Secrets & Variables). + +### Orphaned or missing scripts + +If a Scripted Decision node references a script that is not included in the static config export (e.g. it was created outside the normal journey-editing workflow), the promotion may succeed but the journey fails at runtime when that node executes. + +**Fix:** Verify all scripts referenced by Scripted Decision nodes appear in the pre-promotion config snapshot. AIC's self-service promotion UI shows the full list of static resources included. + +### PII / sensitive data in script logs + +Review Scripted Decision node scripts for `logger.error(...)` or `logger.message(...)` calls that log user attributes before promoting to production. Production log retention is longer and may be subject to compliance requirements. + +--- + +## DaVinci flow promotion: versioning and variables + +### Flow versioning + +Each DaVinci flow has a **saved version** (draft) and a **published version** (live). Native PingOne promotion moves the published version. Ensure the correct version is published before triggering a promotion. + +### Flow-policy dependency + +Flow policies reference a specific flow and version. When promoting a flow, also promote its associated flow policy — an unpromoted policy pointing at a flow that no longer matches will fail at authentication time. + +### Promotion variables for connector credentials + +In DaVinci, connector credentials (client IDs, client secrets, webhook URLs, API keys) are environment-specific. Use **DaVinci promotion variables** to bind these to environment-specific values: + +1. In the source flow, replace the literal credential with a promotion variable token. +2. In the target environment, assign the variable to the target-side credential value before applying the promotion. +3. DaVinci flow promotion validates that all referenced variables have assigned values in the target. + +--- + +## Environment lock impact during AIC promotion + +AIC requires an **environment lock** on both source and target during a promotion. + +| During lock | Effect | +|---|---| +| End-user authentication flows | **Unaffected** — runtime auth continues | +| AIC admin console | Read-only; most writes blocked in the source (dev) environment | +| ESV API | Blocked in the development environment during lock | +| Journey editing (AIC MCP Server, admin console) | Blocked in source during lock | +| Promotion duration | 10–45 minutes depending on config size | + +**Implication for iterative development:** If you are actively editing journeys, schedule promotions during off-hours or low-activity windows to avoid blocking your development workflow. + +--- + +## Sequential pair routing + +AIC self-service promotions enforce a sequential chain: + +``` +dev → staging → production +(with UAT, if present: dev → UAT → staging → production) +``` + +Non-sequential promotion (dev → production directly) is not supported. To validate changes quickly in production-like conditions, promote to staging first, verify, then promote from staging to production. + +Sandbox environments sit outside all promotion chains — you cannot promote to or from a sandbox. + +--- + +## Per-node promotion considerations + +| Node type | Promotion concern | +|---|---| +| Scripted Decision | Script reference must exist in the target; verify script is included in the static config snapshot before promoting | +| SAML/OIDC federation nodes | Entity IDs and redirect URIs are often environment-specific; use ESVs for issuer URLs and endpoints | +| PageNode / themes | Theme customisations move with the journey; ensure themes are included in the static config snapshot | +| Inner journeys | The inner journey must exist (or be co-promoted) in the target before the outer journey is promoted | +| WebAuthn / FIDO2 nodes | `origins` and `relyingPartyDomain` are environment-specific — use ESVs | +| Push MFA nodes | FCM/APNS credentials are environment-specific; store via ESVs | + +--- + +## Rollback for journeys + +If a promoted journey causes issues in the upper environment, AIC self-service rollback restores the prior static config set: + +- **Trigger:** `POST /promotions/{promotionId}/rollback` (API only; admin console does not expose rollback) +- **Behaviour:** The upper environment's journey/script set is restored to its pre-promotion state. In-flight sessions on the promoted journey are not interrupted — they continue against the current version in memory until they time out. +- **After rollback:** Diagnose the issue in the source (dev) environment, fix, and re-promote. + +--- + +## Choosing native promotion vs Terraform for journey/flow work + +| Scenario | Recommendation | +|---|---| +| AIC journey iteration within one tenant chain | AIC self-service promotions — fastest path, admin-console-driven | +| DaVinci flow changes within one PingOne org | PingOne native promotion — in-console, automatic dependency management | +| Multi-org, multi-cloud, or full audit trail required | Terraform (export via `pingcli platform export`, manage with Ping Terraform providers) | +| Mixed AIC + DaVinci in the same pipeline | Both: native/AIC for journeys; Terraform for CaC baseline | + +--- + +## Prerequisites + +- Promotion Admin role (PingOne) or AIC tenant admin access in both environments +- All ESVs referenced in journey/flow config must be pre-created in the target environment +- DaVinci flow promotion variables assigned in the target before promotion +- All dependent inner journeys or scripts co-included in the promotion + +--- + +## Common variants + +| Variant | Notes | +|---|---| +| AIC standard dev/staging/prod chain | Sequential pairs; ESVs pre-configured in each upper env | +| AIC with UAT tier | dev → UAT → staging → production; cannot skip UAT | +| DaVinci flow to a sandbox (test) | Supported in PingOne native promotion; sandbox counts as a valid target env | +| Terraform-managed journey baseline | Export with `pingcli platform export`; manage with Terraform; promote via PR + apply | + +--- + +## Related references + +- `ping-foundation` → `references/curated/cross-platform/config-promotion.md` — model selection, topology, general constraints, and rollback +- `references/curated/pingone-st/journey-design-patterns.md` — journey design best practices before promoting +- `references/curated/pingone-mt/davinci-overview.md` — DaVinci flow concepts and versioning + +--- + +## Source + +- [AIC self-service promotions](https://docs.pingidentity.com/pingoneaic/tenants/self-service-promotions.html) +- [AIC promotion FAQ](https://docs.pingidentity.com/pingoneaic/tenants/self-service-promotions-faqs.html) +- [AIC configuration placeholders (ESVs)](https://docs.pingidentity.com/pingoneaic/tenants/configuration-placeholders.html) +- [PingOne configuration management](https://docs.pingidentity.com/pingone/early-access-features/ea-p1_promote.html) diff --git a/plugins/ping-identity/skills/ping-universal-services/references/curated/service-invocation-patterns.md b/plugins/ping-identity/skills/ping-universal-services/references/curated/service-invocation-patterns.md index 7526d22..caa41d4 100644 --- a/plugins/ping-identity/skills/ping-universal-services/references/curated/service-invocation-patterns.md +++ b/plugins/ping-identity/skills/ping-universal-services/references/curated/service-invocation-patterns.md @@ -210,7 +210,7 @@ Authorize REST response (abbreviated): ## Source [PingOne DaVinci connector library](https://docs.pingidentity.com/davinci/connectors) -[PingOne Protect API reference](https://apidocs.pingidentity.com/pingone/platform/v1/api/#post-create-risk-evaluation) -[PingOne Verify API reference](https://apidocs.pingidentity.com/pingone/verify/v1/api/) -[PingOne Authorize API reference](https://apidocs.pingidentity.com/pingone/authorize/v1/api/) +[PingOne Protect API reference](https://developer.pingidentity.com/pingone-api/protect/introduction.html) +[PingOne Verify API reference](https://developer.pingidentity.com/pingone-api/verify/introduction.html) +[PingOne Authorize API reference](https://developer.pingidentity.com/pingone-api/authorize/introduction.html) [AIC journey node reference](https://docs.pingidentity.com/pingoneaic/journeys/auth-nodes.html) From 40b6af4351b3a987b1205634fc4361dc3a62d16b Mon Sep 17 00:00:00 2001 From: "george.bafaloukas" Date: Tue, 23 Jun 2026 14:30:22 +0100 Subject: [PATCH 03/15] fix(ping-identity): address Brando's PR #8 review comments MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - config-promotion.md: add pingaccess, pingdirectory to products array - config-promotion.md + ping-cli-basics.md: replace hardcoded pingcli/1.0/ URLs with pingcli/latest/ to stay current across version changes (7 replacements) - am-services.md: clarify AIC email configuration — Email Provider and Email Templates under Tenant Settings, not IDM Notifications; note standalone PingIDM and PingAM behaviours separately (per Brando's correction) - common-starting-patterns.md: remove Okta/Auth0 migration section entirely (per Brando's request) Deferred for Patrick's review (comments 3, 4, 5, 8, 9 in PR #8): - pingcli accuracy in config-promotion.md (GitOps section) - recommended model selection table in config-promotion.md - ping-cli-basics.md overall accuracy - DaVinci flow versioning and promotion variables in journey-and-flow-promotion.md Taxonomy comment (comment 7): products array uses pingone-st which is the stable internal routing tag for AIC — correct per the taxonomy changes on this branch. Co-Authored-By: Claude Sonnet 4.6 (1M context) --- .../curated/cross-platform/config-promotion.md | 4 ++-- .../curated/cross-platform/ping-cli-basics.md | 14 +++++++------- .../references/curated/pingone-st/am-services.md | 2 +- .../references/curated/common-starting-patterns.md | 6 ------ 4 files changed, 10 insertions(+), 16 deletions(-) diff --git a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md index 6118f70..1a39dbe 100644 --- a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md +++ b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md @@ -1,7 +1,7 @@ --- title: "Configuration Promotion Across Environments" product_family: cross-platform -products: ["pingone", "pingone-st", "pingfederate"] +products: ["pingone", "pingone-st", "pingfederate", "pingaccess", "pingdirectory"] capabilities: ["foundation"] services: [] audience: ["admin", "architect", "operator"] @@ -96,7 +96,7 @@ Environment-specific values (connection endpoints, client IDs, URIs) must be ext | AIC | **Environment lock required** on source and target during promotion | Blocks ESV API and most admin APIs in the development environment; **authentication flows for end users are unaffected** | | AIC | Promotions take 10–45 minutes | Service restart in the upper environment is part of the process | | AIC | Rollback available via API only | Admin console does not expose rollback | -| Ping CLI export | Terraform HCL export scope varies by service | Not all services produce HCL; check the [product compatibility matrix](https://developer.pingidentity.com/pingcli/1.0/product-compatibility.html) | +| Ping CLI export | Terraform HCL export scope varies by service | Not all services produce HCL; check the [product compatibility matrix](https://developer.pingidentity.com/pingcli/latest/product-compatibility.html) | For current availability of specific resource types in native PingOne promotion, check the linked Ping documentation — this list changes as the feature evolves. diff --git a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md index 347c70f..5abccdb 100644 --- a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md +++ b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md @@ -34,7 +34,7 @@ Ping CLI (`pingcli`) is the unified open-source CLI for managing configuration a - Profile-based authentication so the same scripts run against dev, staging, and production - Raw admin API access with managed auth for endpoints that don't yet have first-class commands -For the current list of supported products and per-service CRUD availability, see the [product compatibility matrix](https://developer.pingidentity.com/pingcli/1.0/product-compatibility.html). +For the current list of supported products and per-service CRUD availability, see the [product compatibility matrix](https://developer.pingidentity.com/pingcli/latest/product-compatibility.html). > **Legacy note:** `pingctl` (earlier tool) is replaced by `pingcli`. Migrate by re-configuring profiles under the new tool. @@ -45,8 +45,8 @@ For the current list of supported products and per-service CRUD availability, se | Platform | Method | Command | |---|---|---| | macOS | Homebrew (recommended) | `brew install pingidentity/tap/pingcli` | -| Linux | Package manager (apt/yum) or binary | See [Linux install guide](https://developer.pingidentity.com/pingcli/1.0/install/linux.html) | -| Windows | Binary download | See [Windows install guide](https://developer.pingidentity.com/pingcli/1.0/install/windows.html) | +| Linux | Package manager (apt/yum) or binary | See [Linux install guide](https://developer.pingidentity.com/pingcli/latest/install/linux.html) | +| Windows | Binary download | See [Windows install guide](https://developer.pingidentity.com/pingcli/latest/install/windows.html) | | CI/CD | Docker image | `docker run pingidentity/pingcli:latest` | Verify: `pingcli version` @@ -126,7 +126,7 @@ pingcli platform export --service-group pingone pingcli platform export --format HCL ``` -**Export availability per product:** Not all products produce HCL today. `pingone-platform`, `pingone-sso`, `pingone-mfa`, `pingone-protect`, `pingone-authorize`, and `pingfederate` are supported; `pingone-davinci`, `pingone-credentials`, and `pingone-verify` are listed but export support is partial. Always check the [product compatibility page](https://developer.pingidentity.com/pingcli/1.0/product-compatibility.html) for the current status. +**Export availability per product:** Not all products produce HCL today. `pingone-platform`, `pingone-sso`, `pingone-mfa`, `pingone-protect`, `pingone-authorize`, and `pingfederate` are supported; `pingone-davinci`, `pingone-credentials`, and `pingone-verify` are listed but export support is partial. Always check the [product compatibility page](https://developer.pingidentity.com/pingcli/latest/product-compatibility.html) for the current status. **Terraformer plugin:** `pingcli-plugin-terraformer` (installed via `pingcli plugin add`) produces opinionated, ready-to-store HCL with post-processing suited for GitOps promotion pipelines. @@ -213,9 +213,9 @@ pingcli -D platform export ## Source - [Ping CLI overview](https://developer.pingidentity.com/pingcli/) -- [Install guide (1.0)](https://developer.pingidentity.com/pingcli/1.0/pingcli_landing_page.html) -- [Product compatibility matrix](https://developer.pingidentity.com/pingcli/1.0/product-compatibility.html) -- [Command reference (1.0)](https://developer.pingidentity.com/pingcli/1.0/command_reference/pingcli.html) +- [Install guide](https://developer.pingidentity.com/pingcli/latest/pingcli_landing_page.html) +- [Product compatibility matrix](https://developer.pingidentity.com/pingcli/latest/product-compatibility.html) +- [Command reference (1.0)](https://developer.pingidentity.com/pingcli/latest/command_reference/pingcli.html) - [Exporting platform configuration](https://developer.pingidentity.com/pingcli/general/exporting-platform-configuration.html) - [Configuration promotion overview](https://developer.pingidentity.com/config-automation-promotion/configuration_promotion_landing_page.html) - [GitHub: pingidentity/pingcli](https://github.com/pingidentity/pingcli) diff --git a/plugins/ping-identity/skills/ping-foundation/references/curated/pingone-st/am-services.md b/plugins/ping-identity/skills/ping-foundation/references/curated/pingone-st/am-services.md index d973252..f0329e3 100644 --- a/plugins/ping-identity/skills/ping-foundation/references/curated/pingone-st/am-services.md +++ b/plugins/ping-identity/skills/ping-foundation/references/curated/pingone-st/am-services.md @@ -222,7 +222,7 @@ Per-input validation rules invoked by `ValidatedUsernameNode`, `ValidatedPasswor Default user profile attribute exposure. Foundational; rarely modified. ### Email Service -**Not used on AIC.** Email delivery is handled by IDM Notifications, not this AM service. Do not invest time configuring this — configure email under IDM (Identity Management → Email). +**Not used on AIC.** In AIC, email delivery is configured via **Email Provider** and **Email Templates** (under Tenant Settings), not this AM service. Do not configure this AM-level service on AIC — it has no effect. For standalone PingIDM, configure email in IDM; for standalone PingAM, journey nodes connect to an external email provider directly. ### Dashboard Service *(See Global services above.)* diff --git a/plugins/ping-identity/skills/ping-quickstart/references/curated/common-starting-patterns.md b/plugins/ping-identity/skills/ping-quickstart/references/curated/common-starting-patterns.md index 91f6b5d..82b7ea1 100644 --- a/plugins/ping-identity/skills/ping-quickstart/references/curated/common-starting-patterns.md +++ b/plugins/ping-identity/skills/ping-quickstart/references/curated/common-starting-patterns.md @@ -158,12 +158,6 @@ Known gotchas: --- -## Note: Migrating from Okta or Auth0 - -Okta and Auth0 migrations are handled as guided engagements rather than self-service. Direct the customer to their Account Executive or open a support case to access migration tooling and partner support. - ---- - ## Pattern 6: Add identity verification (KYC) **Platform:** PingOne + PingOne Verify From 62e0391e3e2132984f293d884323e66226083ac4 Mon Sep 17 00:00:00 2001 From: "george.bafaloukas" Date: Tue, 23 Jun 2026 14:41:00 +0100 Subject: [PATCH 04/15] fix(ping-identity): revert broken pingcli/latest/ URLs back to 1.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit /pingcli/latest/ returns 404 — the site does not implement a /latest/ alias. The unversioned /pingcli/ root correctly redirects to the current version (1.0) and is already used in the slug: field. Deep-linked subpages (/product-compatibility, /install/*, /command_reference/*) require an explicit version in the path and correctly stay at 1.0. Pattern: top-level overview link uses the unversioned /pingcli/ redirect (durable); subpage links pin to /pingcli/1.0/ (the only valid path). Labels updated to include (1.0) so version pinning is transparent to future authors. Co-Authored-By: Claude Sonnet 4.6 (1M context) --- .../curated/cross-platform/config-promotion.md | 2 +- .../curated/cross-platform/ping-cli-basics.md | 14 +++++++------- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md index 1a39dbe..2b87757 100644 --- a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md +++ b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md @@ -96,7 +96,7 @@ Environment-specific values (connection endpoints, client IDs, URIs) must be ext | AIC | **Environment lock required** on source and target during promotion | Blocks ESV API and most admin APIs in the development environment; **authentication flows for end users are unaffected** | | AIC | Promotions take 10–45 minutes | Service restart in the upper environment is part of the process | | AIC | Rollback available via API only | Admin console does not expose rollback | -| Ping CLI export | Terraform HCL export scope varies by service | Not all services produce HCL; check the [product compatibility matrix](https://developer.pingidentity.com/pingcli/latest/product-compatibility.html) | +| Ping CLI export | Terraform HCL export scope varies by service | Not all services produce HCL; check the [product compatibility matrix](https://developer.pingidentity.com/pingcli/1.0/product-compatibility.html) | For current availability of specific resource types in native PingOne promotion, check the linked Ping documentation — this list changes as the feature evolves. diff --git a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md index 5abccdb..b55c764 100644 --- a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md +++ b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md @@ -34,7 +34,7 @@ Ping CLI (`pingcli`) is the unified open-source CLI for managing configuration a - Profile-based authentication so the same scripts run against dev, staging, and production - Raw admin API access with managed auth for endpoints that don't yet have first-class commands -For the current list of supported products and per-service CRUD availability, see the [product compatibility matrix](https://developer.pingidentity.com/pingcli/latest/product-compatibility.html). +For the current list of supported products and per-service CRUD availability, see the [product compatibility matrix](https://developer.pingidentity.com/pingcli/1.0/product-compatibility.html). > **Legacy note:** `pingctl` (earlier tool) is replaced by `pingcli`. Migrate by re-configuring profiles under the new tool. @@ -45,8 +45,8 @@ For the current list of supported products and per-service CRUD availability, se | Platform | Method | Command | |---|---|---| | macOS | Homebrew (recommended) | `brew install pingidentity/tap/pingcli` | -| Linux | Package manager (apt/yum) or binary | See [Linux install guide](https://developer.pingidentity.com/pingcli/latest/install/linux.html) | -| Windows | Binary download | See [Windows install guide](https://developer.pingidentity.com/pingcli/latest/install/windows.html) | +| Linux | Package manager (apt/yum) or binary | See [Linux install guide](https://developer.pingidentity.com/pingcli/1.0/install/linux.html) | +| Windows | Binary download | See [Windows install guide](https://developer.pingidentity.com/pingcli/1.0/install/windows.html) | | CI/CD | Docker image | `docker run pingidentity/pingcli:latest` | Verify: `pingcli version` @@ -126,7 +126,7 @@ pingcli platform export --service-group pingone pingcli platform export --format HCL ``` -**Export availability per product:** Not all products produce HCL today. `pingone-platform`, `pingone-sso`, `pingone-mfa`, `pingone-protect`, `pingone-authorize`, and `pingfederate` are supported; `pingone-davinci`, `pingone-credentials`, and `pingone-verify` are listed but export support is partial. Always check the [product compatibility page](https://developer.pingidentity.com/pingcli/latest/product-compatibility.html) for the current status. +**Export availability per product:** Not all products produce HCL today. `pingone-platform`, `pingone-sso`, `pingone-mfa`, `pingone-protect`, `pingone-authorize`, and `pingfederate` are supported; `pingone-davinci`, `pingone-credentials`, and `pingone-verify` are listed but export support is partial. Always check the [product compatibility page](https://developer.pingidentity.com/pingcli/1.0/product-compatibility.html) for the current status. **Terraformer plugin:** `pingcli-plugin-terraformer` (installed via `pingcli plugin add`) produces opinionated, ready-to-store HCL with post-processing suited for GitOps promotion pipelines. @@ -213,9 +213,9 @@ pingcli -D platform export ## Source - [Ping CLI overview](https://developer.pingidentity.com/pingcli/) -- [Install guide](https://developer.pingidentity.com/pingcli/latest/pingcli_landing_page.html) -- [Product compatibility matrix](https://developer.pingidentity.com/pingcli/latest/product-compatibility.html) -- [Command reference (1.0)](https://developer.pingidentity.com/pingcli/latest/command_reference/pingcli.html) +- [Install guide (1.0)](https://developer.pingidentity.com/pingcli/1.0/pingcli_landing_page.html) +- [Product compatibility matrix (1.0)](https://developer.pingidentity.com/pingcli/1.0/product-compatibility.html) +- [Command reference (1.0)](https://developer.pingidentity.com/pingcli/1.0/command_reference/pingcli.html) - [Exporting platform configuration](https://developer.pingidentity.com/pingcli/general/exporting-platform-configuration.html) - [Configuration promotion overview](https://developer.pingidentity.com/config-automation-promotion/configuration_promotion_landing_page.html) - [GitHub: pingidentity/pingcli](https://github.com/pingidentity/pingcli) From ba820afd8f2dd4e452cc9d0344b40f5f458050a3 Mon Sep 17 00:00:00 2001 From: "george.bafaloukas" Date: Tue, 23 Jun 2026 14:58:51 +0100 Subject: [PATCH 05/15] fix(ping-identity): reframe model-selection tables from prescriptive to factual MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Addresses Brando's PR #8 comment on the 'Recommended model' column — the table entries were inferred rather than sourced from Ping's own guidance. - Replace 'Recommended model' with 'Typical fit' in config-promotion.md - Replace 'Recommendation' with 'Typical fit' in journey-and-flow-promotion.md - Add 'Why' column to each table explaining the factual suitability basis (platform constraints, scope, toolchain requirements) rather than prescribing - Add pointer to developer.pingidentity.com/config-automation-promotion/ for Ping's own guidance on model selection Co-Authored-By: Claude Sonnet 4.6 (1M context) --- .../curated/cross-platform/config-promotion.md | 16 +++++++++------- .../cross-platform/journey-and-flow-promotion.md | 12 ++++++------ 2 files changed, 15 insertions(+), 13 deletions(-) diff --git a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md index 2b87757..550006d 100644 --- a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md +++ b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md @@ -129,13 +129,15 @@ The `pingcli-plugin-terraformer` plugin adds opinionated post-processing to prod ## Choosing a promotion model -| Scenario | Recommended model | -|---|---| -| Single PingOne org, DaVinci-heavy config, in-console workflow preferred | PingOne native promotion | -| AIC tenant with dev/staging/prod chain, sequential promotion | AIC self-service promotions | -| Multi-product (PingOne + PingFederate), multi-org, or full CaC audit trail required | Ping CLI + Terraform | -| Mixed: PingOne apps + AIC journeys | Both: native/AIC for fast iteration; Terraform for baseline config and cross-product consistency | -| PingFederate federation config between servers | Server profiles (Git) + Terraform provider | +For Ping's own guidance on model selection see the [configuration promotion overview](https://developer.pingidentity.com/config-automation-promotion/configuration_promotion_landing_page.html). + +| Scenario | Typical fit | Why | +|---|---|---| +| Config lives entirely within one PingOne org; team prefers admin-console workflow | PingOne native promotion | Designed for same-org, in-console use; automatic dependency management; no toolchain required | +| AIC tenant with dev/staging/prod environments | AIC self-service promotions | The only natively supported path between AIC environments; sequential pairs enforced by the platform | +| Multi-product (PingOne + PingFederate), cross-org, or Git-backed audit trail needed | Ping CLI + Terraform | Only model that spans multiple products and orgs; state tracking and drift detection via Terraform | +| Mix of PingOne and AIC in the same pipeline | Can combine both | Native/AIC handles per-platform config; Terraform handles cross-product baseline and long-term state | +| PingFederate configuration between servers | Server profiles (Git) + Terraform provider | PingFederate's native config-as-code model; no equivalent in-console promotion UI | --- diff --git a/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md b/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md index af2cdc0..cbff4ff 100644 --- a/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md +++ b/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md @@ -152,12 +152,12 @@ If a promoted journey causes issues in the upper environment, AIC self-service r ## Choosing native promotion vs Terraform for journey/flow work -| Scenario | Recommendation | -|---|---| -| AIC journey iteration within one tenant chain | AIC self-service promotions — fastest path, admin-console-driven | -| DaVinci flow changes within one PingOne org | PingOne native promotion — in-console, automatic dependency management | -| Multi-org, multi-cloud, or full audit trail required | Terraform (export via `pingcli platform export`, manage with Ping Terraform providers) | -| Mixed AIC + DaVinci in the same pipeline | Both: native/AIC for journeys; Terraform for CaC baseline | +| Scenario | Typical fit | Why | +|---|---|---| +| AIC journey iteration within one tenant chain | AIC self-service promotions | Native path between AIC environments; admin-console-driven; sequential pairs enforced by the platform | +| DaVinci flow changes within one PingOne org | PingOne native promotion | In-console; automatic dependency management; same-org constraint applies | +| Multi-org, multi-cloud, or Git-backed audit trail needed | Ping CLI + Terraform | Spans organisations and products; state tracking and drift detection | +| Mixed AIC journeys + DaVinci flows in the same pipeline | Can combine both | Each platform's native model handles its own config; Terraform manages cross-product baseline | --- From d1ff65cd627c475bc4e5d70903419bba21218636 Mon Sep 17 00:00:00 2001 From: "george.bafaloukas" Date: Tue, 23 Jun 2026 15:02:56 +0100 Subject: [PATCH 06/15] fix(ping-identity): correct factual inaccuracies in model-selection tables MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Verified each 'Why' claim against docs.pingidentity.com and Glean. Four fixes: 1. AIC row (both tables): remove 'only natively supported path' — docs don't use this phrasing and Terraform/community tooling are valid alternatives; replace with 'platform-provided self-service path' 2. Multi-product row (both tables): Ping CLI CRUD for PingFederate is still rolling out (compatibility matrix shows it as 'coming soon'); PingAccess and PingDirectory are absent from the Ping CLI matrix entirely. Terraform providers cover all three — the two are now distinguished; link to the live compatibility matrix so agents check current state rather than relying on frozen prose Confirmed accurate (no change needed): - Same-org constraint on PingOne native promotion - Automatic dependency management for DaVinci flows - Sequential-pairs enforcement on AIC - PingFederate server profiles / no in-console promotion UI - Terraform drift detection claim Co-Authored-By: Claude Sonnet 4.6 (1M context) --- .../references/curated/cross-platform/config-promotion.md | 4 ++-- .../curated/cross-platform/journey-and-flow-promotion.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md index 550006d..d7ba1ae 100644 --- a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md +++ b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md @@ -134,8 +134,8 @@ For Ping's own guidance on model selection see the [configuration promotion over | Scenario | Typical fit | Why | |---|---|---| | Config lives entirely within one PingOne org; team prefers admin-console workflow | PingOne native promotion | Designed for same-org, in-console use; automatic dependency management; no toolchain required | -| AIC tenant with dev/staging/prod environments | AIC self-service promotions | The only natively supported path between AIC environments; sequential pairs enforced by the platform | -| Multi-product (PingOne + PingFederate), cross-org, or Git-backed audit trail needed | Ping CLI + Terraform | Only model that spans multiple products and orgs; state tracking and drift detection via Terraform | +| AIC tenant with dev/staging/prod environments | AIC self-service promotions | The platform-provided self-service promotion path for AIC; sequential pairs enforced by the platform (dev→staging→production only) | +| Cross-product (PingOne + PingFederate/PingAccess), cross-org, or Git-backed audit trail needed | Ping CLI + Terraform | Terraform providers cover PingFederate, PingAccess, and PingDirectory; Ping CLI CRUD for PingFederate is still rolling out — check the [compatibility matrix](https://developer.pingidentity.com/pingcli/1.0/product-compatibility.html); state tracking and drift detection via Terraform | | Mix of PingOne and AIC in the same pipeline | Can combine both | Native/AIC handles per-platform config; Terraform handles cross-product baseline and long-term state | | PingFederate configuration between servers | Server profiles (Git) + Terraform provider | PingFederate's native config-as-code model; no equivalent in-console promotion UI | diff --git a/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md b/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md index cbff4ff..084a003 100644 --- a/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md +++ b/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md @@ -154,9 +154,9 @@ If a promoted journey causes issues in the upper environment, AIC self-service r | Scenario | Typical fit | Why | |---|---|---| -| AIC journey iteration within one tenant chain | AIC self-service promotions | Native path between AIC environments; admin-console-driven; sequential pairs enforced by the platform | +| AIC journey iteration within one tenant chain | AIC self-service promotions | Platform-provided self-service path for AIC; admin-console-driven; sequential pairs enforced by the platform (dev→staging→production only) | | DaVinci flow changes within one PingOne org | PingOne native promotion | In-console; automatic dependency management; same-org constraint applies | -| Multi-org, multi-cloud, or Git-backed audit trail needed | Ping CLI + Terraform | Spans organisations and products; state tracking and drift detection | +| Multi-org, multi-cloud, or Git-backed audit trail needed | Ping CLI + Terraform | Terraform providers span PingFederate, PingAccess, PingDirectory, and PingOne; Ping CLI CRUD for PingFederate is still rolling out — check the [compatibility matrix](https://developer.pingidentity.com/pingcli/1.0/product-compatibility.html); state tracking and drift detection via Terraform | | Mixed AIC journeys + DaVinci flows in the same pipeline | Can combine both | Each platform's native model handles its own config; Terraform manages cross-product baseline | --- From 886d4d486e9dc7f413707ddbf6f9e6c2a8eecf29 Mon Sep 17 00:00:00 2001 From: "george.bafaloukas" Date: Tue, 23 Jun 2026 15:08:48 +0100 Subject: [PATCH 07/15] fix(ping-identity): correct DaVinci connector credential promotion behaviour Connector config structure moves in PingOne native promotion, but sensitive attributes (client secrets, API keys) are blocked by the platform and cannot transfer directly. Sensitive promotion variables must be pre-created in the target environment before promotion. Verified against: - docs.pingidentity.com/pingone/early-access-features/ea-p1_configuration_management_special_handling.html - docs.pingidentity.com/pingone/early-access-features/ea-p1_promotion_key_concepts.html Also adds the dependency-inclusion note for flow policies (dependent flow versions are auto-included when a policy is promoted directly). Co-Authored-By: Claude Sonnet 4.6 (1M context) --- .../curated/cross-platform/journey-and-flow-promotion.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md b/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md index 084a003..f33a391 100644 --- a/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md +++ b/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md @@ -47,10 +47,10 @@ Journey-, script-, and DaVinci-flow-specific concerns when promoting between AIC **Moves via native PingOne promotion:** - Flow definitions (all versions) -- Flow policies -- Connector configurations (connection IDs and settings) +- Flow policies (with their dependent flow versions auto-included) +- Connector configuration structure (connection IDs and non-secret settings) -**Key gotcha:** Connector credentials (client IDs, secrets, API keys) are environment-specific. Use **promotion variables** to externalise them so the promoted flow references the target environment's credential values, not the source's. +**Connector credentials do not move directly.** PingOne blocks promotion of any attribute marked sensitive (client IDs, secrets, API keys embedded in connector config). You must create **sensitive promotion variables** for those attributes in the target environment before the promotion can complete — the connector structure is promoted, but resolves to the target's credentials at promotion time, not the source's. --- From 65352b0a77246c242a3b84e1a0e3e9aac4e2a1c3 Mon Sep 17 00:00:00 2001 From: "george.bafaloukas" Date: Tue, 23 Jun 2026 15:17:00 +0100 Subject: [PATCH 08/15] fix(ping-identity): correct two inaccuracies in DaVinci connector promotion text MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Verified against docs.pingidentity.com/pingone/early-access-features/: 1. 'client IDs' removed from list of sensitive attributes — client IDs are non-sensitive and do move as structural config; client secrets, API keys, and passwords are the sensitive attributes the platform gates on 2. Variable creation location corrected — variables are created in the SOURCE environment (specifying the target-environment value), not in the target. The previous text inverted the correct mental model. Now reads: 'Variables are created in the source environment with the target-specific value specified at that point' 3. 'blocks' → 'gates' — the platform issues a mandatory prompt/gate; the promotion completes once the sensitive variable exists (not a flat block on the resource itself) All other claims confirmed accurate by doc verification. Co-Authored-By: Claude Sonnet 4.6 (1M context) --- .../curated/cross-platform/journey-and-flow-promotion.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md b/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md index f33a391..1f0b1ad 100644 --- a/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md +++ b/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md @@ -50,7 +50,7 @@ Journey-, script-, and DaVinci-flow-specific concerns when promoting between AIC - Flow policies (with their dependent flow versions auto-included) - Connector configuration structure (connection IDs and non-secret settings) -**Connector credentials do not move directly.** PingOne blocks promotion of any attribute marked sensitive (client IDs, secrets, API keys embedded in connector config). You must create **sensitive promotion variables** for those attributes in the target environment before the promotion can complete — the connector structure is promoted, but resolves to the target's credentials at promotion time, not the source's. +**Connector credentials do not move directly.** PingOne gates promotion of any attribute marked sensitive (client secrets, API keys, passwords embedded in connector config) — the promotion cannot proceed until a **sensitive promotion variable** exists for each blocked attribute. Variables are created in the *source* environment with the target-specific value specified at that point; the connector structure is then promoted and resolves to those target values at promotion time, not the source's. --- From 6e7e0fbb7599062bc3ccd4888bdbdf85c418cd39 Mon Sep 17 00:00:00 2001 From: "george.bafaloukas" Date: Tue, 23 Jun 2026 15:23:06 +0100 Subject: [PATCH 09/15] fix(ping-identity): correct four inaccuracies in DaVinci flow promotion section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Re-verified all claims against docs.pingidentity.com/pingone/early-access-features/. 1. 'Flow definitions (all versions)' → only the most recently deployed version is promoted. If version 3 is the most recently deployed of 4 versions, only version 3 moves. Official doc: 'Only the most recent deployed version of the flow is promoted to the target environment.' 2. 'moves the published version' → 'most recently deployed version'; doc uses 'deployed' not 'published' 3. Flow-policy dependency direction inverted: the correct action is to promote the FLOW POLICY (which auto-includes referenced flow versions as dependencies), not to promote the flow and separately also promote the policy. Inverting this leaves the policy out of sync. 4. Promotion variable step 2 placed assignment in the TARGET environment — official doc states: 'Variables are always created and configured in the source environment.' Target values are specified at creation time in the source. Step 2 now correctly says 'In the source environment, create a sensitive promotion variable...' Also removes 'client IDs' which reappeared in the promotion variables section — client IDs are non-sensitive structural config, not a sensitive attribute requiring a variable. Co-Authored-By: Claude Sonnet 4.6 (1M context) --- .../cross-platform/journey-and-flow-promotion.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md b/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md index 1f0b1ad..b282ccc 100644 --- a/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md +++ b/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md @@ -46,8 +46,8 @@ Journey-, script-, and DaVinci-flow-specific concerns when promoting between AIC ### PingOne DaVinci flows **Moves via native PingOne promotion:** -- Flow definitions (all versions) -- Flow policies (with their dependent flow versions auto-included) +- Flow definitions — **most recently deployed version only** (not all versions; if you have 4 versions and version 3 is the most recently deployed, only version 3 promotes) +- Flow policies (with their referenced flow versions auto-included as dependencies) - Connector configuration structure (connection IDs and non-secret settings) **Connector credentials do not move directly.** PingOne gates promotion of any attribute marked sensitive (client secrets, API keys, passwords embedded in connector config) — the promotion cannot proceed until a **sensitive promotion variable** exists for each blocked attribute. Variables are created in the *source* environment with the target-specific value specified at that point; the connector structure is then promoted and resolves to those target values at promotion time, not the source's. @@ -80,19 +80,19 @@ Review Scripted Decision node scripts for `logger.error(...)` or `logger.message ### Flow versioning -Each DaVinci flow has a **saved version** (draft) and a **published version** (live). Native PingOne promotion moves the published version. Ensure the correct version is published before triggering a promotion. +Each DaVinci flow has multiple versions; only the **most recently deployed version** is promoted to the target environment. Ensure the correct version is deployed before triggering a promotion. ### Flow-policy dependency -Flow policies reference a specific flow and version. When promoting a flow, also promote its associated flow policy — an unpromoted policy pointing at a flow that no longer matches will fail at authentication time. +Flow policies reference specific flows and specific versions of those flows. **Promote the flow policy** — the promotion service then auto-includes the referenced flow versions as dependencies. Promoting the flow directly without the policy leaves the policy out of sync and will fail at authentication time. ### Promotion variables for connector credentials -In DaVinci, connector credentials (client IDs, client secrets, webhook URLs, API keys) are environment-specific. Use **DaVinci promotion variables** to bind these to environment-specific values: +In DaVinci, connector credentials (client secrets, webhook URLs, API keys) are environment-specific. PingOne auto-detects sensitive attributes and requires **sensitive promotion variables** before the promotion can proceed: -1. In the source flow, replace the literal credential with a promotion variable token. -2. In the target environment, assign the variable to the target-side credential value before applying the promotion. -3. DaVinci flow promotion validates that all referenced variables have assigned values in the target. +1. When you select a connector config resource for promotion, PingOne identifies sensitive attributes and auto-selects them as requiring variables — you cannot clear this. +2. In the **source environment**, create a sensitive promotion variable for each blocked attribute and specify the target environment's value at that point. +3. The promotion proceeds; the connector resolves to those target values after promotion, not the source's. --- From bbbbe8e0afa1f17ed8eef43955847417abaf6d67 Mon Sep 17 00:00:00 2001 From: "george.bafaloukas" Date: Tue, 23 Jun 2026 15:25:47 +0100 Subject: [PATCH 10/15] fix(ping-identity): two remaining inaccuracies in DaVinci flow promotion section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Re-verified all claims exhaustively with doc quotes. Two remaining issues: 1. 'will fail at authentication time' — this consequence is not stated in any of the four official docs pages; it was an inference presented as a documented fact. Softened to: 'the policy in the target environment may reference a different version than the one you promoted.' 2. Missing LDAP gateway carve-out: the special_handling doc explicitly states 'Gateway credentials can't be promoted or managed using promotion variables' — added as an inline exception on the connector config bullet. All other claims now confirmed with verbatim doc quotes. Section is fully backed by docs.pingidentity.com/pingone/early-access-features/ sources. Co-Authored-By: Claude Sonnet 4.6 (1M context) --- .../curated/cross-platform/journey-and-flow-promotion.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md b/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md index b282ccc..65beb6d 100644 --- a/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md +++ b/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md @@ -48,7 +48,7 @@ Journey-, script-, and DaVinci-flow-specific concerns when promoting between AIC **Moves via native PingOne promotion:** - Flow definitions — **most recently deployed version only** (not all versions; if you have 4 versions and version 3 is the most recently deployed, only version 3 promotes) - Flow policies (with their referenced flow versions auto-included as dependencies) -- Connector configuration structure (connection IDs and non-secret settings) +- Connector configuration structure (connection IDs and non-secret settings) — **exception: LDAP gateway credentials cannot be promoted or managed using promotion variables** and must be manually configured in each environment **Connector credentials do not move directly.** PingOne gates promotion of any attribute marked sensitive (client secrets, API keys, passwords embedded in connector config) — the promotion cannot proceed until a **sensitive promotion variable** exists for each blocked attribute. Variables are created in the *source* environment with the target-specific value specified at that point; the connector structure is then promoted and resolves to those target values at promotion time, not the source's. @@ -84,7 +84,7 @@ Each DaVinci flow has multiple versions; only the **most recently deployed versi ### Flow-policy dependency -Flow policies reference specific flows and specific versions of those flows. **Promote the flow policy** — the promotion service then auto-includes the referenced flow versions as dependencies. Promoting the flow directly without the policy leaves the policy out of sync and will fail at authentication time. +Flow policies reference specific flows and specific versions of those flows. **Promote the flow policy** — the promotion service then auto-includes the referenced flow versions as dependencies. If you promote a flow independently without also promoting its flow policy, the policy in the target environment may reference a different version than the one you promoted. ### Promotion variables for connector credentials From 57bab8a7f2b6fb27b3e040aaa1a8368d8ada482d Mon Sep 17 00:00:00 2001 From: "george.bafaloukas" Date: Wed, 24 Jun 2026 10:38:46 +0100 Subject: [PATCH 11/15] fix(ping-identity): update pingcli deep-links from 1.0 to latest /pingcli/latest/ URLs now resolve (confirmed 200 on all 5 paths as of 2026-06-24). Replaces all pingcli/1.0/ deep-link references in ping-cli-basics.md, config-promotion.md, and journey-and-flow-promotion.md with pingcli/latest/, matching Brando's original intent. Removes (1.0) version labels from the Source section of ping-cli-basics.md since URLs are now version-agnostic. Co-Authored-By: Claude Sonnet 4.6 (1M context) --- .../curated/cross-platform/config-promotion.md | 4 ++-- .../curated/cross-platform/ping-cli-basics.md | 14 +++++++------- .../cross-platform/journey-and-flow-promotion.md | 2 +- 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md index d7ba1ae..e552866 100644 --- a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md +++ b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md @@ -96,7 +96,7 @@ Environment-specific values (connection endpoints, client IDs, URIs) must be ext | AIC | **Environment lock required** on source and target during promotion | Blocks ESV API and most admin APIs in the development environment; **authentication flows for end users are unaffected** | | AIC | Promotions take 10–45 minutes | Service restart in the upper environment is part of the process | | AIC | Rollback available via API only | Admin console does not expose rollback | -| Ping CLI export | Terraform HCL export scope varies by service | Not all services produce HCL; check the [product compatibility matrix](https://developer.pingidentity.com/pingcli/1.0/product-compatibility.html) | +| Ping CLI export | Terraform HCL export scope varies by service | Not all services produce HCL; check the [product compatibility matrix](https://developer.pingidentity.com/pingcli/latest/product-compatibility.html) | For current availability of specific resource types in native PingOne promotion, check the linked Ping documentation — this list changes as the feature evolves. @@ -135,7 +135,7 @@ For Ping's own guidance on model selection see the [configuration promotion over |---|---|---| | Config lives entirely within one PingOne org; team prefers admin-console workflow | PingOne native promotion | Designed for same-org, in-console use; automatic dependency management; no toolchain required | | AIC tenant with dev/staging/prod environments | AIC self-service promotions | The platform-provided self-service promotion path for AIC; sequential pairs enforced by the platform (dev→staging→production only) | -| Cross-product (PingOne + PingFederate/PingAccess), cross-org, or Git-backed audit trail needed | Ping CLI + Terraform | Terraform providers cover PingFederate, PingAccess, and PingDirectory; Ping CLI CRUD for PingFederate is still rolling out — check the [compatibility matrix](https://developer.pingidentity.com/pingcli/1.0/product-compatibility.html); state tracking and drift detection via Terraform | +| Cross-product (PingOne + PingFederate/PingAccess), cross-org, or Git-backed audit trail needed | Ping CLI + Terraform | Terraform providers cover PingFederate, PingAccess, and PingDirectory; Ping CLI CRUD for PingFederate is still rolling out — check the [compatibility matrix](https://developer.pingidentity.com/pingcli/latest/product-compatibility.html); state tracking and drift detection via Terraform | | Mix of PingOne and AIC in the same pipeline | Can combine both | Native/AIC handles per-platform config; Terraform handles cross-product baseline and long-term state | | PingFederate configuration between servers | Server profiles (Git) + Terraform provider | PingFederate's native config-as-code model; no equivalent in-console promotion UI | diff --git a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md index b55c764..14df252 100644 --- a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md +++ b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md @@ -34,7 +34,7 @@ Ping CLI (`pingcli`) is the unified open-source CLI for managing configuration a - Profile-based authentication so the same scripts run against dev, staging, and production - Raw admin API access with managed auth for endpoints that don't yet have first-class commands -For the current list of supported products and per-service CRUD availability, see the [product compatibility matrix](https://developer.pingidentity.com/pingcli/1.0/product-compatibility.html). +For the current list of supported products and per-service CRUD availability, see the [product compatibility matrix](https://developer.pingidentity.com/pingcli/latest/product-compatibility.html). > **Legacy note:** `pingctl` (earlier tool) is replaced by `pingcli`. Migrate by re-configuring profiles under the new tool. @@ -45,8 +45,8 @@ For the current list of supported products and per-service CRUD availability, se | Platform | Method | Command | |---|---|---| | macOS | Homebrew (recommended) | `brew install pingidentity/tap/pingcli` | -| Linux | Package manager (apt/yum) or binary | See [Linux install guide](https://developer.pingidentity.com/pingcli/1.0/install/linux.html) | -| Windows | Binary download | See [Windows install guide](https://developer.pingidentity.com/pingcli/1.0/install/windows.html) | +| Linux | Package manager (apt/yum) or binary | See [Linux install guide](https://developer.pingidentity.com/pingcli/latest/install/linux.html) | +| Windows | Binary download | See [Windows install guide](https://developer.pingidentity.com/pingcli/latest/install/windows.html) | | CI/CD | Docker image | `docker run pingidentity/pingcli:latest` | Verify: `pingcli version` @@ -126,7 +126,7 @@ pingcli platform export --service-group pingone pingcli platform export --format HCL ``` -**Export availability per product:** Not all products produce HCL today. `pingone-platform`, `pingone-sso`, `pingone-mfa`, `pingone-protect`, `pingone-authorize`, and `pingfederate` are supported; `pingone-davinci`, `pingone-credentials`, and `pingone-verify` are listed but export support is partial. Always check the [product compatibility page](https://developer.pingidentity.com/pingcli/1.0/product-compatibility.html) for the current status. +**Export availability per product:** Not all products produce HCL today. `pingone-platform`, `pingone-sso`, `pingone-mfa`, `pingone-protect`, `pingone-authorize`, and `pingfederate` are supported; `pingone-davinci`, `pingone-credentials`, and `pingone-verify` are listed but export support is partial. Always check the [product compatibility page](https://developer.pingidentity.com/pingcli/latest/product-compatibility.html) for the current status. **Terraformer plugin:** `pingcli-plugin-terraformer` (installed via `pingcli plugin add`) produces opinionated, ready-to-store HCL with post-processing suited for GitOps promotion pipelines. @@ -213,9 +213,9 @@ pingcli -D platform export ## Source - [Ping CLI overview](https://developer.pingidentity.com/pingcli/) -- [Install guide (1.0)](https://developer.pingidentity.com/pingcli/1.0/pingcli_landing_page.html) -- [Product compatibility matrix (1.0)](https://developer.pingidentity.com/pingcli/1.0/product-compatibility.html) -- [Command reference (1.0)](https://developer.pingidentity.com/pingcli/1.0/command_reference/pingcli.html) +- [Install guide](https://developer.pingidentity.com/pingcli/latest/pingcli_landing_page.html) +- [Product compatibility matrix](https://developer.pingidentity.com/pingcli/latest/product-compatibility.html) +- [Command reference](https://developer.pingidentity.com/pingcli/latest/command_reference/pingcli.html) - [Exporting platform configuration](https://developer.pingidentity.com/pingcli/general/exporting-platform-configuration.html) - [Configuration promotion overview](https://developer.pingidentity.com/config-automation-promotion/configuration_promotion_landing_page.html) - [GitHub: pingidentity/pingcli](https://github.com/pingidentity/pingcli) diff --git a/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md b/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md index 65beb6d..0da5951 100644 --- a/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md +++ b/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md @@ -156,7 +156,7 @@ If a promoted journey causes issues in the upper environment, AIC self-service r |---|---|---| | AIC journey iteration within one tenant chain | AIC self-service promotions | Platform-provided self-service path for AIC; admin-console-driven; sequential pairs enforced by the platform (dev→staging→production only) | | DaVinci flow changes within one PingOne org | PingOne native promotion | In-console; automatic dependency management; same-org constraint applies | -| Multi-org, multi-cloud, or Git-backed audit trail needed | Ping CLI + Terraform | Terraform providers span PingFederate, PingAccess, PingDirectory, and PingOne; Ping CLI CRUD for PingFederate is still rolling out — check the [compatibility matrix](https://developer.pingidentity.com/pingcli/1.0/product-compatibility.html); state tracking and drift detection via Terraform | +| Multi-org, multi-cloud, or Git-backed audit trail needed | Ping CLI + Terraform | Terraform providers span PingFederate, PingAccess, PingDirectory, and PingOne; Ping CLI CRUD for PingFederate is still rolling out — check the [compatibility matrix](https://developer.pingidentity.com/pingcli/latest/product-compatibility.html); state tracking and drift detection via Terraform | | Mixed AIC journeys + DaVinci flows in the same pipeline | Can combine both | Each platform's native model handles its own config; Terraform manages cross-product baseline | --- From a2d34594ccf1a94b0580c1f5e55df452390bda61 Mon Sep 17 00:00:00 2001 From: "george.bafaloukas" Date: Wed, 24 Jun 2026 11:39:53 +0100 Subject: [PATCH 12/15] fix(ping-identity): remove 0.8 features from CLI anchor, fix scope contradiction Addresses Patrick's PR #8 review comments. ping-cli-basics.md: - Remove pingcli platform export section (0.8 feature, not in 1.x) - Remove Custom API requests / pingcli request section (0.8 feature) - Remove 0.8 version note and 0.8 command-name gotcha row - Remove Terraformer plugin references throughout - Remove Terraform GitOps variant row and Terraform HCL from Prerequisites - Reframe intro/Scope to 'why Ping CLI' over 'how' per Patrick's direction - Explicitly call out platform export and pingcli request as out-of-scope with a pointer to the compatibility matrix for current 1.x feature state config-promotion.md: - Remove entire GitOps/pingcli platform export section (steps 1-6) - Replace 'exportable via pingcli platform export' with Terraform providers - Replace platform-export-specific gotcha row with Terraform provider gap row - Remove pingcli-general/exporting source link - Update related-references description to remove export mention journey-and-flow-promotion.md: - Fix Scope contradiction: 'Does NOT cover: general promotion model' was inconsistent with the DaVinci native promotion content below it; rewrite Scope to explicitly state what IS covered (AIC self-service + PingOne native promotion for DaVinci flows) vs what is not (Terraform/CaC, general model choice) - Replace 'Export with pingcli platform export' in Terraform variant row Co-Authored-By: Claude Sonnet 4.6 (1M context) --- .../cross-platform/config-promotion.md | 24 +----- .../curated/cross-platform/ping-cli-basics.md | 77 ++++--------------- .../journey-and-flow-promotion.md | 4 +- 3 files changed, 21 insertions(+), 84 deletions(-) diff --git a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md index e552866..cd8ab3b 100644 --- a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md +++ b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md @@ -31,7 +31,7 @@ How to move Ping Identity configuration between development, staging, and produc |---|---|---|---|---| | **PingOne native promotion** | PingOne (multi-tenant cloud) | Applications, DaVinci flows and policies, sign-on policies, and most PingOne resources | Authorize, Credentials, Privilege, runtime user data, sessions, audit logs | Source/target same org; check live docs for current resource scope | | **AIC self-service promotions** | PingOne Advanced Identity Cloud | Journeys, scripts, themes, AM/IDM static config, ESV references | Live users, sessions, user-created applications, runtime data | Sequential pairs only: dev→staging, staging→production. Non-sequential promotion not supported. | -| **Ping CLI + Terraform (config-as-code)** | PingOne, PingFederate, DaVinci, and supported universal services | Any resource exportable via `pingcli platform export`; Terraform-managed config | Per-resource, determined by provider support | None — Terraform manages state independently per target environment | +| **Ping CLI + Terraform (config-as-code)** | PingOne, PingFederate, DaVinci, and supported universal services | Terraform-managed config via Ping Identity Terraform providers | Per-resource, determined by provider support | None — Terraform manages state independently per target environment | --- @@ -54,7 +54,7 @@ How to move Ping Identity configuration between development, staging, and produc ### Ping Software (PingFederate, PingAccess, PingDirectory) - Configuration is managed via **server profiles** (Git-backed config-as-code). Promotion = merging and applying a server-profile branch. -- Use `pingcli platform export` to extract current running config as Terraform HCL as a starting point. +- The Ping Identity Terraform providers cover PingFederate, PingAccess, and PingDirectory for state-managed config-as-code. --- @@ -112,21 +112,6 @@ For current availability of specific resource types in native PingOne promotion, --- -## GitOps pattern with Ping CLI + Terraform - -For multi-product or multi-environment pipelines beyond a single org: - -1. `pingcli platform export --format HCL` — extract current config from a reference environment -2. Store HCL in version control alongside `*.tfvars` per target environment -3. Raise a PR; review diffs as configuration changes -4. Run `terraform plan` against the target environment (dry run) -5. Apply on merge: `terraform apply` -6. Verify post-apply via smoke tests or `pingcli pingone ... list` - -The `pingcli-plugin-terraformer` plugin adds opinionated post-processing to produce cleaner, version-control-ready HCL. For details see `references/curated/cross-platform/ping-cli-basics.md`. - ---- - ## Choosing a promotion model For Ping's own guidance on model selection see the [configuration promotion overview](https://developer.pingidentity.com/config-automation-promotion/configuration_promotion_landing_page.html). @@ -169,13 +154,13 @@ For Ping's own guidance on model selection see the [configuration promotion over | PingOne promotion fails on service dependency | Target env missing a service the source config references | Enable the service in the target environment before promoting | | AIC promotion locks admin APIs longer than expected | Large config sets take 10–45 minutes; lock is held throughout | Schedule promotions during low-traffic windows; monitor the promotion status API | | Rollback restores unexpected state | Multiple promotions in quick succession | Wait for each promotion to complete before running the next; check the promotion history before rollback | -| `pingcli platform export` produces empty package for a service | Service not yet in HCL export scope | Check the product compatibility matrix; use `pingcli pingone api` as a fallback for raw export | +| Terraform provider missing a resource type | Resource not yet in provider support | Check the Ping Terraform provider changelog; use `pingcli pingone api` for a raw read in the interim | --- ## Related references -- `references/curated/cross-platform/ping-cli-basics.md` — Ping CLI install, profiles, CRUD, and Terraform export commands +- `references/curated/cross-platform/ping-cli-basics.md` — Ping CLI install, profiles, and CRUD commands - `references/curated/cross-platform/core-admin-patterns.md` — secret rotation, API patterns - `references/curated/pingone-mt/tenant-and-environment-setup.md` — environment setup prerequisites - `ping-orchestration` → `references/curated/cross-platform/journey-and-flow-promotion.md` — journey, script, and DaVinci flow promotion specifics @@ -189,5 +174,4 @@ For Ping's own guidance on model selection see the [configuration promotion over - [AIC self-service promotions](https://docs.pingidentity.com/pingoneaic/tenants/self-service-promotions.html) - [AIC promotion FAQ](https://docs.pingidentity.com/pingoneaic/tenants/self-service-promotions-faqs.html) - [AIC configuration placeholders (ESVs)](https://docs.pingidentity.com/pingoneaic/tenants/configuration-placeholders.html) -- [Ping CLI platform export](https://developer.pingidentity.com/pingcli/general/exporting-platform-configuration.html) - [Ping Terraform provider](https://terraform.pingidentity.com) diff --git a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md index 14df252..6ca6e8d 100644 --- a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md +++ b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md @@ -9,30 +9,30 @@ use_cases: ["workforce", "customer", "cross-platform"] doc_type: guide status: current canonical: true -last_updated: "2026-06-22" +last_updated: "2026-06-24" slug: "https://developer.pingidentity.com/pingcli/" --- # Ping CLI — Configuration Automation Basics -Scriptable, deterministic configuration management across PingOne, PingFederate, DaVinci, and the Ping universal services using the `pingcli` command-line tool. +Ping CLI (`pingcli`) is the unified open-source command-line tool for managing configuration across PingOne, PingFederate, DaVinci, and the Ping universal services. ## Scope -**Covers:** Install and first-run, configuration profile model, connecting Ping services, CRUD via per-product subcommands, `pingcli platform export` for Configuration-as-Code / Terraform HCL, `pingcli request` for unmodeled endpoints, CI/CD patterns, and the migration from the legacy `pingctl` tool. +**Covers:** Why to use Ping CLI, install and first-run, configuration profile model, connecting Ping services, CRUD via per-product subcommands (1.x), CI/CD patterns. -**Does NOT cover:** Interactive agent-driven config — use the PingOne MCP Server or DaVinci MCP Server for that. Long-term Terraform state management — see the PingOne and PingFederate Terraform providers at `developer.pingidentity.com/terraform/`. DaVinci flow design — see `ping-orchestration`. PingFederate console or federation configuration — see `references/curated/ping-software/pingfederate-basics.md`. Per-service policy semantics (Protect risk, Verify KYC) — see `ping-universal-services`. +**Does NOT cover:** `pingcli platform export` and `pingcli request` — these are 0.8 features not yet available in 1.x; see the [product compatibility matrix](https://developer.pingidentity.com/pingcli/latest/product-compatibility.html) for current 1.x feature availability. Interactive agent-driven config — use the PingOne MCP Server or DaVinci MCP Server. Long-term Terraform state management — see the PingOne and PingFederate Terraform providers. DaVinci flow design — see `ping-orchestration`. Per-service policy semantics — see `ping-universal-services`. --- -## What Ping CLI is +## Why Ping CLI -Ping CLI (`pingcli`) is the unified open-source CLI for managing configuration across PingOne, PingFederate, DaVinci, and the Ping universal services. It provides: +Ping CLI (`pingcli`) addresses the gap between the interactive admin console (good for humans, not scriptable) and raw REST API calls (scriptable, but require managing auth, base URLs, and retries manually). It provides: -- A consistent CRUD interface for admin operations without raw `curl` calls -- Multi-product Configuration-as-Code export (`pingcli platform export`) for Terraform integration -- Profile-based authentication so the same scripts run against dev, staging, and production -- Raw admin API access with managed auth for endpoints that don't yet have first-class commands +- **Consistent CRUD interface** across PingOne, DaVinci, PingFederate, and the Ping universal services without raw `curl` calls +- **Profile-based authentication** so the same scripts run against dev, staging, and production using different credentials per environment +- **Automatic auth and base URL injection** — no per-command token management +- **CI/CD friendly** — non-interactive auth via env vars, `--output-format json`, detailed exit codes For the current list of supported products and per-service CRUD availability, see the [product compatibility matrix](https://developer.pingidentity.com/pingcli/latest/product-compatibility.html). @@ -57,7 +57,7 @@ Verify: `pingcli version` Profiles are named groups of settings stored in `$HOME/.pingcli/config.yaml`. Use one profile per target environment (dev, staging, prod). -| Operation | Command (1.0) | +| Operation | Command | |---|---| | Create a profile | `pingcli config profiles create --name dev` | | Switch active profile | `pingcli config profiles use dev` | @@ -65,8 +65,6 @@ Profiles are named groups of settings stored in `$HOME/.pingcli/config.yaml`. Us | View active profile | `pingcli config view-profile` | | Delete a profile | `pingcli config profiles delete dev` | -> **Version note:** Ping CLI 0.8 used different subcommand names (`add-profile`, `set-active-profile`). If commands fail, verify your installed version with `pingcli version` and cross-check the [0.8 command reference](https://developer.pingidentity.com/pingcli/0.8/command_reference/pingcli_config.html) if needed. - --- ## Connecting Ping services @@ -102,51 +100,12 @@ pingcli davinci flows list --application-id # PingOne MFA — replace a device policy pingcli mfa device-policies replace -f policy.json - -# PingFederate — raw admin API call (GET /oauth/clients) -pingcli pingfederate api GET /oauth/clients ``` Universal-service connectors are accessible both at top level (`pingcli davinci ...`, `pingcli mfa ...`) and under the PingOne connector umbrella (`pingcli pingone davinci ...`). Both paths use the same PingOne Worker app credentials. --- -## `pingcli platform export` - -Exports multi-product configuration as Configuration-as-Code packages, optionally as Terraform HCL `import {}` blocks. - -```bash -# Export all connected products -pingcli platform export - -# Export only PingOne services -pingcli platform export --service-group pingone - -# Export as Terraform HCL (requires pingcli-plugin-terraformer) -pingcli platform export --format HCL -``` - -**Export availability per product:** Not all products produce HCL today. `pingone-platform`, `pingone-sso`, `pingone-mfa`, `pingone-protect`, `pingone-authorize`, and `pingfederate` are supported; `pingone-davinci`, `pingone-credentials`, and `pingone-verify` are listed but export support is partial. Always check the [product compatibility page](https://developer.pingidentity.com/pingcli/latest/product-compatibility.html) for the current status. - -**Terraformer plugin:** `pingcli-plugin-terraformer` (installed via `pingcli plugin add`) produces opinionated, ready-to-store HCL with post-processing suited for GitOps promotion pipelines. - ---- - -## Custom API requests - -For endpoints without a first-class subcommand, use the raw request interfaces. The CLI injects auth, base URL, and retry handling automatically. - -```bash -# Generic request (all products) -pingcli request GET /pingone/environments//applications - -# Product-specific wrappers (1.0) -pingcli pingone api GET /environments//applications -pingcli pingfederate api GET /oauth/clients -``` - ---- - ## CI/CD patterns ```bash @@ -160,11 +119,11 @@ export PINGCLI_PINGONE_REGION=com pingcli pingone applications list --output-format json # Detailed exit codes for conditional pipeline steps -pingcli -D platform export # Exit 0 = success; 1 = error; 2 = success with warnings +pingcli -D pingone environments list ``` -**Profile-per-environment promotion pattern:** Create one profile per environment (dev/staging/prod), each binding to a different Worker app. A promotion script switches profiles and runs the export or create commands. +**Profile-per-environment pattern:** Create one profile per environment (dev/staging/prod), each binding to a different Worker app. Scripts switch profiles to operate against the correct environment. --- @@ -173,7 +132,6 @@ pingcli -D platform export - PingOne: Worker application with the required admin roles; `clientId`, `clientSecret`, `environmentId`, and region. - PingFederate: Admin API OAuth client; admin base URL (HTTPS, port 9999 by default). - Network access from the CLI host to each product's admin API endpoint. -- For Terraform HCL export: `pingcli-plugin-terraformer` installed via `pingcli plugin add`. --- @@ -182,9 +140,8 @@ pingcli -D platform export | Variant | Notes | |---|---| | Single tenant, one profile | Default setup; one profile, one Worker app | -| Multi-environment promotion | One profile per env; promotion script switches profiles before export/create | +| Multi-environment scripting | One profile per env; scripts switch profiles before running commands | | Docker-only CI | Run `pingidentity/pingcli:latest` as a container step; pass credentials as env vars | -| Terraform GitOps | `pingcli platform export --format HCL` + Terraformer plugin + Terraform plan/apply in PR pipeline | | Migrating from `pingctl` | Re-configure profiles under `pingcli`; `pingctl` commands are not compatible | --- @@ -195,8 +152,6 @@ pingcli -D platform export |---|---|---| | 404 on environment lookup | Wrong region in profile | Verify region string matches the PingOne tenant domain (e.g., `eu` for `pingone.eu`) | | 403 on `applications create` | Worker app missing roles | Verify the Worker app has the required admin roles in the PingOne environment | -| 0.8 profile commands fail on 1.0 | Command names changed between versions | Run `pingcli version`; update scripts to use 1.0 command names (`profiles create`, not `add-profile`) | -| `platform export` returns empty package for a service | Service not yet supported for export | Check the product compatibility matrix; use `pingcli request` as fallback | | `pingcli init` wizard skips a service | Service credentials not configured | Re-run `pingcli config set` for the missing service manually | --- @@ -212,10 +167,8 @@ pingcli -D platform export ## Source -- [Ping CLI overview](https://developer.pingidentity.com/pingcli/) +- [Ping CLI overview and docs](https://developer.pingidentity.com/pingcli/) - [Install guide](https://developer.pingidentity.com/pingcli/latest/pingcli_landing_page.html) - [Product compatibility matrix](https://developer.pingidentity.com/pingcli/latest/product-compatibility.html) - [Command reference](https://developer.pingidentity.com/pingcli/latest/command_reference/pingcli.html) -- [Exporting platform configuration](https://developer.pingidentity.com/pingcli/general/exporting-platform-configuration.html) -- [Configuration promotion overview](https://developer.pingidentity.com/config-automation-promotion/configuration_promotion_landing_page.html) - [GitHub: pingidentity/pingcli](https://github.com/pingidentity/pingcli) diff --git a/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md b/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md index 0da5951..f64013d 100644 --- a/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md +++ b/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md @@ -21,7 +21,7 @@ Journey-, script-, and DaVinci-flow-specific concerns when promoting between AIC **Covers:** What journey and flow config moves; AIC ESV and script gotchas; DaVinci flow versioning and promotion variables; environment lock impact on running journeys; per-node promotion considerations; rollback. -**Does NOT cover:** General promotion model choice, tool selection, environment topology, and Terraform/CaC pipeline — see `ping-foundation` → `references/curated/cross-platform/config-promotion.md`. That anchor is the entry point; load this one only when the task involves journey- or flow-specific concerns. +**Does NOT cover:** General promotion model choice, environment topology, Terraform/CaC pipeline, and cross-product config promotion — see `ping-foundation` → `references/curated/cross-platform/config-promotion.md` for those. This anchor covers only the platform-native promotion mechanisms for journeys, flows, and their specific gotchas: AIC self-service promotions for journeys/scripts/themes, and PingOne native promotion for DaVinci flows and flow policies. --- @@ -177,7 +177,7 @@ If a promoted journey causes issues in the upper environment, AIC self-service r | AIC standard dev/staging/prod chain | Sequential pairs; ESVs pre-configured in each upper env | | AIC with UAT tier | dev → UAT → staging → production; cannot skip UAT | | DaVinci flow to a sandbox (test) | Supported in PingOne native promotion; sandbox counts as a valid target env | -| Terraform-managed journey baseline | Export with `pingcli platform export`; manage with Terraform; promote via PR + apply | +| Terraform-managed journey baseline | Manage with Ping Identity Terraform providers; promote via PR + apply | --- From 2555cf82f7d4874643c0fc48daf4abf1156bd22f Mon Sep 17 00:00:00 2001 From: "george.bafaloukas" Date: Wed, 24 Jun 2026 11:52:45 +0100 Subject: [PATCH 13/15] fix(ping-identity): correct 6 inaccuracies found during doc/Glean re-verification MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Verified against developer.pingidentity.com/pingcli/latest/ and terraform.pingidentity.com. ping-cli-basics.md: - pingcli config view-profile → pingcli config profiles show (correct 1.x path) - Region strings com/eu/asia/sg/ca → NA/EU/AP/AU/CA/SG (1.x regionCode enum values; old strings were root domain suffixes from 0.8 config model; also adds AU which was missing entirely) - pingcli davinci flows list --application-id → -e / --environment-id (correct flag) - pingcli mfa device-policies replace → pingcli mfa mfa-device-policies replace (subcommand has mfa- prefix in 1.x) config-promotion.md: - Remove PingAccess from Terraform provider claim in two places — PingAccess has no Terraform provider; correct: PingFederate and PingDirectory only (source: developer.pingidentity.com/terraform/) - Replace 'Ping CLI export' hard limits row with 'Terraform provider coverage' row — platform export is 0.8-only; the constraint in 1.x is Terraform provider resource coverage, not CLI export scope Co-Authored-By: Claude Sonnet 4.6 (1M context) --- .../references/curated/cross-platform/config-promotion.md | 6 +++--- .../references/curated/cross-platform/ping-cli-basics.md | 8 ++++---- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md index cd8ab3b..e4d0da2 100644 --- a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md +++ b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md @@ -54,7 +54,7 @@ How to move Ping Identity configuration between development, staging, and produc ### Ping Software (PingFederate, PingAccess, PingDirectory) - Configuration is managed via **server profiles** (Git-backed config-as-code). Promotion = merging and applying a server-profile branch. -- The Ping Identity Terraform providers cover PingFederate, PingAccess, and PingDirectory for state-managed config-as-code. +- The Ping Identity Terraform providers cover PingFederate and PingDirectory for state-managed config-as-code. PingAccess does not have a Terraform provider. --- @@ -96,7 +96,7 @@ Environment-specific values (connection endpoints, client IDs, URIs) must be ext | AIC | **Environment lock required** on source and target during promotion | Blocks ESV API and most admin APIs in the development environment; **authentication flows for end users are unaffected** | | AIC | Promotions take 10–45 minutes | Service restart in the upper environment is part of the process | | AIC | Rollback available via API only | Admin console does not expose rollback | -| Ping CLI export | Terraform HCL export scope varies by service | Not all services produce HCL; check the [product compatibility matrix](https://developer.pingidentity.com/pingcli/latest/product-compatibility.html) | +| Terraform provider coverage | Resource support varies by provider | Not all PingOne / PingFederate resources have Terraform provider support; check the [Ping Terraform provider docs](https://terraform.pingidentity.com) for current coverage | For current availability of specific resource types in native PingOne promotion, check the linked Ping documentation — this list changes as the feature evolves. @@ -120,7 +120,7 @@ For Ping's own guidance on model selection see the [configuration promotion over |---|---|---| | Config lives entirely within one PingOne org; team prefers admin-console workflow | PingOne native promotion | Designed for same-org, in-console use; automatic dependency management; no toolchain required | | AIC tenant with dev/staging/prod environments | AIC self-service promotions | The platform-provided self-service promotion path for AIC; sequential pairs enforced by the platform (dev→staging→production only) | -| Cross-product (PingOne + PingFederate/PingAccess), cross-org, or Git-backed audit trail needed | Ping CLI + Terraform | Terraform providers cover PingFederate, PingAccess, and PingDirectory; Ping CLI CRUD for PingFederate is still rolling out — check the [compatibility matrix](https://developer.pingidentity.com/pingcli/latest/product-compatibility.html); state tracking and drift detection via Terraform | +| Cross-product (PingOne + PingFederate), cross-org, or Git-backed audit trail needed | Ping CLI + Terraform | Terraform providers cover PingFederate and PingDirectory (no PingAccess provider); Ping CLI CRUD for PingFederate is still rolling out — check the [compatibility matrix](https://developer.pingidentity.com/pingcli/latest/product-compatibility.html); state tracking and drift detection via Terraform | | Mix of PingOne and AIC in the same pipeline | Can combine both | Native/AIC handles per-platform config; Terraform handles cross-product baseline and long-term state | | PingFederate configuration between servers | Server profiles (Git) + Terraform provider | PingFederate's native config-as-code model; no equivalent in-console promotion UI | diff --git a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md index 6ca6e8d..83afce1 100644 --- a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md +++ b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md @@ -62,7 +62,7 @@ Profiles are named groups of settings stored in `$HOME/.pingcli/config.yaml`. Us | Create a profile | `pingcli config profiles create --name dev` | | Switch active profile | `pingcli config profiles use dev` | | List profiles | `pingcli config profiles list` | -| View active profile | `pingcli config view-profile` | +| View active profile | `pingcli config profiles show` | | Delete a profile | `pingcli config profiles delete dev` | --- @@ -80,7 +80,7 @@ Before using product subcommands, configure the service credentials in the activ Use `pingcli init` for a guided first-run setup wizard. Configure manually with `pingcli config set`. -**Regions:** PingOne regions affect the base URL — ensure the profile uses the correct region string (`com`, `eu`, `asia`, `sg`, `ca`). A wrong region causes 404 on environment lookups. +**Regions:** PingOne regions affect the base URL — ensure the profile uses the correct region code (`NA`, `EU`, `AP`, `AU`, `CA`, `SG`). A wrong region causes 404 on environment lookups. --- @@ -96,10 +96,10 @@ pingcli pingone environments list pingcli pingone applications create -f app.json # DaVinci — list flows in an application -pingcli davinci flows list --application-id +pingcli davinci flows list -e # PingOne MFA — replace a device policy -pingcli mfa device-policies replace -f policy.json +pingcli mfa mfa-device-policies replace -f policy.json ``` Universal-service connectors are accessible both at top level (`pingcli davinci ...`, `pingcli mfa ...`) and under the PingOne connector umbrella (`pingcli pingone davinci ...`). Both paths use the same PingOne Worker app credentials. From b2b6f4a6adb8116eb0816d769374026438b1ae3c Mon Sep 17 00:00:00 2001 From: "george.bafaloukas" Date: Wed, 24 Jun 2026 12:17:59 +0100 Subject: [PATCH 14/15] fix(ping-identity): address Patrick's latest PR #8 review comments MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ping-cli-basics.md: - Scope: apply Patrick's exact suggestion — remove 0.8-specific callout, clean to 'Does NOT cover: Features below 1.x...' - Connecting Ping services: remove detailed credentials table — agent should not be responsible for connection config; replaced with pointer to official docs and a profile verification command - CI/CD: remove secret env var examples — agent should not handle secrets; kept JSON output and exit code examples, added docs pointer - Prerequisites: remove detailed credential fields; defer to official setup guide config-promotion.md: - Terraform provider row: apply Patrick's exact suggestion — 'Resource and data source support varies by provider' with pointer to terraform.pingidentity.com for available resources and data sources - Terraform rollback row: apply Patrick's exact suggestion — 'Revert to prior state file or prior apply' (remove terraform destroy) Co-Authored-By: Claude Sonnet 4.6 (1M context) --- .../cross-platform/config-promotion.md | 4 +-- .../curated/cross-platform/ping-cli-basics.md | 30 ++++++------------- 2 files changed, 11 insertions(+), 23 deletions(-) diff --git a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md index e4d0da2..6543ee2 100644 --- a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md +++ b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md @@ -96,7 +96,7 @@ Environment-specific values (connection endpoints, client IDs, URIs) must be ext | AIC | **Environment lock required** on source and target during promotion | Blocks ESV API and most admin APIs in the development environment; **authentication flows for end users are unaffected** | | AIC | Promotions take 10–45 minutes | Service restart in the upper environment is part of the process | | AIC | Rollback available via API only | Admin console does not expose rollback | -| Terraform provider coverage | Resource support varies by provider | Not all PingOne / PingFederate resources have Terraform provider support; check the [Ping Terraform provider docs](https://terraform.pingidentity.com) for current coverage | +| Terraform provider coverage | Resource and data source support varies by provider | Check the [Ping Terraform provider docs](https://terraform.pingidentity.com) for available resources and data sources | For current availability of specific resource types in native PingOne promotion, check the linked Ping documentation — this list changes as the feature evolves. @@ -108,7 +108,7 @@ For current availability of specific resource types in native PingOne promotion, |---|---|---| | PingOne native | Restores the target environment to its state before the most recent promotion | Admin console → Promote, or Configuration Management API | | AIC | Restores the upper environment's prior static config set | API only (`POST /promotions/{id}/rollback`) | -| Terraform | `terraform destroy` + revert to prior state file or prior `apply` | Standard Terraform rollback — revert the commit and re-apply | +| Terraform | Revert to prior state file or prior `apply` | Standard Terraform rollback — revert the commit and re-apply | --- diff --git a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md index 83afce1..e7dae3a 100644 --- a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md +++ b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/ping-cli-basics.md @@ -21,7 +21,7 @@ Ping CLI (`pingcli`) is the unified open-source command-line tool for managing c **Covers:** Why to use Ping CLI, install and first-run, configuration profile model, connecting Ping services, CRUD via per-product subcommands (1.x), CI/CD patterns. -**Does NOT cover:** `pingcli platform export` and `pingcli request` — these are 0.8 features not yet available in 1.x; see the [product compatibility matrix](https://developer.pingidentity.com/pingcli/latest/product-compatibility.html) for current 1.x feature availability. Interactive agent-driven config — use the PingOne MCP Server or DaVinci MCP Server. Long-term Terraform state management — see the PingOne and PingFederate Terraform providers. DaVinci flow design — see `ping-orchestration`. Per-service policy semantics — see `ping-universal-services`. +**Does NOT cover:** Features below 1.x. Interactive agent-driven config. Long-term Terraform state management — see the PingOne and PingFederate Terraform providers. DaVinci flow design — see `ping-orchestration`. Per-service policy semantics — see `ping-universal-services`. --- @@ -69,18 +69,11 @@ Profiles are named groups of settings stored in `$HOME/.pingcli/config.yaml`. Us ## Connecting Ping services -Before using product subcommands, configure the service credentials in the active profile: +Configure Ping CLI connections according to the [official documentation](https://developer.pingidentity.com/pingcli/latest/pingcli_landing_page.html). Once configured, verify connectivity: -| Service | Prerequisites | Key config fields | -|---|---|---| -| PingOne | Worker application (client credentials) | `clientId`, `clientSecret`, `environmentId`, `region` | -| PingFederate | Admin API OAuth client | `baseURL`, `clientId`, `clientSecret` | -| DaVinci | Same Worker app as PingOne | Shares PingOne credentials | -| Universal services (MFA, Protect, Verify, Authorize, Credentials) | Same Worker app as PingOne | Share PingOne credentials via PingOne connector | - -Use `pingcli init` for a guided first-run setup wizard. Configure manually with `pingcli config set`. - -**Regions:** PingOne regions affect the base URL — ensure the profile uses the correct region code (`NA`, `EU`, `AP`, `AU`, `CA`, `SG`). A wrong region causes 404 on environment lookups. +```bash +pingcli config profiles show +``` --- @@ -108,13 +101,9 @@ Universal-service connectors are accessible both at top level (`pingcli davinci ## CI/CD patterns -```bash -# Non-interactive auth (client credentials — no browser prompt) -export PINGCLI_PINGONE_CLIENT_ID=... -export PINGCLI_PINGONE_CLIENT_SECRET=... -export PINGCLI_PINGONE_ENVIRONMENT_ID=... -export PINGCLI_PINGONE_REGION=com +Ping CLI is well-suited for CI/CD pipelines. Configure credentials according to the [official documentation](https://developer.pingidentity.com/pingcli/latest/pingcli_landing_page.html) — do not store secrets in skill instructions. +```bash # JSON output for pipeline parsing pingcli pingone applications list --output-format json @@ -129,9 +118,8 @@ pingcli -D pingone environments list ## Prerequisites -- PingOne: Worker application with the required admin roles; `clientId`, `clientSecret`, `environmentId`, and region. -- PingFederate: Admin API OAuth client; admin base URL (HTTPS, port 9999 by default). -- Network access from the CLI host to each product's admin API endpoint. +- Ping CLI installed and authenticated — follow the [official setup guide](https://developer.pingidentity.com/pingcli/latest/pingcli_landing_page.html) +- Network access from the CLI host to each product's admin API endpoint --- From 0c0cc1f584f658e830354396c9535ea1f90d2bcc Mon Sep 17 00:00:00 2001 From: "george.bafaloukas" Date: Wed, 24 Jun 2026 12:23:18 +0100 Subject: [PATCH 15/15] fix(ping-identity): four doc-verified inaccuracies found in final re-verification MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit All four fixes backed by verbatim doc quotes from docs.pingidentity.com. 1. config-promotion.md (×2): PingOne native promotion excludes four services, not three — PingOne Recognize was missing. Added to both the three-models table and the 'What promotes vs what does not' table. Source: ea-p1_promote.html lists exactly four excluded services. 2. journey-and-flow-promotion.md: Terraform Typical fit row incorrectly listed PingAccess as covered by a Terraform provider. PingAccess has no provider. Consistent with config-promotion.md which already stated this correctly. Source: developer.pingidentity.com/terraform/ — PingAccess not listed. 3. config-promotion.md: Promotion variables row said target values are 'assigned in the target before applying' — incorrect. Target values are specified at variable creation time in the source environment. Source: ea-p1_create_promotion_variable.html: 'Variables are always created and configured in the source environment.' 4. journey-and-flow-promotion.md: ESV lock row said 'Blocked in the development environment during lock' — incomplete. AIC locks both source AND target. Source: AIC promotions page: 'ESV API access in both locked environments.' Co-Authored-By: Claude Sonnet 4.6 (1M context) --- .../references/curated/cross-platform/config-promotion.md | 6 +++--- .../curated/cross-platform/journey-and-flow-promotion.md | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md index 6543ee2..79036c3 100644 --- a/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md +++ b/plugins/ping-identity/skills/ping-foundation/references/curated/cross-platform/config-promotion.md @@ -29,7 +29,7 @@ How to move Ping Identity configuration between development, staging, and produc | Model | Applies to | What moves | What does not move | Sequential constraint | |---|---|---|---|---| -| **PingOne native promotion** | PingOne (multi-tenant cloud) | Applications, DaVinci flows and policies, sign-on policies, and most PingOne resources | Authorize, Credentials, Privilege, runtime user data, sessions, audit logs | Source/target same org; check live docs for current resource scope | +| **PingOne native promotion** | PingOne (multi-tenant cloud) | Applications, DaVinci flows and policies, sign-on policies, and most PingOne resources | Authorize, Credentials, Privilege, Recognize, runtime user data, sessions, audit logs | Source/target same org; check live docs for current resource scope | | **AIC self-service promotions** | PingOne Advanced Identity Cloud | Journeys, scripts, themes, AM/IDM static config, ESV references | Live users, sessions, user-created applications, runtime data | Sequential pairs only: dev→staging, staging→production. Non-sequential promotion not supported. | | **Ping CLI + Terraform (config-as-code)** | PingOne, PingFederate, DaVinci, and supported universal services | Terraform-managed config via Ping Identity Terraform providers | Per-resource, determined by provider support | None — Terraform manages state independently per target environment | @@ -70,7 +70,7 @@ How to move Ping Identity configuration between development, staging, and produc | ESV / environment variables | Promotion variables only | ESV references move; secrets must be pre-configured in target | Via Terraform provider variables | | Users, sessions, audit logs | ✗ never | ✗ never | ✗ never | | Runtime user data (devices, MFA enrollments) | ✗ never | ✗ never | ✗ never | -| PingOne Authorize, Credentials, Privilege | ✗ excluded | n/a | ✓ (where provider support exists) | +| PingOne Authorize, Credentials, Privilege, Recognize | ✗ excluded | n/a | ✓ (where provider support exists) | --- @@ -80,7 +80,7 @@ Environment-specific values (connection endpoints, client IDs, URIs) must be ext | Platform | Mechanism | Key constraint | |---|---|---| -| PingOne native | **Promotion variables** — named substitution tokens in the exported config | Defined in the source; must be assigned values in the target before applying | +| PingOne native | **Promotion variables** — named substitution tokens in the exported config | Created in the source environment; target environment values are specified at creation time in the source | | AIC | **Environment secrets and variables (ESVs)** | ESVs referenced in static config must exist in the upper environment. AIC's integrity check blocks promotion if any ESV is missing or if an encrypted secret is embedded directly in config rather than referenced via an ESV. | | Terraform | **Terraform input variables / `.tfvars` files per environment** | Standard Terraform pattern; per-environment variable files hold the target-specific values | diff --git a/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md b/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md index f64013d..41d9fe2 100644 --- a/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md +++ b/plugins/ping-identity/skills/ping-orchestration/references/curated/cross-platform/journey-and-flow-promotion.md @@ -104,7 +104,7 @@ AIC requires an **environment lock** on both source and target during a promotio |---|---| | End-user authentication flows | **Unaffected** — runtime auth continues | | AIC admin console | Read-only; most writes blocked in the source (dev) environment | -| ESV API | Blocked in the development environment during lock | +| ESV API | Blocked in both locked environments (source and target) during promotion | | Journey editing (AIC MCP Server, admin console) | Blocked in source during lock | | Promotion duration | 10–45 minutes depending on config size | @@ -156,7 +156,7 @@ If a promoted journey causes issues in the upper environment, AIC self-service r |---|---|---| | AIC journey iteration within one tenant chain | AIC self-service promotions | Platform-provided self-service path for AIC; admin-console-driven; sequential pairs enforced by the platform (dev→staging→production only) | | DaVinci flow changes within one PingOne org | PingOne native promotion | In-console; automatic dependency management; same-org constraint applies | -| Multi-org, multi-cloud, or Git-backed audit trail needed | Ping CLI + Terraform | Terraform providers span PingFederate, PingAccess, PingDirectory, and PingOne; Ping CLI CRUD for PingFederate is still rolling out — check the [compatibility matrix](https://developer.pingidentity.com/pingcli/latest/product-compatibility.html); state tracking and drift detection via Terraform | +| Multi-org, multi-cloud, or Git-backed audit trail needed | Ping CLI + Terraform | Terraform providers cover PingFederate, PingDirectory, and PingOne (no PingAccess provider); Ping CLI CRUD for PingFederate is still rolling out — check the [compatibility matrix](https://developer.pingidentity.com/pingcli/latest/product-compatibility.html); state tracking and drift detection via Terraform | | Mixed AIC journeys + DaVinci flows in the same pipeline | Can combine both | Each platform's native model handles its own config; Terraform manages cross-product baseline | ---