analyzing-release-readiness

Release Readiness Review

AgentSpace routing (SigV4 only): If list_agent_spaces is available in your tool list and the multi-space orchestration skill has NOT been invoked yet this session, invoke it first to determine which agent_space_id to use. Then pass agent_space_id on all tool calls below. For bearer token auth this is unnecessary — the token is already scoped to one space.

Run a release readiness review via the AWS DevOps Agent. Analyzes a code change for risk, correctness, and potential rollback issues. Returns a structured report with actionable findings.

Rules:

• If a PR/MR URL is provided: Extract ALL fields from the URL. Do NOT inspect the local workspace or git state.
• NEVER use gh CLI, glab CLI, or any external tool to fetch PR/MR details. All required fields (repository, prNumber/mergeRequestIid, hostname) MUST be parsed directly from the URL or user input. The DevOps Agent fetches the content itself — you only need to pass identifiers.
• Only use the local workspace flows when the user references a repository or package without a PR/MR link.

Gathering execution parameters

Infer everything automatically from the user's request — do not ask for parameters that can be derived.

Input source decision tree:

Has the user provided a pull request/merge request link or ID?
├── Yes: github.com PR URL               → use "GitHub PR" flow below
├── Yes: gitlab.com MR URL               → use "GitLab MR" flow below
└── No link provided — repo name only    → use "Local GitHub/GitLab repo" flow below

GitHub PR (github.com URL or PR reference)

• Parse the input to extract fields — do NOT attempt a web fetch unless fields cannot be determined from the input.
• repository (required): owner/repo from the PR URL
• At least one of the following is required: headSha (commit SHA), headBranch (branch name), prNumber (PR number as a string, e.g. "8" not 8)
• hostname: Extract from the URL (e.g., github.com or a self-hosted hostname)
• Pass these fields to create_release_readiness_review under content.githubPrContent as an array of objects (even for a single PR).

Example:

{
  "content": {
    "githubPrContent": [
      {

Critical format rules: githubPrContent MUST be an array (not a single object). prNumber MUST be a string (not an integer).

GitLab MR (gitlab.com URL)

• Parse the input to extract fields — do NOT attempt a web fetch unless fields cannot be determined from the input.
• repository (required): owner/repo from the MR URL
• At least one of the following is required: headSha (commit SHA), headBranch (branch name), mergeRequestIid (MR number as a string, e.g. "1" not 1)
• hostname: Extract from the URL (e.g., gitlab.com or a self-hosted hostname)
• Pass these fields to create_release_readiness_review under content.gitlabMrContent as an array of objects (even for a single MR).

Example:

Critical format rules: gitlabMrContent MUST be an array (not a single object). mergeRequestIid MUST be a string (not an integer). Violating either causes immediate task failure with no journal records.

Local GitHub/GitLab repo (no PR/MR URL provided — local workspace ONLY)

MANDATORY: When the user references a repository or branch without a PR/MR link, you MUST execute every step below in order. Do NOT shortcut by grabbing the remote URL and SHA directly — the review agent needs a pushed branch to read from. Skipping the push step will cause the analysis to fail or produce incomplete results.

1. Navigate to the repository directory: cd to the repo root (e.g., the clone directory). Ask the user if needed.

2. Determine the base branch: Use main unless the user specifies a different branch. Verify the remote tracking branch exists:

   BASE_BRANCH="main"
   if ! git show-ref --verify --quiet refs/remotes/origin/$BASE_BRANCH; then
       git fetch origin $BASE_BRANCH
   fi

   If the fetch fails (e.g., "couldn't find remote ref"), ask the user to specify the base branch and stop.

3. Check for local changes: Run git status --short and git rev-list --count origin/$BASE_BRANCH..HEAD to determine the state and communicate accordingly:

   • Clean AND not ahead: Inform the user there's nothing new to analyze and stop.

   • Has uncommitted changes (with or without unpushed commits):

     • If there are one or more unpushed commits (rev-list count >= 1), tell the user:

       "You have uncommitted changes and N unpushed commits. I'll commit your uncommitted changes on top, then push all N+1 commits to a new branch for analysis. All changes will appear as a single diff against the base branch. Shall I proceed?"

     • If there are no other unpushed commits (rev-list count = 0), tell the user:

       "I'll commit your uncommitted changes and push them to a new branch for release readiness review. Shall I proceed?"

     • Do NOT proceed until the user approves. If they decline, stop.

   • Clean but ahead of remote (rev-list count > 0, no uncommitted changes):

     • If ahead by more than 1 commit, tell the user:

       "You have N unpushed commits. I'll push all of them to a new branch for analysis. All changes will appear as a single diff against the base branch. Shall I proceed?"

     • If ahead by exactly 1 commit, tell the user:

       "I'll push your latest commit to a new branch for release readiness review. Shall I proceed?"

     • Do NOT proceed until the user approves. If they decline, stop.

4. Stash uncommitted changes (skip this step if working directory is clean):

   git stash push --include-untracked -m "release-analysis: preserve working changes"

5. Create review branch (do this BEFORE committing so the snapshot commit only lives on the disposable branch):

   ORIGINAL_BRANCH=$(git rev-parse --abbrev-ref HEAD)
   BRANCH_NAME="feat/release-readiness-review"
   git checkout -b $BRANCH_NAME 2>/dev/null || { BRANCH_NAME="feat/release-readiness-review-$(date +%Y%m%d-%H%M%S)"; git checkout -b $BRANCH_NAME; }

6. Apply stashed changes and commit on the review branch (skip this step if working directory was clean — go straight to step 7):

   git stash apply

   Before staging, check for sensitive files:

   git status --short | grep -iE '\.(env|pem|key|p12|pfx|credentials|secret)'

   If sensitive files are detected, warn the user and ask for confirmation before proceeding. If the user declines, abort:

   git checkout $ORIGINAL_BRANCH && git branch -D $BRANCH_NAME && git stash drop

   Once confirmed (or no sensitive files found):

   git add -A
   git commit -m "chore: snapshot for release readiness review"

7. Push all unpushed commits (requires prior user approval): If the user already approved the push in step 3, proceed directly. Otherwise (e.g., the flow reached here without an explicit approval prompt), confirm before pushing:

   "I'm about to push branch $BRANCH_NAME to origin. This is a prerequisite step, can I proceed?" Do NOT push until the user approves. If they decline, abort and skip to step 11.

   Once approved (or if already approved in step 3):

   git push -u origin HEAD

8. Determine the repository identifier and hostname: Run git remote get-url origin | sed 's|://[^@]*@|://|' to extract the owner/repo and hostname.

   • GitHub URLs (github.com or self-hosted) → use githubPrContent, hostname from URL
   • GitLab URLs (gitlab.com or self-hosted) → use gitlabMrContent, hostname from URL

9. Build the content: Set headBranch to $BRANCH_NAME, repository to the extracted owner/repo, and hostname to the value from step 8. Wrap the object in an array:

   • GitHub: {"githubPrContent": [{"repository": "owner/repo", "headBranch": "feat/release-readiness-review", "hostname": "github.com"}]}
   • GitLab: {"gitlabMrContent": [{"repository": "namespace/repo", "headBranch": "feat/release-readiness-review", "hostname": "gitlab.com"}]}

10. Inform the user: Tell them which branch was created and pushed, then proceed with the core workflow below.

11. After analysis completes: Clean up and restore working state:

    git checkout $ORIGINAL_BRANCH
    git push origin --delete $BRANCH_NAME 2>/dev/null || true
    git branch -D $BRANCH_NAME 2>/dev/null || true

    If step 4 was executed (uncommitted changes were stashed), also run:

    git stash pop

Important: Do NOT create a PR/MR — only push the branch. The release readiness review agent will read the branch directly.

Core workflow

STRICT SEQUENCING: Steps below are numbered. You MUST complete each step before moving to the next. In particular, step 1 (automated testing prompt) MUST NOT happen until the entire "Gathering execution parameters" flow above is fully complete — all git operations done, branch pushed (if local flow), content object built, and user informed of the branch. Only THEN proceed to step 1.

1. Determine skip_automated_testing (ask ONLY after content is ready)

The skip_automated_testing parameter controls whether the agent runs automated testing (automated verification tests) or only static analysis.

Present the choice and wait for a response:

"Would you like a quick static analysis (code review, risk assessment, dependency checks), or a full analysis that also includes automated testing? Automated testing spins up a testing environment, builds your code, and runs automated verification tests — it's more thorough but takes longer."

Do NOT proceed until the user answers.

• If the user says "yes" / "include testing" / "full analysis" / "run tests" → use skip_automated_testing=false
• If the user says "no" / "static only" / "skip testing" / "quick" / declines → use skip_automated_testing=true
• If the response is ambiguous (e.g., "go ahead", "sure", "proceed") → ask the user to clarify which option they prefer.

2. Check tool availability

Verify that the following tools are available: aws_devops_agent__create_release_readiness_review, aws_devops_agent__get_task, aws_devops_agent__list_journal_records, aws_devops_agent__get_release_readiness_report. These tools are NOT deferred/lazy-loaded — if they do not appear in your tool list, they are unavailable. Do NOT search for them via ToolSearch. If any are missing, skip the remaining steps in this section and use the "Fallback (aws-mcp)" path below instead. Tell the user: "Remote server unavailable — using direct aws-mcp server fallback."

3. Start the Job

aws_devops_agent__create_release_readiness_review(
    content={...},
    skip_automated_testing=true/false
)
→ {"taskId": "...", "executionId": "...", "status": "started"}

Record the taskId and executionId from the response.

4. Poll for Status

Call aws_devops_agent__get_task(task_id=TASK_ID) every 30 seconds until the status transitions to IN_PROGRESS or a terminal state (COMPLETED, FAILED, CANCELED, TIMED_OUT).

5. Monitor Until Completion

Once IN_PROGRESS, poll for progress in a loop:

1. Call aws_devops_agent__list_journal_records(execution_id=EXEC_ID, order="ASC") to fetch new findings.
2. Present each record to the user with a friendly progress update.
3. Use next_token from the response to fetch only new records on subsequent polls.
4. Wait 15 seconds between each poll iteration.
5. Check aws_devops_agent__get_task(task_id=TASK_ID) periodically — stop when terminal status.

6. Present Results

Once the job reaches a terminal status:

• If COMPLETED:

  1. Call aws_devops_agent__get_release_readiness_report(execution_id=EXEC_ID) to retrieve the full report.

  2. Write the report contents to a markdown file:

     release-readiness-review-<YYYY-MM-DD-HHmmss>.md

  3. Inform the user that the report was saved, including the file path.

  4. Auto-fix flow (MANDATORY): After saving the report, you MUST attempt to generate and present fixes for all actionable risks — this is the primary value of the review workflow, not an optional step.

     • First, locate the analyzed repository in the current workspace:
       1. Run ls to list available directories in the workspace.
       2. Match by repo name (the last segment of owner/repo or namespace/repo). For example, testgroupadthiru/repo1updated → look for a directory named repo1updated.
       3. If a single match is found, confirm with the user: "I found <match> — is this the correct local copy of <namespace/repo>?"
       4. If multiple matches are found, ask the user which one is correct.
       5. If no obvious match exists, ask the user: "I couldn't find a local directory matching <repo-name>. Is it available locally under a different name, or should I just show the suggested fixes?"
     • If found locally:

       • Verify branch: Run git -C <repo-directory> branch --show-current to confirm you're on the expected branch. If not on the expected branch, check out the correct one before proceeding.

       • Scan the relevant code, interpret the risks/issues from the report. Then tell the user:

         "The report identified N actionable issues. I can generate the fixes in your local repository, and push them to a new branch feat/release-readiness-fix. Shall I proceed?"

       • Do NOT proceed until the user approves. If they decline, stop.

       • Once approved, generate the fixes. Then:

         cd <repo-directory>
         git checkout -b feat/release-readiness-fix 2>/dev/null || { git checkout -b "feat/release-readiness-fix-$(date +%Y%m%d-%H%M%S)"; }
         # Apply the fixes
         git add -A
         git commit -m "fix: Address issues identified by release readiness review"

       • Before pushing, verify branch again: Run git branch --show-current and confirm it shows feat/release-readiness-fix*. Do NOT push if you're on any other branch.

         git push -u origin HEAD

         Inform the user: which issues were fixed, what branch was created, and that the fix has been pushed.

     • If NOT found locally: Present the suggested fixes from the report as concrete, ready-to-apply code patches. Use the suggestedFix field from each risk. Format them as code blocks the user can copy-paste directly. Walk through each actionable risk: explain the issue, show the exact fix, and state which file/line it targets.
     • If the report finds no risks or issues: Inform the user the analysis completed with no actionable findings.
• If FAILED or TIMED_OUT: Present the error information and suggest next steps.
• If CANCELED: Inform the user the job was canceled and no report is available.

Cancelling a job

aws_devops_agent__cancel_release_readiness_review(task_id=TASK_ID)

Error handling

1. If FAILED or TIMED_OUT — stop and present the error. If the job failed quickly (within the first poll or two), call aws_devops_agent__list_associations() to check whether the target repository's hosting service (GitHub/GitLab hostname) is associated with the agent space.
2. If job does not reach IN_PROGRESS within 5 minutes — cancel with cancel_release_readiness_review.
3. If throttled (429 or ThrottlingException) — wait 30 seconds, retry up to 3 times.
4. If the error does not match any known pattern above, present the raw error output to the user.

Fallback (aws-mcp)

If the aws-devops-agent remote server is unavailable, use the AWS CLI directly:

Tell the user: "Remote server unavailable — using the aws-mcp server fallback."

1. Select Agent Space

List available agent spaces:

aws devops-agent list-agent-spaces --region us-east-1

Present the list to the user and ask which agent space they'd like to use. Do NOT proceed until the user has selected one. Use the selected agentSpaceId as SPACE_ID in all subsequent calls.

2. Start the Job

aws devops-agent create-backlog-task \
  --agent-space-id SPACE_ID \
  --task-type RELEASE_READINESS_REVIEW \
  --title 'Release Readiness Review' \
  --priority MEDIUM \
  --description '{\"agentInput\": {\"content\": <CONTENT_JSON>, \"metadata\": {\"skipAutomatedTesting\": true}}}' \
  --region us-east-1

CRITICAL: The content value must be a single object — NOT wrapped in a list. Correct: "content": {"githubPrContent": [...]}. Incorrect: "content": [{"githubPrContent": [...]}]. Wrapping in a list causes a Pydantic validation failure on the backend. The values in the content should all be of string format e.g. the PR number should be a string.

Default is "skipAutomatedTesting": true (static only). Set to false only if user explicitly opted into automated testing.

3. Poll for Status

aws devops-agent get-backlog-task \
  --agent-space-id SPACE_ID \
  --task-id TASK_ID \
  --region us-east-1

Poll every 30 seconds until the status transitions to IN_PROGRESS or a terminal state (COMPLETED, FAILED, CANCELED, TIMED_OUT).

4. Monitor Until Completion

Once IN_PROGRESS, poll for progress in a loop:

aws devops-agent list-journal-records \
  --agent-space-id SPACE_ID \
  --execution-id EXEC_ID \
  --order ASC \
  --region us-east-1

1. Present each record to the user with a friendly progress update.
2. Use next_token from the response to fetch only new records on subsequent polls.
3. Wait 15 seconds between each poll iteration.
4. Check get-backlog-task periodically — stop when terminal status.

5. Present Results

Once the job reaches a terminal status:

• If COMPLETED:

  1. Retrieve the report:

     aws devops-agent list-journal-records \
       --agent-space-id SPACE_ID \
       --execution-id EXEC_ID \
       --record-type release_analysis_report \
       --order ASC \
       --region us-east-1

  2. Write the report contents to a markdown file:

     release-readiness-review-<YYYY-MM-DD-HHmmss>.md

  3. Inform the user that the report was saved, including the file path.

  4. Auto-fix flow (MANDATORY): After saving the report, you MUST attempt to generate and present fixes for all actionable risks — this is the primary value of the review workflow, not an optional step. Follow the same auto-fix flow described in the Core workflow section above (locate repo, verify branch, generate fixes, push to feat/release-readiness-fix).

• If FAILED or TIMED_OUT: Present the error information and suggest next steps.
• If CANCELED: Inform the user the job was canceled and no report is available.

Cancelling (fallback)

aws devops-agent update-backlog-task \
  --agent-space-id SPACE_ID \
  --task-id TASK_ID \
  --task-status CANCELED \
  --region us-east-1