fix(docs): correct Jenkins external-CI example payload and token request - #809
Open
kaviththiranga wants to merge 5 commits into
Open
fix(docs): correct Jenkins external-CI example payload and token request#809kaviththiranga wants to merge 5 commits into
kaviththiranga wants to merge 5 commits into
Conversation
Contributor
📝 WalkthroughSummary by CodeRabbit
WalkthroughThe external CI documentation updates token requests, Jenkins prerequisites, Workload deployment methods, error handling, and Jenkins job naming. It also updates the external CI setup guide and troubleshooting commands. ChangesExternal CI workflow
Estimated code review effort: 3 (Moderate) | ~20 minutes Sequence Diagram(s)sequenceDiagram
participant Jenkins
participant ThunderID
participant WorkloadAPI
Jenkins->>ThunderID: Request token with URL-encoded credentials
ThunderID-->>Jenkins: Return access token
Jenkins->>WorkloadAPI: Create or apply Workload CR
WorkloadAPI-->>Jenkins: Return success, conflict, or error details
Jenkins->>WorkloadAPI: Update Workload CR after conflict
WorkloadAPI-->>Jenkins: Return deployment response
Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Signed-off-by: Kavith Lokuhewage <kaviththiranga@gmail.com>
kaviththiranga
force-pushed
the
fix/external-ci-jenkins-example
branch
from
August 4, 2026 23:53
098e32b to
b1f1ed7
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/platform-engineer-guide/workflows/external-ci.mdx`:
- Around line 176-181: Update the PUT fallback in the external CI workflow
around the curl request to capture both its HTTP status and response body
instead of relying on curl -sf. Apply the same explicit non-2xx validation used
by the POST request, preserving the response body for error reporting and
ensuring all non-2xx PUT responses are reported.
- Around line 72-74: Update both OAuth token request examples in
docs/platform-engineer-guide/workflows/external-ci.mdx (lines 72-74 and 151-153)
to use curl’s --data-urlencode for every form field, including grant_type,
client_id, and client_secret, instead of raw -d values.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 28b6fd83-3f66-4285-aed2-231c1c6eda70
⛔ Files ignored due to path filters (1)
versioned_docs/version-v1.2.x/platform-engineer-guide/workflows/external-ci.mdxis excluded by!versioned_docs/**
📒 Files selected for processing (1)
docs/platform-engineer-guide/workflows/external-ci.mdx
Contributor
|
Note GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer. |
- url-encode OAuth form values - check the PUT fallback status, not just curl -sf - note the jq prerequisite and that jenkins/jenkins:lts lacks it - set +x so the bearer token is not echoed into the build log Signed-off-by: Kavith Lokuhewage <kaviththiranga@gmail.com>
kaviththiranga
force-pushed
the
fix/external-ci-jenkins-example
branch
from
August 5, 2026 02:49
3117d78 to
06d9285
Compare
The documented /job/my-org/job/my-service is a URL path; the plugin expects a job full name and inserts the /job/ segments itself. Signed-off-by: Kavith Lokuhewage <kaviththiranga@gmail.com>
Contributor
|
Note GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer. |
Signed-off-by: Kavith Lokuhewage <kaviththiranga@gmail.com>
kaviththiranga
force-pushed
the
fix/external-ci-jenkins-example
branch
from
August 5, 2026 04:57
e10287e to
a0d2cd1
Compare
Contributor
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/platform-engineer-guide/workflows/external-ci.mdx (1)
171-175: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winFail when token acquisition fails.
The pipeline returns the
jqstatus, not thecurlstatus. Ifcurlfails before it returns JSON,jqcan succeed with no input and assign an emptyTOKEN. The pipeline then reports a Workload API error instead of the token request failure.Capture the token response before parsing it. Require a non-empty
.access_token.Proposed fix
- TOKEN=$(curl -sf -X POST "${THUNDER_URL}/oauth2/token" \ + if ! TOKEN_RESPONSE=$(curl -sf -X POST "${THUNDER_URL}/oauth2/token" \ --data-urlencode "grant_type=client_credentials" \ --data-urlencode "client_id=${CLIENT_ID}" \ - --data-urlencode "client_secret=${CLIENT_SECRET}" \ - | jq -r '.access_token') + --data-urlencode "client_secret=${CLIENT_SECRET}"); then + echo "Token request failed" + exit 1 + fi + + if ! TOKEN=$(printf '%s' "${TOKEN_RESPONSE}" | jq -er '.access_token'); then + echo "Token response has no access token" + exit 1 + fi🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/platform-engineer-guide/workflows/external-ci.mdx` around lines 171 - 175, Update the token acquisition block for TOKEN to capture the curl response separately before passing it to jq, so curl failures propagate instead of being masked by the pipeline. Parse the captured response and validate that .access_token is non-empty, failing the workflow immediately when the request fails or no token is returned.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@docs/platform-engineer-guide/workflows/external-ci.mdx`:
- Around line 171-175: Update the token acquisition block for TOKEN to capture
the curl response separately before passing it to jq, so curl failures propagate
instead of being masked by the pipeline. Parse the captured response and
validate that .access_token is non-empty, failing the workflow immediately when
the request fails or no token is returned.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 2127650e-5494-41ac-8d6d-322353fbfa40
⛔ Files ignored due to path filters (1)
versioned_docs/version-v1.2.x/platform-engineer-guide/workflows/external-ci.mdxis excluded by!versioned_docs/**
📒 Files selected for processing (1)
docs/platform-engineer-guide/workflows/external-ci.mdx
Signed-off-by: Kavith Lokuhewage <kaviththiranga@gmail.com>
kaviththiranga
force-pushed
the
fix/external-ci-jenkins-example
branch
from
August 5, 2026 07:24
cd7359a to
41a9e52
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
1. Wrong Workload payload (Step 3, Jenkins)
The example posts:
The Workload schema requires
metadata.nameplusspec.owner{projectName, componentName}andspec.container.image. Posting the documented body returns:The GitHub Actions example immediately below it on the same page already uses the
correct shape — only the Jenkins block was wrong.
2. No 409 handling (Step 3, Jenkins)
The example uses
curl -sfwith a bare POST and no fallback. The first buildcreates the Workload; every subsequent build gets HTTP 409,
curl -sfexitsnon-zero, and the stage fails. Since Jenkins jobs re-run constantly this is the
first thing a real user hits. The GitHub Actions example already handles it; this
change brings the Jenkins one in line.
3. Token request uses HTTP Basic (Step 1)
The verification snippet passes credentials with
curl -u. Backend Serviceapplications are registered with
token_endpoint_auth_method: client_secret_post,so that request fails:
Changed to form parameters (
--data-urlencode) and added a note explaining why.A
set +xguard was also added to the Jenkins example: Jenkins masks injectedcredentials in the build log but not the bearer token derived from them.
4. Wrong
jenkins.io/job-full-nameannotation format (Step 4)The guide told users to set the annotation to a URL path
(
/job/my-org/job/my-service). The Backstage plugin expects the job fullname (
my-org/my-service) and inserts the/job/segments itself, so thedocumented value resolves to a folder literally named
joband the Jenkins tab404s. Fixed here and in the developer guide's CI overview.
5. New:
occCLI alternative for the registration stepAdded a short "Using the OpenChoreo CLI instead of curl" subsection after the
Jenkins example.
occ login --client-credentials+occ workload create+occ applyperforms the same registration with nojq, no 409 fallback, and noset +x(the CLI reads credentials from env vars and never prints the token).The subsection also covers the things to watch: pin the CLI version to the
OpenChoreo release, point
HOMEat the per-build workspace becauseocc loginstores the client secret in
~/.openchoreo/config, and keep endpoints in theworkload.yamldescriptor sinceocc applyreplaces the whole spec.