Required Fixes for Workflows and Docs

[piyumaldk]

$Subject

Summary by CodeRabbit

• Documentation

  • Added quick-start guide for ap CLI with installation instructions for macOS, Linux, and Windows, plus required environment variable setup.

• Chores

  • Release binaries now packaged as platform-specific ZIP files instead of raw binaries.
  • Build workflow improvements with enhanced logging and error handling.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Updates to CI/CD workflows enhance the hourly build process with Go module caching, structured logging, and error handling, while the release workflow transitions from individual binaries to platform-specific ZIP archives. Documentation and manifest files support these automation changes.

Changes

Cohort / File(s)	Summary
GitHub Workflow – Hourly Build .github/workflows/cli-gw-build-hourly.yml	Schedule changed from every 30 minutes to hourly. Added Go module caching with restore-keys. Introduced per-step log files (gateway-build.log, cli-build.log, prepare-dir.log, ap-gateway-image-build.log) with centralized error handling (pipefail, RC-based exit). Refactored prepare directory step with robust binary discovery and manifest handling. Added dedicated smoke test step with conditional execution and docker.log capture.
GitHub Workflow – Release .github/workflows/cli-release.yml	Replaced binary renaming with new "Package platform zips" step that loops over platform targets, bundles binaries into per-platform ZIP archives with version naming, and removes raw binaries post-packaging. Updated GitHub Release creation to reference ZIP artifacts instead of individual binaries. Added workflow artifact upload for release-artifacts.
Configuration cli/src/tests/resources/simple-policy-manifest.yaml	Added comment lines documenting the manifest purpose. Introduced explicit top-level policies: key under version metadata.
Documentation docs/cli/quick-start-guide.md	New quick-start guide covering prebuilt ap binary installation on PATH for macOS/Linux and Windows, environment variable setup (WSO2AP_GW_USERNAME, WSO2AP_GW_PASSWORD, POLICY_HUB_URL), and CLI execution instructions.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 A builder's tale in YAML bright,
Zip files packaged, logs held tight,
Caching hops through every test,
From hourly builds to GitHub's best,
Documentation guides the way—
Our CLI shines another day! 🚀

Pre-merge checks and finishing touches

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The pull request description contains only a placeholder '$Subject' with no actual content, failing to provide any meaningful explanation of purpose, goals, approach, documentation, testing, or security information required by the template.	Complete the pull request description by filling in all required template sections: Purpose (with issue links), Goals, Approach, User stories, Documentation, Automation tests, Security checks, Samples, Related PRs, and Test environment.
Title check	❓ Inconclusive	The title 'Required Fixes for Workflows and Docs' is vague and generic, using non-descriptive terms that don't convey specific information about the actual changes (workflow scheduling/caching improvements, release packaging, and CLI documentation).	Provide a more specific title that highlights the main change, such as 'Add hourly gateway build scheduling, release packaging, and CLI quick-start guide' or focus on the primary objective.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

.github/workflows/cli-gw-build-hourly.yml (1)

154-274: CRITICAL: Remove duplicate workflow definition.

The entire workflow is duplicated starting at line 154, creating duplicate name, on, and jobs keys. This is a YAML syntax error that will cause the workflow to fail or produce unexpected behavior.

Only one workflow definition should remain. The first version (lines 1-153) appears more robust with explicit error handling and exit codes.

Based on static analysis hints.

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between f8bfb4e and ad2430e.

📒 Files selected for processing (4)

• .github/workflows/cli-gw-build-hourly.yml
• .github/workflows/cli-release.yml
• cli/src/tests/resources/simple-policy-manifest.yaml
• docs/cli/quick-start-guide.md

🧰 Additional context used

🪛 actionlint (1.7.9)

.github/workflows/cli-gw-build-hourly.yml

154-154: key "name" is duplicated in workflow. previously defined at line:1,col:1

(syntax-check)

---

156-156: key "on" is duplicated in workflow. previously defined at line:3,col:1

(syntax-check)

---

161-161: key "jobs" is duplicated in workflow. previously defined at line:8,col:1

(syntax-check)

🪛 markdownlint-cli2 (0.18.1)

docs/cli/quick-start-guide.md

7-7: Unordered list indentation
Expected: 2; Actual: 1

(MD007, ul-indent)

---

7-7: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

9-9: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

10-10: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

11-11: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

13-13: Unordered list indentation
Expected: 2; Actual: 1

(MD007, ul-indent)

---

13-13: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

15-15: Hard tabs
Column: 1

(MD010, no-hard-tabs)

🪛 YAMLlint (1.37.1)

.github/workflows/cli-gw-build-hourly.yml

[error] 154-154: duplication of key "name" in mapping

(key-duplicates)

---

[error] 156-156: duplication of key "on" in mapping

(key-duplicates)

---

[error] 161-161: duplication of key "jobs" in mapping

(key-duplicates)

🔇 Additional comments (6)

cli/src/tests/resources/simple-policy-manifest.yaml (1)

1-5: LGTM! Clear documentation of manifest purpose.

The added comments and explicit policies: key improve the manifest's readability and make its role in the periodic testing workflow clear.

.github/workflows/cli-release.yml (2)

53-107: LGTM! Robust platform-specific packaging logic.

The new packaging approach correctly:

• Uses set -euo pipefail for proper error handling
• Creates platform-specific ZIPs with top-level directories
• Handles missing binaries gracefully with placeholder files
• Preserves executable permissions for Unix binaries
• Cleans up temporary files and raw binaries

---

157-161: LGTM! Workflow artifact upload enhances traceability.

Uploading the release ZIPs as workflow artifacts provides a convenient way to access and verify the packaged binaries directly from the workflow run.

.github/workflows/cli-gw-build-hourly.yml (3)

22-30: LGTM! Go module caching improves build performance.

The added Go module cache step will significantly speed up subsequent workflow runs by reusing downloaded dependencies and build artifacts.

---

88-114: LGTM! Comprehensive smoke test with proper log handling.

The smoke test step correctly:

• Sets up required environment variables
• Creates log directories before execution
• Handles missing binaries gracefully
• Captures both stdout/stderr and docker.log
• Provides clear error messages with log references

---

116-153: LGTM! Structured artifact upload ensures logs are always available.

The placeholder creation and individual log uploads ensure that artifacts are consistently available for debugging, even when steps fail early or produce no output.