updating initial workflows to create tags

[sean-sype-simmons]

updated documentation

removed some options for stub versions

Description

Related Issue

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Chore (non-breaking change that does not add functionality or fix an issue)

Checklist:

• I have read the CONTRIBUTING document.
• I have run the pre-merge tests locally and they pass.
• I have updated the documentation accordingly.
• I have added tests to cover my changes.
• If Gemfile.lock has changed, I have used --conservative to do it and included the full output in the Description above.
• All new and existing tests passed.
• All commits have been signed-off for the Developer Certificate of Origin.

[Copilot]

Pull request overview

Adds end-user documentation and a reusable workflow to support semantic version tagging/releases for the chef/common-github-actions reusable workflow suite, along with updated stub guidance for pinning workflows by tag.

Changes:

• Added a reusable create-release-tag.yml workflow to calculate, create, and push a semantic version tag (and create a GitHub Release).
• Added new documentation pages (HOW-TO-USE.md, PIPELINE-REFERENCE.md) and linked them prominently from README.md.
• Simplified the CI stub workflow by removing stub-version echoing and adding guidance to pin to tags.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
README.md	Adds prominent links to the new usage/reference documentation.
HOW-TO-USE.md	New quick-start and configuration guide, including tag-based versioning guidance.
PIPELINE-REFERENCE.md	New comprehensive reference for pipeline jobs/tools and their mappings.
.github/workflows/stubs/create-release-tag-stub.yml	New stub workflow for consumers to call the tag/release workflow.
.github/workflows/stubs/ci-main-pull-request-stub.yml	Removes stub-version echo job; adds guidance to pin reusable workflow by tag.
.github/workflows/create-release-tag.yml	New reusable workflow implementing tag calculation, tag push, and GitHub Release creation.

Comments suppressed due to low confidence (4)

HOW-TO-USE.md:75

• The copy commands reference files without the workflow-supporting-files/sonar-templates/ prefix, so they won’t work when run from a consumer repo. Update the examples to include the correct relative path (or clarify that the templates must be copied out of this repository first).

Copy the appropriate template from `workflow-supporting-files/sonar-templates/` to your repository root:

```bash
# For Go projects
cp GO-sonar-project.properties sonar-project.properties

# For Ruby projects
cp RUBY-sonar-project.properties sonar-project.properties

# For Rust projects
cp RUST-sonar-project.properties sonar-project.properties

**.github/workflows/create-release-tag.yml:120**
* If `version_bump` is anything other than major/minor/patch, the `case` falls through and silently keeps the same version. It would be safer to add a default case that fails the workflow with an error so an invalid input can’t produce an unexpected tag.

      # Calculate new version based on bump type
      case $BUMP_TYPE in
        major)
          MAJOR=$((MAJOR + 1))
          MINOR=0
          PATCH=0
          ;;
        minor)
          MINOR=$((MINOR + 1))
          PATCH=0
          ;;
        patch)
          PATCH=$((PATCH + 1))
          ;;
      esac

**.github/workflows/create-release-tag.yml:177**
* The summary always reports `v${{ steps.calc_version.outputs.new_version }}` as the "New Tag" even when tag creation is skipped because it already exists. Use the actual created tag output (or explicitly indicate the tag was skipped) to avoid misleading workflow summaries.

  - name: Output summary
    run: |
      echo "## 🏷️ Release Tag Summary" >> $GITHUB_STEP_SUMMARY
      echo "" >> $GITHUB_STEP_SUMMARY
      echo "| Property | Value |" >> $GITHUB_STEP_SUMMARY
      echo "|----------|-------|" >> $GITHUB_STEP_SUMMARY
      echo "| Previous Tag | ${{ steps.get_latest_tag.outputs.latest_tag }} |" >> $GITHUB_STEP_SUMMARY
      echo "| New Tag | v${{ steps.calc_version.outputs.new_version }} |" >> $GITHUB_STEP_SUMMARY
      echo "| Commit SHA | ${{ github.sha }} |" >> $GITHUB_STEP_SUMMARY

**.github/workflows/create-release-tag.yml:247**
* `softprops/action-gh-release` is configured with both `body_path` and `generate_release_notes: true`. These options can conflict (GitHub-generated notes may override or duplicate the provided body). Prefer one approach: either rely on generated release notes, or keep `body_path` and set `generate_release_notes` to false.

  - name: Create GitHub Release
    uses: softprops/action-gh-release@v2
    with:
      tag_name: ${{ needs.create-tag.outputs.new_tag }}
      name: "Release ${{ needs.create-tag.outputs.new_tag }}"
      body_path: release_notes.md
      draft: false
      prerelease: false
      generate_release_notes: true

</details>



---

💡 <a href="/chef/common-github-actions/new/main/.github/instructions?filename=*.instructions.md" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Add Copilot custom instructions</a> for smarter, more guided reviews. <a href="https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Learn how to get started</a>.

[sean-sype-simmons]

Will need to create a manual tag prior to this being merged.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (3)

HOW-TO-USE.md:74

• The copy commands for sonar-project.properties omit the workflow-supporting-files/sonar-templates/ path mentioned just above, so they won’t work as written. Update the examples to include the full relative path (or clarify where the templates should be downloaded from) so users can copy the correct files.

Copy the appropriate template from `workflow-supporting-files/sonar-templates/` to your repository root:

```bash
# For Go projects
cp GO-sonar-project.properties sonar-project.properties

# For Ruby projects
cp RUBY-sonar-project.properties sonar-project.properties

# For Rust projects
cp RUST-sonar-project.properties sonar-project.properties

.github/workflows/create-release-tag.yml:266

• git log ${PREVIOUS_TAG}..HEAD can include commits beyond the tag being released (depending on what HEAD points to after checkout). Generate the changelog against the specific tag/sha you’re releasing (for example ${PREVIOUS_TAG}..${NEW_TAG}) so the release notes are deterministic.

          # Generate changelog between tags
          if [ "$PREVIOUS_TAG" != "v0.0.0" ]; then
            CHANGELOG=$(git log --pretty=format:"- %s (%h)" ${PREVIOUS_TAG}..HEAD 2>/dev/null || echo "- Initial release")
          else

PIPELINE-REFERENCE.md:260

• polaris-detect-search-depth is documented here as defaulting to '5', but the actual reusable workflow input currently defaults to an empty string (and is then passed as null when unset). Please update the documentation to match the real default behavior, or change the workflow default if '5' is intended.

- `polaris-coverity-args` (string) - Additional Coverity arguments
- `polaris-detect-search-depth` (string) - Detect search depth, default: '5'
- `polaris-detect-args` (string) - Additional Detect arguments

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.