From 71e034171d8f00d9eb199631aa38acfb49412b44 Mon Sep 17 00:00:00 2001 From: Sean Simmons Date: Fri, 20 Feb 2026 09:25:25 -0500 Subject: [PATCH 1/4] updating initial workflows to create tags updated documentation removed some options for stub versions Signed-off-by: Sean Simmons --- .github/workflows/create-release-tag.yml | 249 +++++ .../stubs/ci-main-pull-request-stub.yml | 15 +- .../stubs/create-release-tag-stub.yml | 42 + HOW-TO-USE.md | 993 ++++++++++++++++++ combined-documentation.md | 743 +++++++++++++ 5 files changed, 2030 insertions(+), 12 deletions(-) create mode 100644 .github/workflows/create-release-tag.yml create mode 100644 .github/workflows/stubs/create-release-tag-stub.yml create mode 100644 HOW-TO-USE.md create mode 100644 combined-documentation.md diff --git a/.github/workflows/create-release-tag.yml b/.github/workflows/create-release-tag.yml new file mode 100644 index 0000000..236e495 --- /dev/null +++ b/.github/workflows/create-release-tag.yml @@ -0,0 +1,249 @@ +# Workflow to create a git tag when code is merged to main branch +# This tag can be used to version projects that reference this repository +# +# Usage: Projects can reference a specific version of common-github-actions using the tag: +# uses: chef/common-github-actions/.github/workflows/ci-main-pull-request.yml@v1.0.7 +# +# Tag format: v{MAJOR}.{MINOR}.{PATCH} +# - MAJOR: Breaking changes +# - MINOR: New features, backward compatible +# - PATCH: Bug fixes, backward compatible +# +# This workflow can be: +# 1. Used directly in this repository (triggers on push/workflow_dispatch) +# 2. Called by other repositories via workflow_call + +name: Create Release Tag on Merge + +on: + push: + branches: + - main + workflow_dispatch: + inputs: + version_bump: + description: 'Version bump type' + required: true + default: 'patch' + type: choice + options: + - major + - minor + - patch + custom_version: + description: 'Custom version (overrides version_bump, format: X.Y.Z without v prefix)' + required: false + type: string + workflow_call: + inputs: + version_bump: + description: 'Version bump type (major, minor, patch)' + required: false + type: string + default: 'patch' + custom_version: + description: 'Custom version (overrides version_bump, format: X.Y.Z without v prefix)' + required: false + type: string + default: '' + +permissions: + contents: write + +env: + WORKFLOW_VERSION: '1.0.0' + +jobs: + create-tag: + name: 'Create Release Tag' + runs-on: ubuntu-latest + outputs: + new_tag: ${{ steps.create_tag.outputs.new_tag }} + previous_tag: ${{ steps.get_latest_tag.outputs.latest_tag }} + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 + fetch-tags: true + + - name: Get latest tag + id: get_latest_tag + run: | + # Get the latest tag, default to v0.0.0 if no tags exist + LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "v0.0.0") + echo "latest_tag=${LATEST_TAG}" >> $GITHUB_OUTPUT + echo "Latest tag: ${LATEST_TAG}" + + - name: Calculate new version + id: calc_version + run: | + LATEST_TAG="${{ steps.get_latest_tag.outputs.latest_tag }}" + + # Handle custom version input + if [ -n "${{ inputs.custom_version }}" ]; then + NEW_VERSION="${{ inputs.custom_version }}" + echo "Using custom version: ${NEW_VERSION}" + echo "new_version=${NEW_VERSION}" >> $GITHUB_OUTPUT + exit 0 + fi + + # Strip 'v' prefix for version calculation + VERSION=${LATEST_TAG#v} + + # Split version into parts + MAJOR=$(echo $VERSION | cut -d. -f1) + MINOR=$(echo $VERSION | cut -d. -f2) + PATCH=$(echo $VERSION | cut -d. -f3) + + # Default to patch bump for push events, use input for workflow_dispatch + BUMP_TYPE="${{ inputs.version_bump }}" + if [ -z "$BUMP_TYPE" ]; then + BUMP_TYPE="patch" + fi + + # 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 + + NEW_VERSION="${MAJOR}.${MINOR}.${PATCH}" + echo "new_version=${NEW_VERSION}" >> $GITHUB_OUTPUT + echo "Bump type: ${BUMP_TYPE}" + echo "New version: ${NEW_VERSION}" + + - name: Check if tag already exists + id: check_tag + run: | + NEW_TAG="v${{ steps.calc_version.outputs.new_version }}" + if git rev-parse "$NEW_TAG" >/dev/null 2>&1; then + echo "Tag ${NEW_TAG} already exists!" + echo "exists=true" >> $GITHUB_OUTPUT + else + echo "Tag ${NEW_TAG} does not exist, proceeding with creation" + echo "exists=false" >> $GITHUB_OUTPUT + fi + + - name: Create and push tag + id: create_tag + if: steps.check_tag.outputs.exists == 'false' + run: | + NEW_TAG="v${{ steps.calc_version.outputs.new_version }}" + + # Configure git + git config user.name "github-actions[bot]" + git config user.email "github-actions[bot]@users.noreply.github.com" + + # Create annotated tag with message + git tag -a "${NEW_TAG}" -m "Release ${NEW_TAG} + + Automated release tag created on merge to main branch. + + Previous version: ${{ steps.get_latest_tag.outputs.latest_tag }} + Commit: ${{ github.sha }} + Triggered by: ${{ github.actor }}" + + # Push the tag + git push origin "${NEW_TAG}" + + echo "new_tag=${NEW_TAG}" >> $GITHUB_OUTPUT + echo "✅ Created and pushed tag: ${NEW_TAG}" + + - name: Skip tag creation (already exists) + if: steps.check_tag.outputs.exists == 'true' + run: | + echo "⚠️ Skipping tag creation - tag v${{ steps.calc_version.outputs.new_version }} already exists" + + - 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 + echo "| Actor | ${{ github.actor }} |" >> $GITHUB_STEP_SUMMARY + echo "| Workflow Version | ${{ env.WORKFLOW_VERSION }} |" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "### Usage" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "Reference this version in your workflow:" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "\`\`\`yaml" >> $GITHUB_STEP_SUMMARY + echo "uses: chef/common-github-actions/.github/workflows/ci-main-pull-request.yml@v${{ steps.calc_version.outputs.new_version }}" >> $GITHUB_STEP_SUMMARY + echo "\`\`\`" >> $GITHUB_STEP_SUMMARY + + create-release: + name: 'Create GitHub Release' + runs-on: ubuntu-latest + needs: create-tag + if: needs.create-tag.outputs.new_tag != '' + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Generate release notes + id: release_notes + run: | + PREVIOUS_TAG="${{ needs.create-tag.outputs.previous_tag }}" + NEW_TAG="${{ needs.create-tag.outputs.new_tag }}" + + # 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 + CHANGELOG="- Initial release" + fi + + # Write to file for multi-line handling + cat > release_notes.md << EOF + ## What's Changed + + ${CHANGELOG} + + ## Usage + + Reference this version in your workflow: + + \`\`\`yaml + jobs: + call-ci-main-pr-check-pipeline: + uses: chef/common-github-actions/.github/workflows/ci-main-pull-request.yml@${NEW_TAG} + secrets: inherit + permissions: + id-token: write + contents: read + \`\`\` + + ## Full Changelog + + https://github.com/${{ github.repository }}/compare/${PREVIOUS_TAG}...${NEW_TAG} + EOF + + - 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 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/stubs/ci-main-pull-request-stub.yml b/.github/workflows/stubs/ci-main-pull-request-stub.yml index 8de6151..edfacb6 100644 --- a/.github/workflows/stubs/ci-main-pull-request-stub.yml +++ b/.github/workflows/stubs/ci-main-pull-request-stub.yml @@ -15,21 +15,12 @@ on: permissions: contents: read - -env: - STUB_VERSION: "1.0.7" jobs: - echo_version: - name: 'Echo stub version' - runs-on: ubuntu-latest - steps: - - name: echo version of stub and inputs - run: | - echo "CI main pull request stub version $STUB_VERSION" - call-ci-main-pr-check-pipeline: - uses: chef/common-github-actions/.github/workflows/ci-main-pull-request.yml@main + # To pin to a specific version, change @main to a tag like @v1.0.7 + # Available tags: https://github.com/chef/common-github-actions/tags + uses: chef/common-github-actions/.github/workflows/ci-main-pull-request.yml@main # or use @v1.0.7 secrets: inherit permissions: id-token: write diff --git a/.github/workflows/stubs/create-release-tag-stub.yml b/.github/workflows/stubs/create-release-tag-stub.yml new file mode 100644 index 0000000..8848604 --- /dev/null +++ b/.github/workflows/stubs/create-release-tag-stub.yml @@ -0,0 +1,42 @@ +# Stub to call the common GitHub Action for creating release tags +# Copy this file to your repository's .github/workflows/ directory +# +# This workflow will create a git tag when code is merged to main branch +# Projects can then reference a specific version of common-github-actions + +name: Create Release Tag + +on: + push: + branches: + - main + workflow_dispatch: + inputs: + version_bump: + description: 'Version bump type' + required: true + default: 'patch' + type: choice + options: + - major + - minor + - patch + custom_version: + description: 'Custom version (overrides version_bump, format: X.Y.Z without v prefix)' + required: false + type: string + +permissions: + contents: write + +jobs: + call-create-release-tag: + # To pin to a specific version, change @main to a tag like @v1.0.7 + # Available tags: https://github.com/chef/common-github-actions/tags + uses: chef/common-github-actions/.github/workflows/create-release-tag.yml@main + secrets: inherit + permissions: + contents: write + with: + version_bump: ${{ inputs.version_bump || 'patch' }} + custom_version: ${{ inputs.custom_version || '' }} diff --git a/HOW-TO-USE.md b/HOW-TO-USE.md new file mode 100644 index 0000000..29b0a71 --- /dev/null +++ b/HOW-TO-USE.md @@ -0,0 +1,993 @@ +# HOW-TO-USE: Chef Common GitHub Actions + +This guide explains how to use the reusable workflows from the `chef/common-github-actions` repository in your own projects. + +--- + +## Table of Contents + +- [Quick Start](#quick-start) +- [Versioning with Tags](#versioning-with-tags) +- [Available Workflows](#available-workflows) +- [CI/CD Pipeline Architecture](#cicd-pipeline-architecture) +- [Workflow Reference](#workflow-reference) + - [CI Main Pull Request](#ci-main-pull-request) + - [Create Release Tag](#create-release-tag) + - [SCC (Source Code Complexity)](#scc-source-code-complexity) + - [TruffleHog (Secret Scanning)](#trufflehog-secret-scanning) + - [Trivy (Vulnerability Scanning)](#trivy-vulnerability-scanning) + - [SonarQube (SAST)](#sonarqube-sast) + - [SBOM Generation](#sbom-generation) + - [Quality Dashboard](#quality-dashboard) +- [Required Secrets](#required-secrets) +- [Configuration Examples](#configuration-examples) + +--- + +## Quick Start + +### Step 1: Copy the Stub Workflow + +Copy the stub file to your repository's `.github/workflows/` directory: + +```yaml +# .github/workflows/ci-main-pull-request.yml +name: CI Pull Request on Main Branch + +on: + pull_request: + branches: [ main, release/** ] + push: + branches: [ main, release/** ] + workflow_dispatch: + +permissions: + contents: read + +jobs: + call-ci-main-pr-check-pipeline: + uses: chef/common-github-actions/.github/workflows/ci-main-pull-request.yml@v1.0.7 + secrets: inherit + permissions: + id-token: write + contents: read + with: + visibility: ${{ github.event.repository.visibility }} + language: 'go' # go, ruby, rust + perform-complexity-checks: true + perform-trufflehog-scan: true + perform-trivy-scan: true + perform-sonarqube-scan: true + generate-sbom: true +``` + +### Step 2: Configure Required Secrets + +Ensure your repository or organization has the following secrets configured: + +| Secret | Purpose | +|--------|---------| +| `SONAR_TOKEN` | SonarQube authentication | +| `SONAR_HOST_URL` | SonarQube server URL | +| `POLARIS_ACCESS_TOKEN` | BlackDuck Polaris authentication | +| `POLARIS_SERVER_URL` | BlackDuck Polaris server URL | +| `BLACKDUCK_SCA_TOKEN` | BlackDuck SCA authentication | +| `BLACKDUCK_SBOM_URL` | BlackDuck SCA server URL | + +### Step 3: Add sonar-project.properties + +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 +``` + +--- + +## Versioning with Tags + +The `common-github-actions` repository uses semantic versioning tags to allow projects to reference specific versions: + +```yaml +# Reference a specific version (recommended for stability) +uses: chef/common-github-actions/.github/workflows/ci-main-pull-request.yml@v1.0.7 + +# Reference the latest from main (use with caution) +uses: chef/common-github-actions/.github/workflows/ci-main-pull-request.yml@main +``` + +### Tag Format + +Tags follow semantic versioning: `v{MAJOR}.{MINOR}.{PATCH}` + +- **MAJOR**: Breaking changes +- **MINOR**: New features, backward compatible +- **PATCH**: Bug fixes, backward compatible + +### Create Release Tag Workflow + +When code is merged to `main` in `common-github-actions`, a new tag is automatically created. You can also trigger manual tag creation: + +```yaml +# Manual tag creation with version bump +workflow_dispatch: + inputs: + version_bump: 'minor' # major, minor, or patch +``` + +--- + +## Available Workflows + +| Workflow | Purpose | File | +|----------|---------|------| +| CI Main Pull Request | Complete CI pipeline with security scans | `ci-main-pull-request.yml` | +| Create Release Tag | Auto-tag on merge to main | `create-release-tag.yml` | +| SCC | Source code complexity analysis | `scc.yml` | +| TruffleHog | Secret scanning | `trufflehog.yml` | +| Trivy | Vulnerability scanning | `trivy.yml` | +| SonarQube (Public) | SAST for public repos | `sonarqube-public-repo.yml` | +| SonarQube (Internal) | SAST for internal repos | `sonarqube-internal-repo.yml` | +| SBOM | Software Bill of Materials | `sbom.yml` | +| Quality Dashboard | Atlassian quality reporting | `irfan-quality-dashboard.yml` | + +--- + +## CI/CD Pipeline Architecture + +### Complete Pipeline Flow + +```mermaid +flowchart TB + subgraph Trigger["🚀 Trigger Events"] + PR[Pull Request] + Push[Push to main/release] + Manual[Manual Dispatch] + end + + subgraph PreChecks["📋 Pre-compilation Checks"] + direction TB + PC[precompilation-checks] + CO[checkout] + PC --> |"detect custom properties"| ENV[Set Environment] + end + + subgraph CodeQuality["📊 Code Quality"] + direction TB + SCC[scc.yml
Source Code Complexity] + LSC[language-specific-checks
Linting] + LAC[language-agnostic-checks
OWASP] + end + + subgraph SecurityScans["🔒 Security Scans"] + direction TB + TH[trufflehog.yml
Secret Scanning] + TV[trivy.yml
Vulnerability Scan] + end + + subgraph BuildTest["🔨 Build & Test"] + direction TB + BUILD[ci-build
Compilation] + UT[ci-unit-test
Unit Tests] + VER[set-application-version] + end + + subgraph SAST["🛡️ SAST Analysis"] + direction TB + SONAR_PUB[Sonar-public-repo] + SONAR_PRIV[Sonar-private-repo] + SONAR_INT[Sonar-internal-repo] + POLARIS[BlackDuck-Polaris-SAST] + end + + subgraph Packaging["📦 Packaging"] + direction TB + PKG[package-binary] + HAB_BUILD[habitat-build] + HAB_PUB[habitat-publish] + GRYPE_LIN[habitat-grype-scan-linux] + GRYPE_WIN[habitat-grype-scan-windows] + PUB[publish] + end + + subgraph SBOM_SCA["📋 SBOM & SCA"] + direction TB + SBOM[sbom.yml
SBOM Generation] + SCA[BlackDuck SCA] + MSFT[Microsoft SBOM] + LICENSE[License Scout] + end + + subgraph Reporting["📈 Reporting"] + direction TB + DASH[quality-dashboard
Atlassian Dashboard] + end + + Trigger --> PreChecks + PreChecks --> CO + CO --> CodeQuality + CO --> SecurityScans + CO --> BuildTest + CO --> POLARIS + + BuildTest --> SAST + BuildTest --> Packaging + BuildTest --> SBOM_SCA + + HAB_BUILD --> HAB_PUB + HAB_PUB --> GRYPE_LIN + HAB_PUB --> GRYPE_WIN + HAB_BUILD --> PUB + + SBOM_SCA --> Reporting + + style Trigger fill:#e1f5fe + style PreChecks fill:#f3e5f5 + style CodeQuality fill:#e8f5e9 + style SecurityScans fill:#ffebee + style BuildTest fill:#fff3e0 + style SAST fill:#fce4ec + style Packaging fill:#e0f2f1 + style SBOM_SCA fill:#f1f8e9 + style Reporting fill:#ede7f6 +``` + +### Nested Workflow Dependencies + +```mermaid +flowchart LR + subgraph Main["ci-main-pull-request.yml"] + direction TB + M_START((Start)) + M_PRE[Pre-checks] + M_CHECKOUT[Checkout] + M_BUILD[Build] + M_END((End)) + end + + subgraph External["Reusable Workflows"] + direction TB + E_SCC["scc.yml"] + E_TH["trufflehog.yml"] + E_TV["trivy.yml"] + E_SONAR_PUB["sonarqube-public-repo.yml"] + E_SONAR_INT["sonarqube-internal-repo.yml"] + E_SBOM["sbom.yml"] + E_QD["irfan-quality-dashboard.yml"] + end + + subgraph Actions["Composite Actions"] + direction TB + A_AZURE["azure-login"] + A_FIREWALL["update-firewall-rule"] + A_GRYPE["chef-download-grype-snapshot"] + end + + M_CHECKOUT --> E_SCC + M_CHECKOUT --> E_TH + M_CHECKOUT --> E_TV + M_BUILD --> E_SONAR_PUB + M_BUILD --> E_SONAR_INT + M_BUILD --> E_SBOM + E_SBOM --> E_QD + + E_SONAR_PUB --> A_AZURE + E_SONAR_INT --> A_AZURE + A_AZURE --> A_FIREWALL + + style Main fill:#e3f2fd + style External fill:#fff8e1 + style Actions fill:#fce4ec +``` + +--- + +## Workflow Reference + +### CI Main Pull Request + +The main CI workflow that orchestrates all security and quality checks. + +**Workflow File:** `ci-main-pull-request.yml` + +#### Input Variables + +```mermaid +flowchart TB + subgraph Required["Required Inputs"] + visibility["visibility
(public/private/internal)"] + language["language
(go/ruby/rust)"] + end + + subgraph Version["Version Configuration"] + version["version
default: 1.0.0"] + detect_type["detect-version-source-type
(none/file/github-tag/github-release)"] + detect_param["detect-version-source-parameter"] + end + + subgraph CodeQuality["Code Quality Flags"] + complexity["perform-complexity-checks
default: true"] + linting["perform-language-linting
default: true"] + scc_output["scc-output-filename
default: scc-complexity"] + end + + subgraph Security["Security Scan Flags"] + trufflehog["perform-trufflehog-scan
default: true"] + trivy["perform-trivy-scan
default: true"] + polaris["perform-blackduck-polaris
default: false"] + sonar["perform-sonarqube-scan
default: true"] + docker["perform-docker-scan
default: false"] + end + + subgraph Polaris["Polaris Configuration"] + pol_app["polaris-application-name"] + pol_proj["polaris-project-name"] + pol_work["polaris-working-directory"] + pol_mode["polaris-assessment-mode
(SAST/CI/SOURCE_UPLOAD)"] + pol_wait["wait-for-scan
default: true"] + end + + subgraph Build["Build Configuration"] + build["build
default: true"] + build_profile["build-profile
default: cli"] + unit_tests["unit-tests
default: true"] + unit_output["unit-test-output-path"] + unit_cmd["unit-test-command-override"] + end + + subgraph Habitat["Habitat Configuration"] + hab_build["habitat-build
default: true"] + hab_publish["publish-habitat-packages
default: false"] + hab_pkg["publish-habitat-hab_package"] + hab_ver["publish-habitat-hab_version"] + hab_rel["publish-habitat-hab_release"] + hab_ch["publish-habitat-hab_channel
default: stable"] + hab_os["publish-habitat-runner_os
default: ubuntu-latest"] + hab_grype["habitat-grype-scan
default: false"] + end + + subgraph SBOM["SBOM Configuration"] + gen_sbom["generate-sbom
default: true"] + gh_sbom["export-github-sbom
default: true"] + msft_sbom["generate-msft-sbom
default: true"] + license["license_scout
default: true"] + bd_sca["perform-blackduck-sca-scan
default: false"] + bd_group["blackduck-project-group-name
default: Chef"] + bd_proj["blackduck-project-name"] + end + + subgraph Quality["Quality Dashboard"] + report_dash["report-to-atlassian-dashboard
default: true"] + report_cov["report-unit-test-coverage
default: true"] + q_prod["quality-product-name"] + q_sonar["quality-sonar-app-name"] + q_type["quality-testing-type"] + q_svc["quality-service-name"] + q_junit["quality-junit-report"] + end + + style Required fill:#ffcdd2 + style Version fill:#c8e6c9 + style CodeQuality fill:#bbdefb + style Security fill:#ffecb3 + style Polaris fill:#f8bbd9 + style Build fill:#d1c4e9 + style Habitat fill:#b2dfdb + style SBOM fill:#c5cae9 + style Quality fill:#dcedc8 +``` + +#### Complete Input Reference + +| Input | Type | Default | Description | +|-------|------|---------|-------------| +| `application` | string | - | Application from repository custom properties | +| `visibility` | string | `public` | Repository visibility (public/private/internal) | +| `go-private-modules` | string | `github.com/progress-platform-services/*` | GOPRIVATE for Go modules | +| `version` | string | `1.0.0` | Project version | +| `detect-version-source-type` | string | `none` | Version detection method | +| `detect-version-source-parameter` | string | - | Parameter for version detection | +| `language` | string | `ruby` | Build language (go/ruby/rust) | +| `perform-complexity-checks` | boolean | `true` | Run SCC complexity checks | +| `scc-output-filename` | string | `scc-complexity` | SCC output filename | +| `perform-language-linting` | boolean | `true` | Run language-specific linting | +| `perform-trufflehog-scan` | boolean | `true` | Run TruffleHog secret scan | +| `perform-trivy-scan` | boolean | `true` | Run Trivy vulnerability scan | +| `build` | boolean | `true` | Run CI build | +| `build-profile` | string | `cli` | Build profile | +| `unit-tests` | boolean | `true` | Run unit tests | +| `unit-test-output-path` | string | `test/unittest` | Unit test output path | +| `unit-test-command-override` | string | - | Custom unit test command | +| `perform-blackduck-polaris` | boolean | `false` | Run BlackDuck Polaris SAST | +| `polaris-application-name` | string | - | Polaris application name | +| `polaris-project-name` | string | `${{ github.event.repository.name }}` | Polaris project name | +| `polaris-working-directory` | string | `.` | Polaris working directory | +| `polaris-config-path` | string | - | Detect configuration file path | +| `polaris-coverity-config-path` | string | - | Coverity configuration file path | +| `polaris-coverity-build-command` | string | `go build` | Coverity build command | +| `polaris-coverity-clean-command` | string | `go clean` | Coverity clean command | +| `polaris-coverity-args` | string | - | Additional Coverity arguments | +| `polaris-detect-search-depth` | string | - | Detect search depth | +| `polaris-detect-args` | string | - | Additional Detect arguments | +| `polaris-assessment-mode` | string | `CI` | Assessment mode (SAST/CI/SOURCE_UPLOAD) | +| `wait-for-scan` | boolean | `true` | Wait for scan completion | +| `perform-sonarqube-scan` | boolean | `true` | Run SonarQube scan | +| `perform-docker-scan` | boolean | `false` | Run Docker scan | +| `report-unit-test-coverage` | boolean | `true` | Report unit test coverage | +| `report-to-atlassian-dashboard` | boolean | `true` | Report to quality dashboard | +| `quality-product-name` | string | `Chef360` | Product name for reporting | +| `quality-sonar-app-name` | string | `YourSonarAppName` | Sonar application name | +| `quality-testing-type` | string | `Integration` | Testing type | +| `quality-service-name` | string | `YourServiceOrRepoName` | Service name | +| `quality-junit-report` | string | `path/to/junit/report` | JUnit report path | +| `package-binaries` | boolean | `true` | Package binaries | +| `habitat-build` | boolean | `true` | Create Habitat packages | +| `publish-habitat-packages` | boolean | `false` | Publish Habitat packages | +| `publish-habitat-hab_package` | string | `core/nginx` | Habitat package name | +| `publish-habitat-hab_version` | string | - | Habitat package version | +| `publish-habitat-hab_release` | string | - | Habitat package release | +| `publish-habitat-hab_channel` | string | `stable` | Habitat channel | +| `publish-habitat-hab_auth_token` | string | - | Habitat auth token | +| `publish-habitat-runner_os` | string | `ubuntu-latest` | Habitat runner OS | +| `habitat-grype-scan` | boolean | `false` | Scan Habitat packages with Grype | +| `publish-packages` | boolean | `true` | Publish packages | +| `generate-sbom` | boolean | `true` | Generate SBOM | +| `export-github-sbom` | boolean | `true` | Export GitHub SBOM | +| `generate-msft-sbom` | boolean | `true` | Generate Microsoft SBOM | +| `license_scout` | boolean | `true` | Run license scout | +| `perform-blackduck-sca-scan` | boolean | `false` | Run BlackDuck SCA scan | +| `blackduck-project-group-name` | string | `Chef` | BlackDuck project group | +| `blackduck-project-name` | string | `${{ github.event.repository.name }}` | BlackDuck project name | +| `blackduck-force-low-accuracy-mode` | boolean | `false` | Force low accuracy mode | +| `run-bundle-install` | boolean | `false` | Run bundle install before scanning | +| `udf1` | string | `default` | User defined flag 1 | +| `udf2` | string | `default` | User defined flag 2 | +| `udf3` | string | `default` | User defined flag 3 | + +--- + +### Create Release Tag + +Automatically creates a git tag when code is merged to main. + +**Workflow File:** `create-release-tag.yml` + +#### Workflow Diagram + +```mermaid +flowchart TB + subgraph Trigger["Trigger"] + PUSH[Push to main] + MANUAL[Manual Dispatch] + end + + subgraph CreateTag["create-tag Job"] + CHECKOUT[Checkout
fetch-depth: 0] + GET_TAG[Get Latest Tag
git describe --tags] + CALC_VER[Calculate New Version
major/minor/patch] + CHECK_EXISTS[Check if Tag Exists] + CREATE[Create & Push Tag
git tag -a] + SUMMARY[Output Summary] + end + + subgraph CreateRelease["create-release Job"] + CHECKOUT2[Checkout] + GEN_NOTES[Generate Release Notes
git log] + CREATE_REL[Create GitHub Release
softprops/action-gh-release] + end + + Trigger --> CHECKOUT + CHECKOUT --> GET_TAG + GET_TAG --> CALC_VER + CALC_VER --> CHECK_EXISTS + CHECK_EXISTS -->|not exists| CREATE + CREATE --> SUMMARY + SUMMARY --> CHECKOUT2 + CHECKOUT2 --> GEN_NOTES + GEN_NOTES --> CREATE_REL + + style Trigger fill:#e1f5fe + style CreateTag fill:#e8f5e9 + style CreateRelease fill:#fff3e0 +``` + +#### Input Variables + +| Input | Type | Default | Description | +|-------|------|---------|-------------| +| `version_bump` | choice | `patch` | Version bump type (major/minor/patch) | +| `custom_version` | string | - | Custom version (overrides version_bump) | + +#### Usage Example + +```yaml +name: Create Release Tag + +on: + push: + branches: [ main ] + workflow_dispatch: + inputs: + version_bump: + description: 'Version bump type' + required: true + default: 'patch' + type: choice + options: [major, minor, patch] + +permissions: + contents: write + +jobs: + create-tag: + uses: chef/common-github-actions/.github/workflows/create-release-tag.yml@main + secrets: inherit + permissions: + contents: write + with: + version_bump: ${{ inputs.version_bump || 'patch' }} +``` + +--- + +### SCC (Source Code Complexity) + +Generates source code complexity metrics using SCC. + +**Workflow File:** `scc.yml` + +#### Workflow Diagram + +```mermaid +flowchart TB + subgraph SCC["scc Job"] + CHECKOUT[Checkout Repository] + INSTALL[Install SCC CLI
go install github.com/boyter/scc/v3@latest] + RUN[Run SCC Analysis] + UPLOAD_TXT[Upload TXT Artifact] + UPLOAD_JSON[Upload JSON Artifact] + UPLOAD_HTML[Upload HTML Artifact] + end + + CHECKOUT --> INSTALL + INSTALL --> RUN + RUN --> UPLOAD_TXT + RUN --> UPLOAD_JSON + RUN --> UPLOAD_HTML + + style SCC fill:#e8f5e9 +``` + +#### Input Variables + +| Input | Type | Default | Description | +|-------|------|---------|-------------| +| `outputfilename` | string | `scc-complexity` | Name of output file (without extension) | + +#### Output Artifacts + +- `{repo}-{branch}-{timestamp}-scc-complexity.txt` - Tabular format +- `{repo}-{branch}-{timestamp}-scc-complexity.json` - JSON detailed format +- `{repo}-{branch}-{timestamp}-scc-complexity.html` - HTML detailed format + +--- + +### TruffleHog (Secret Scanning) + +Scans for accidentally committed secrets in the repository. + +**Workflow File:** `trufflehog.yml` + +#### Workflow Diagram + +```mermaid +flowchart TB + subgraph TruffleHog["Trufflehog Job"] + CHECKOUT[Checkout Repository
fetch-depth: 0] + SCAN[TruffleHog Scan
trufflesecurity/trufflehog@main] + end + + CHECKOUT --> SCAN + + style TruffleHog fill:#ffebee +``` + +#### Input Variables + +None - this workflow has no required inputs. + +--- + +### Trivy (Vulnerability Scanning) + +Scans for vulnerabilities in dependencies. + +**Workflow File:** `trivy.yml` + +#### Workflow Diagram + +```mermaid +flowchart TB + subgraph Trivy["trivy Job"] + CHECKOUT[Checkout Repository] + GEN_PREFIX[Generate Filename Prefix] + SCAN_JSON[Trivy Scan - JSON Output] + UPLOAD_JSON[Upload JSON Artifact] + SCAN_TABLE[Trivy Scan - Table Output] + UPLOAD_TABLE[Upload Table Artifact] + end + + CHECKOUT --> GEN_PREFIX + GEN_PREFIX --> SCAN_JSON + SCAN_JSON --> UPLOAD_JSON + UPLOAD_JSON --> SCAN_TABLE + SCAN_TABLE --> UPLOAD_TABLE + + style Trivy fill:#ffebee +``` + +#### Input Variables + +| Input | Type | Default | Description | +|-------|------|---------|-------------| +| `outputfilename` | string | `trivy-output.json` | Output filename | +| `version` | string | `1.0.0` | Project version | + +--- + +### SonarQube (SAST) + +Static Application Security Testing using SonarQube. + +**Workflow Files:** +- `sonarqube-public-repo.yml` - For public repositories +- `sonarqube-internal-repo.yml` - For internal repositories +- Inline implementation for private repositories + +#### Workflow Diagram + +```mermaid +flowchart TB + subgraph SonarQube["SonarQube Job"] + CHECKOUT[Checkout Repository
fetch-depth: 0] + AZURE[Azure Login
chef/common-github-actions/.github/actions/azure-login] + FIREWALL[Update Firewall Rule] + SCAN[SonarQube Scan
sonarsource/sonarqube-scan-action] + CLEANUP[Cleanup Firewall Rule] + end + + CHECKOUT --> AZURE + AZURE --> FIREWALL + FIREWALL --> SCAN + SCAN --> CLEANUP + + style SonarQube fill:#fff3e0 +``` + +#### Input Variables + +| Input | Type | Required | Description | +|-------|------|----------|-------------| +| `perform-build` | boolean | No | Whether to perform build | +| `build-profile` | string | No | Build profile | +| `language` | string | No | Programming language | +| `report-unit-test-coverage` | boolean | No | Report test coverage | +| `report-to-atlassian-dashboard` | boolean | No | Report to dashboard | +| `quality-product-name` | string | No | Product name | +| `quality-sonar-app-name` | string | No | Sonar application name | +| `quality-testing-type` | string | No | Testing type | +| `quality-service-name` | string | No | Service name | +| `quality-junit-report` | string | No | JUnit report path | +| `visibility` | string | No | Repository visibility | +| `go-private-modules` | string | No | GOPRIVATE setting | +| `udf1`, `udf2`, `udf3` | string | No | User defined flags | + +--- + +### SBOM Generation + +Generates Software Bill of Materials in multiple formats. + +**Workflow File:** `sbom.yml` + +#### Workflow Diagram + +```mermaid +flowchart TB + subgraph SBOM["SBOM Generation"] + GH_SBOM[GitHub SBOM Export
Dependency Graph API] + BD_SCA[BlackDuck SCA Scan
blackduck-inc/black-duck-security-scan] + MSFT_SBOM[Microsoft SBOM Tool] + LICENSE[License Scout
.license_scout.yml] + end + + subgraph Outputs["Output Artifacts"] + SPDX_JSON[SPDX JSON] + SPDX_CSV[SPDX CSV] + BD_REPORT[BlackDuck Report] + MSFT_REPORT[MSFT SBOM Report] + end + + GH_SBOM --> SPDX_JSON + GH_SBOM --> SPDX_CSV + BD_SCA --> BD_REPORT + MSFT_SBOM --> MSFT_REPORT + + style SBOM fill:#e8f5e9 + style Outputs fill:#fff8e1 +``` + +#### Input Variables + +| Input | Type | Default | Description | +|-------|------|---------|-------------| +| `version` | string | Required | Project version | +| `export-github-sbom` | boolean | `true` | Export GitHub SBOM | +| `perform-blackduck-sca-scan` | boolean | `false` | Run BlackDuck SCA | +| `blackduck-project-group-name` | string | `Chef` | BlackDuck project group | +| `blackduck-project-name` | string | - | BlackDuck project name | +| `generate-msft-sbom` | boolean | `true` | Generate Microsoft SBOM | +| `license_scout` | boolean | `true` | Run license scout | +| `go-private-modules` | string | - | GOPRIVATE setting | +| `blackduck-force-low-accuracy-mode` | boolean | `false` | Force low accuracy mode | +| `run-bundle-install` | boolean | `false` | Run bundle install | +| `language` | string | `ruby` | Project language | + +--- + +### Quality Dashboard + +Reports quality metrics to the Atlassian dashboard. + +**Workflow File:** `irfan-quality-dashboard.yml` + +#### Workflow Diagram + +```mermaid +flowchart TB + subgraph QualityDashboard["Quality Dashboard Job"] + SONAR_REPORT[SonarQube Report
Progress-I360/github-action-reporting/sonarqube] + AUTO_REPORT[Automation Report
Progress-I360/github-action-reporting/automation] + end + + SONAR_REPORT --> AUTO_REPORT + + style QualityDashboard fill:#ede7f6 +``` + +#### Input Variables + +Same as SonarQube inputs - see [SonarQube Input Variables](#input-variables-3). + +--- + +## Required Secrets + +Configure these secrets at the repository or organization level: + +### SonarQube + +| Secret | Description | +|--------|-------------| +| `SONAR_TOKEN` | SonarQube authentication token | +| `SONAR_HOST_URL` | SonarQube server URL (progress.sonar.com) | +| `AKEYLESS_JWT_ID` | For Azure firewall rules (public/internal repos) | + +### BlackDuck Polaris (SAST) + +| Secret | Description | +|--------|-------------| +| `POLARIS_SERVER_URL` | Polaris server URL (https://polaris.blackduck.com) | +| `POLARIS_ACCESS_TOKEN` | Polaris authentication token | + +### BlackDuck SCA + +| Secret | Description | +|--------|-------------| +| `BLACKDUCK_SBOM_URL` | BlackDuck SCA server URL | +| `BLACKDUCK_SCA_TOKEN` | BlackDuck SCA authentication token | + +### Habitat + +| Secret | Description | +|--------|-------------| +| `HAB_PUBLIC_BLDR_PAT` | Habitat Builder personal access token | + +### GitHub + +| Secret | Description | +|--------|-------------| +| `GITHUB_TOKEN` | Automatically provided by GitHub Actions | +| `GH_TOKEN` | For accessing private Go modules | + +--- + +## Configuration Examples + +### Go Project (CLI Application) + +```yaml +name: CI Pipeline + +on: + pull_request: + branches: [ main ] + push: + branches: [ main ] + +jobs: + ci: + uses: chef/common-github-actions/.github/workflows/ci-main-pull-request.yml@v1.0.7 + secrets: inherit + permissions: + id-token: write + contents: read + with: + visibility: ${{ github.event.repository.visibility }} + language: 'go' + version: '1.0.0' + build-profile: 'cli' + + # Code Quality + perform-complexity-checks: true + perform-language-linting: true + + # Security Scans + perform-trufflehog-scan: true + perform-trivy-scan: true + perform-sonarqube-scan: true + + # BlackDuck Polaris + perform-blackduck-polaris: true + polaris-application-name: 'Chef-Chef360' + polaris-project-name: ${{ github.event.repository.name }} + polaris-assessment-mode: 'SAST' + + # Build + build: true + unit-tests: true + + # SBOM + generate-sbom: true + perform-blackduck-sca-scan: true + blackduck-project-group-name: 'Chef-Chef360' +``` + +### Ruby Project (Gem) + +```yaml +name: CI Pipeline + +on: + pull_request: + branches: [ main ] + push: + branches: [ main ] + +jobs: + ci: + uses: chef/common-github-actions/.github/workflows/ci-main-pull-request.yml@v1.0.7 + secrets: inherit + permissions: + id-token: write + contents: read + with: + visibility: ${{ github.event.repository.visibility }} + language: 'ruby' + version: '1.0.0' + + # Code Quality + perform-complexity-checks: true + perform-language-linting: true + + # Security Scans + perform-trufflehog-scan: true + perform-trivy-scan: true + perform-sonarqube-scan: true + + # Build + build: true + unit-tests: true + run-bundle-install: true # For projects without committed Gemfile.lock + + # SBOM + generate-sbom: true + license_scout: true +``` + +### Habitat Package + +```yaml +name: CI Pipeline + +on: + pull_request: + branches: [ main ] + push: + branches: [ main ] + +jobs: + ci: + uses: chef/common-github-actions/.github/workflows/ci-main-pull-request.yml@v1.0.7 + secrets: inherit + permissions: + id-token: write + contents: read + with: + visibility: ${{ github.event.repository.visibility }} + language: 'rust' + + # Security Scans + perform-trufflehog-scan: true + perform-trivy-scan: true + + # Packaging + package-binaries: true + habitat-build: true + publish-habitat-packages: true + publish-habitat-hab_package: 'myorg/mypackage' + publish-habitat-hab_channel: 'stable' + publish-habitat-runner_os: 'ubuntu-latest' + habitat-grype-scan: true + + # SBOM + generate-sbom: true +``` + +### Minimal Security Scan Only + +```yaml +name: Security Scan + +on: + pull_request: + branches: [ main ] + +jobs: + security: + uses: chef/common-github-actions/.github/workflows/ci-main-pull-request.yml@v1.0.7 + secrets: inherit + with: + visibility: ${{ github.event.repository.visibility }} + language: 'go' + + # Disable everything except security scans + perform-complexity-checks: false + perform-language-linting: false + build: false + unit-tests: false + package-binaries: false + habitat-build: false + generate-sbom: false + report-to-atlassian-dashboard: false + + # Enable security scans only + perform-trufflehog-scan: true + perform-trivy-scan: true +``` + +--- + +## Support + +For issues or questions: + +1. Check the [DEV-README.md](.github/workflows/DEV-README.md) for development notes +2. Review the [combined-documentation.md](combined-documentation.md) for detailed tool information +3. Open an issue in this repository + +--- + +## Version History + +| Version | Date | Changes | +|---------|------|---------| +| v1.0.7 | 2025 | Added Polaris configuration options, Go build/test, Habitat Grype scanning | +| v1.0.5 | 2024 | Initial release with core security scanning | diff --git a/combined-documentation.md b/combined-documentation.md new file mode 100644 index 0000000..ffb863e --- /dev/null +++ b/combined-documentation.md @@ -0,0 +1,743 @@ +# CI/CD Security and Quality Scanning Tools - Complete Reference + +This document provides comprehensive information about the security and quality scanning tools configured in the CI/CD pipeline, including their purpose, configuration requirements, and integration details. + +--- + +## Pipeline Overview + +```mermaid +graph TD + Start([Pull Request/Push Event]) --> PreCheck[precompilation-checks] + Start --> Checkout[checkout] + Start --> GenSlug[generate-filename-slug] + + Checkout --> SCC[scc] + Checkout --> LangSpec[language-specific-checks] + Checkout --> LangAgn[language-agnostic-checks] + Checkout --> TruffleHog[run-trufflehog] + Checkout --> Trivy[run-trivy] + Checkout --> Build[ci-build] + Checkout --> Polaris[BlackDuck-Polaris-SAST] + + Build --> SetVer[set-application-version] + Build --> UnitTest[ci-unit-test] + Build --> SonarPub[Sonar-public-repo] + Build --> SonarPriv[Sonar-private-repo] + Build --> SonarInt[Sonar-internal-repo] + Build --> Package[package-binary] + Build --> SBOM[generate-sbom] + + Package --> Habitat[habitat-build] + Habitat --> HabPub[habitat-publish] + HabPub --> GrypeLinux[habitat-grype-scan-linux] + HabPub --> GrypeWin[habitat-grype-scan-windows] + Habitat --> Publish[publish] + + SBOM --> QualDash[quality-dashboard] + + style SCC fill:#e1f5ff + style TruffleHog fill:#ffe1e1 + style Trivy fill:#ffe1e1 + style Polaris fill:#ffe1e1 + style SonarPub fill:#fff4e1 + style SonarPriv fill:#fff4e1 + style SonarInt fill:#fff4e1 + style SBOM fill:#e1ffe1 + style GrypeLinux fill:#ffe1e1 + style GrypeWin fill:#ffe1e1 +``` + +--- + +## Code Quality & Complexity + +### **SCC (Source Code Complexity)** + +**Purpose:** Analyzes source code complexity metrics including lines of code, cyclomatic complexity, and comment ratios across multiple programming languages. + +**What it scans:** +- Lines of code (physical, logical, comments) +- Cyclomatic complexity +- Code structure and organization + +**Reporting:** +- Generates a text output file (default: `scc-complexity.txt`) +- Uploaded as a GitHub Actions artifact +- Used to track code maintainability over time + +#### Job Mapping + +```mermaid +graph LR + A[scc Job] -->|calls| B[scc.yml] + B -->|requires| C[Variables] + + C -->|input| D[outputfilename: string] + + style A fill:#e1f5ff + style B fill:#d4edff +``` + +**Workflow File:** `chef/common-github-actions/.github/workflows/scc.yml` + +**Required Variables:** +- `outputfilename` (string) - Name of the SCC complexity output file artifact, default: 'scc-complexity' + +**Condition:** `inputs.perform-complexity-checks == true` + +--- + +## Language-Specific Analysis + +### **Linting Tools** + +**Purpose:** Perform language-specific code quality checks and enforce coding standards. + +**Supported Languages:** +- **Go**: golangci-lint, staticcheck +- **Ruby**: RuboCop +- **Rust**: Clippy + +**What they scan:** +- Code style violations +- Potential bugs +- Performance issues +- Best practice violations + +**Reporting:** +- Console output in GitHub Actions logs +- Can fail the build based on severity + +#### Job Mapping + +**Workflow File:** Inline implementation in `ci-main-pull-request.yml` + +**Required Variables:** +- `language` (string) - Programming language (go, ruby, rust) +- `go-private-modules` (string) - GOPRIVATE for Go private modules (if language is Go) + +**Condition:** `inputs.perform-language-linting == true` + +--- + +## Secret Scanning + +### **TruffleHog** + +**Purpose:** Scans for accidentally committed secrets, credentials, and sensitive information in source code and git history. + +**What it scans:** +- API keys and tokens +- Passwords +- Private keys +- Database connection strings +- Cloud provider credentials + +**Reporting:** +- Results displayed in GitHub Actions logs +- Can be configured to fail the build if secrets are found +- Integrated findings available through the workflow + +#### Job Mapping + +```mermaid +graph LR + A[run-trufflehog Job] -->|calls| B[trufflehog.yml] + B -->|requires| C[Variables] + + C -->|no inputs| D[None Required] + + style A fill:#ffe1e1 + style B fill:#ffd4d4 +``` + +**Workflow File:** `chef/common-github-actions/.github/workflows/trufflehog.yml` + +**Required Variables:** +- None (inherits secrets automatically) + +**Condition:** `inputs.perform-trufflehog-scan == true` + +--- + +## Vulnerability Scanning + +### **Trivy** + +**Purpose:** Comprehensive security scanner for vulnerabilities in dependencies, container images, and infrastructure as code. + +**What it scans:** +- OS packages and dependencies +- Application dependencies (npm, pip, gem, etc.) +- Container images +- Infrastructure as Code (IaC) misconfigurations + +**Reporting:** +- JSON/SARIF output formats +- Results uploaded as GitHub Actions artifacts +- Integration with GitHub Security tab (if SARIF format enabled) + +#### Job Mapping + +```mermaid +graph LR + A[run-trivy Job] -->|calls| B[trivy.yml] + B -->|requires| C[Variables] + + C -->|input| D[version: string] + + style A fill:#ffe1e1 + style B fill:#ffd4d4 +``` + +**Workflow File:** `chef/common-github-actions/.github/workflows/trivy.yml` + +**Required Variables:** +- `version` (string) - Version of the project, default: '1.0.0' + +**Condition:** `inputs.perform-trivy-scan == true` + +--- + +## Static Application Security Testing (SAST) + +### **BlackDuck Polaris (Coverity)** + +**Purpose:** Enterprise-grade static analysis for identifying security vulnerabilities and code quality issues in source code. + +**What it scans:** +- Security vulnerabilities (CWE/OWASP categories) +- Code quality defects +- Compliance violations +- API misuse + +**Configuration:** +- Application name: Maps to Chef product (e.g., Chef-Chef360, Chef-Habitat) +- Project name: Typically the repository name +- Assessment modes: SAST, CI, or SOURCE_UPLOAD +- Configurable build commands and scan depth + +**Reporting:** +- Results available at: `https://polaris.blackduck.com` +- Project-specific dashboard with vulnerability details +- Can block builds based on policy violations +- SARIF reports can be uploaded to GitHub Security + +#### Job Mapping + +```mermaid +graph LR + A[BlackDuck-Polaris-SAST Job] -->|inline steps| B[Inline Implementation] + B -->|requires| C[Variables] + + C -->|secrets| D[POLARIS_SERVER_URL
POLARIS_ACCESS_TOKEN] + C -->|inputs| E[polaris-application-name
polaris-project-name
polaris-working-directory
polaris-config-path
polaris-coverity-config-path
polaris-coverity-build-command
polaris-coverity-clean-command
polaris-coverity-args
polaris-detect-search-depth
polaris-detect-args
polaris-assessment-mode
wait-for-scan] + + style A fill:#ffe1e1 + style B fill:#ffd4d4 +``` + +**Workflow File:** Inline implementation (no separate workflow) + +**Required Secrets:** +- `POLARIS_SERVER_URL` - BlackDuck Polaris server URL +- `POLARIS_ACCESS_TOKEN` - BlackDuck Polaris access token +- `GITHUB_TOKEN` - GitHub token for authentication + +**Required Variables:** +- `polaris-application-name` (string) - One of: Chef-Agents, Chef-Automate, Chef-Chef360, Chef-Habitat, Chef-Infrastructure-Server, Chef-Shared-Services +- `polaris-project-name` (string) - Typically the repository name + +**Optional Variables (New in 1.0.7):** +- `polaris-working-directory` (string) - Working directory for scan +- `polaris-config-path` (string) - Path to Detect configuration file +- `polaris-coverity-config-path` (string) - Path to Coverity configuration file +- `polaris-coverity-build-command` (string) - Coverity build command +- `polaris-coverity-clean-command` (string) - Coverity clean command +- `polaris-coverity-args` (string) - Additional Coverity arguments +- `polaris-detect-search-depth` (string) - Detect search depth, default: '5' +- `polaris-detect-args` (string) - Additional Detect arguments +- `polaris-assessment-mode` (string) - Assessment mode: SAST, CI, or SOURCE_UPLOAD +- `wait-for-scan` (boolean) - Wait for scan completion, default: true + +**Condition:** `inputs.perform-blackduck-polaris == true` + +--- + +### **SonarQube** + +**Purpose:** Continuous code quality and security inspection platform that identifies bugs, code smells, and security vulnerabilities. + +**What it scans:** +- Security vulnerabilities +- Code smells and maintainability issues +- Code coverage from unit tests +- Duplicate code +- Technical debt + +**Configuration:** +- Separate workflows for public, private, and internal repositories +- Integrates with unit test coverage reports +- Language-specific analysis rules + +**Reporting:** +- Results available at configured SonarQube server (progress.sonar.com) +- Quality Gate status (pass/fail) +- Detailed metrics on code quality, security, and coverage +- Historical trends and project comparison + +#### Job Mapping - Public Repository + +```mermaid +graph LR + A[Sonar-public-repo Job] -->|calls| B[sonarqube-public-repo.yml] + B -->|requires| C[Variables] + + C -->|secrets| D[SONAR_TOKEN
SONAR_HOST_URL
AKEYLESS_JWT_ID] + C -->|inputs| E[perform-build
build-profile
language
report-unit-test-coverage
report-to-atlassian-dashboard
quality-product-name
quality-sonar-app-name
quality-testing-type
quality-service-name
quality-junit-report
visibility
go-private-modules
udf1, udf2, udf3] + + style A fill:#fff4e1 + style B fill:#ffe8c5 +``` + +**Workflow File:** `chef/common-github-actions/.github/workflows/sonarqube-public-repo.yml` + +**Required Secrets:** +- `SONAR_TOKEN` - SonarQube authentication token +- `SONAR_HOST_URL` - SonarQube server URL (progress.sonar.com) +- `AKEYLESS_JWT_ID` - For Azure firewall rules + +**Required Variables:** +- `perform-build` (boolean) - Whether to perform build +- `build-profile` (string) - Build profile, default: 'cli' +- `language` (string) - Programming language +- `report-unit-test-coverage` (boolean) - Report unit test coverage +- `report-to-atlassian-dashboard` (boolean) - Report to QA dashboard +- `quality-product-name` (string) - Product name, default: 'Chef360' +- `quality-sonar-app-name` (string) - Sonar application name +- `quality-testing-type` (string) - Testing type, default: 'Integration' +- `quality-service-name` (string) - Service/repository name +- `quality-junit-report` (string) - Path to JUnit report +- `visibility` (string) - Repository visibility +- `go-private-modules` (string) - GOPRIVATE for Go modules +- `udf1`, `udf2`, `udf3` (string) - User defined flags + +**Condition:** `inputs.perform-sonarqube-scan == true && inputs.visibility == 'public'` + +#### Job Mapping - Private Repository + +```mermaid +graph LR + A[Sonar-private-repo Job] -->|inline steps| B[Inline SonarQube Scan] + B -->|requires| C[Variables] + + C -->|secrets| D[SONAR_TOKEN
SONAR_HOST_URL] + + style A fill:#fff4e1 + style B fill:#ffe8c5 +``` + +**Workflow File:** Inline implementation using `sonarsource/sonarqube-scan-action@v5.3.1` + +**Required Secrets:** +- `SONAR_TOKEN` - SonarQube authentication token +- `SONAR_HOST_URL` - SonarQube server URL + +**Condition:** `inputs.perform-sonarqube-scan == true && inputs.visibility == 'private'` + +#### Job Mapping - Internal Repository + +```mermaid +graph LR + A[Sonar-internal-repo Job] -->|calls| B[sonarqube-internal-repo.yml] + B -->|requires| C[Variables] + + C -->|secrets| D[SONAR_TOKEN
SONAR_HOST_URL
AKEYLESS_JWT_ID] + C -->|inputs| E[Same as public repo] + + style A fill:#fff4e1 + style B fill:#ffe8c5 +``` + +**Workflow File:** `chef/common-github-actions/.github/workflows/sonarqube-internal-repo.yml` + +**Required Variables:** Same as public repository + +**Condition:** `inputs.perform-sonarqube-scan == true && inputs.visibility == 'internal'` + +--- + +## Software Composition Analysis (SCA) + +### **BlackDuck SCA (Sbominator)** + +**Purpose:** Identifies open source components, licenses, and known vulnerabilities in dependencies. + +**What it scans:** +- Open source dependencies +- License compliance +- Known vulnerabilities (CVEs) +- Component versions and updates + +**Configuration:** +- Project group: Maps to Chef product groups +- Project name: Typically repository name +- Requires version specification for accurate tracking + +**Reporting:** +- Results at: `https://progresssoftware.app.blackduck.com` +- SBOM generation in SPDX format +- License compliance reports +- Vulnerability risk analysis +- Policy violation alerts + +#### Job Mapping + +**Note:** BlackDuck SCA is integrated within the SBOM generation workflow (see SBOM Generation section below). + +**Workflow File:** `chef/common-github-actions/.github/workflows/sbom.yml` + +**Required Secrets:** +- `BLACKDUCK_SBOM_URL` - BlackDuck SCA server URL +- `BLACKDUCK_SCA_TOKEN` - BlackDuck SCA authentication token + +**Condition:** `inputs.perform-blackduck-sca-scan == true` (within SBOM workflow) + +--- + +### **Grype (Habitat Package Scanning)** + +**Purpose:** Vulnerability scanner specifically used for scanning built Habitat packages. + +**What it scans:** +- Installed packages within Habitat artifacts +- Known CVEs in package dependencies +- OS-level vulnerabilities + +**Reporting:** +- Text output files uploaded as GitHub Actions artifacts +- Separate scans for Linux and Windows platforms +- Results named: `grype-results-{platform}-{package}.txt` + +#### Job Mapping - Linux + +```mermaid +graph LR + A[habitat-grype-scan-linux Job] -->|inline steps| B[Install Habitat + Grype] + B -->|requires| C[Variables] + + C -->|secrets| D[HAB_PUBLIC_BLDR_PAT] + C -->|inputs| E[publish-habitat-hab_package
publish-habitat-hab_version
publish-habitat-hab_release
publish-habitat-hab_channel
publish-habitat-hab_auth_token] + + style A fill:#ffe1e1 + style B fill:#ffd4d4 +``` + +**Workflow File:** Inline implementation + +**Required Secrets:** +- `HAB_PUBLIC_BLDR_PAT` - Habitat Builder personal access token (fallback) + +**Required Variables:** +- `publish-habitat-hab_package` (string) - Habitat package to scan, default: 'core/nginx' +- `publish-habitat-hab_version` (string) - Package version (optional) +- `publish-habitat-hab_release` (string) - Package release (optional) +- `publish-habitat-hab_channel` (string) - Package channel, default: 'stable' +- `publish-habitat-hab_auth_token` (string) - Auth token (optional, uses secret if not provided) + +**Condition:** `inputs.habitat-grype-scan == true && inputs.publish-habitat-runner_os == 'ubuntu-latest'` + +#### Job Mapping - Windows + +```mermaid +graph LR + A[habitat-grype-scan-windows Job] -->|inline steps| B[Install Habitat + Grype] + B -->|requires| C[Variables] + + C -->|same as Linux| D[Same variables as Linux] + + style A fill:#ffe1e1 + style B fill:#ffd4d4 +``` + +**Workflow File:** Inline implementation + +**Required Variables:** Same as Linux version + +**Condition:** `inputs.habitat-grype-scan == true && inputs.publish-habitat-runner_os == 'windows-latest'` + +--- + +## Software Bill of Materials (SBOM) + +### **GitHub SBOM Export** + +**Purpose:** Generates and exports SPDX-compliant SBOM for dependency tracking. + +**What it includes:** +- All project dependencies +- Component versions +- License information +- Package relationships + +**Reporting:** +- SPDX JSON format +- Uploaded as GitHub Actions artifact +- Can be submitted to BlackDuck SCA for analysis + +#### Job Mapping + +**Note:** GitHub SBOM Export is integrated within the SBOM generation workflow. + +**Condition:** `inputs.export-github-sbom == true` (within SBOM workflow) + +--- + +### **Microsoft SBOM Tool** + +**Purpose:** Alternative SBOM generation using Microsoft's tooling. + +**What it includes:** +- SPDX 2.2 format +- Component inventory +- License data + +**Reporting:** +- JSON artifacts uploaded to workflow +- Integration with supply chain security tools + +#### Job Mapping + +**Note:** Microsoft SBOM Tool is integrated within the SBOM generation workflow. + +**Condition:** `inputs.generate-msft-sbom == true` (within SBOM workflow) + +--- + +### **License Scout** + +**Purpose:** Scans project dependencies for license compliance using `.license_scout.yml` configuration. + +**What it scans:** +- Dependency licenses +- License compatibility +- Compliance violations + +**Reporting:** +- License compliance report +- Violations flagged based on policy + +#### Job Mapping + +**Note:** License Scout is integrated within the SBOM generation workflow. + +**Condition:** `inputs.license_scout == true` (within SBOM workflow) + +--- + +### **SBOM Generation (Combined Workflow)** + +**Purpose:** Orchestrates multiple SBOM generation tools and BlackDuck SCA scanning. + +#### Job Mapping + +```mermaid +graph LR + A[generate-sbom Job] -->|calls| B[sbom.yml] + B -->|requires| C[Variables] + + C -->|secrets| D[BLACKDUCK_SBOM_URL
BLACKDUCK_SCA_TOKEN] + C -->|inputs| E[version
export-github-sbom
perform-blackduck-sca-scan
blackduck-project-group-name
blackduck-project-name
generate-msft-sbom
license_scout
go-private-modules] + + style A fill:#e1ffe1 + style B fill:#c5f5c5 +``` + +**Workflow File:** `chef/common-github-actions/.github/workflows/sbom.yml` + +**Required Secrets:** +- `BLACKDUCK_SBOM_URL` - BlackDuck SCA server URL +- `BLACKDUCK_SCA_TOKEN` - BlackDuck SCA authentication token + +**Required Variables:** +- `version` (string) - Version of the project +- `export-github-sbom` (boolean) - Export SBOM from GitHub, default: true +- `perform-blackduck-sca-scan` (boolean) - Perform BlackDuck SCA scan, default: false +- `blackduck-project-group-name` (string) - BlackDuck project group, default: 'Chef' +- `blackduck-project-name` (string) - BlackDuck project name +- `generate-msft-sbom` (boolean) - Generate Microsoft SBOM, default: true +- `license_scout` (boolean) - Run license scout, default: true +- `go-private-modules` (string) - GOPRIVATE for Go modules + +**Condition:** `inputs.generate-sbom == true` + +--- + +## Quality Dashboard Integration + +### **Atlassian Quality Dashboard** + +**Purpose:** Aggregates quality metrics from multiple sources for centralized reporting. + +**Data Sources:** +- SonarQube metrics +- Unit test results (JUnit format) +- Code coverage data + +**Reported Metrics:** +- Product: Chef-360, Courier, InSpec, etc. +- Service/Repository name +- Testing type: Unit, Integration, e2e, API, Performance, Security +- Quality gate status + +**Reporting:** +- Centralized dashboard (Irfan's QA dashboard) +- Historical trend analysis +- Cross-project comparison + +#### Job Mapping + +```mermaid +graph LR + A[quality-dashboard Job] -->|calls| B[irfan-quality-dashboard.yml] + B -->|requires| C[Variables] + + C -->|inputs| D[perform-build
build-profile
language
report-unit-test-coverage
report-to-atlassian-dashboard
quality-product-name
quality-sonar-app-name
quality-testing-type
quality-service-name
quality-junit-report
visibility
go-private-modules
udf1, udf2, udf3] + + style A fill:#f0e1ff + style B fill:#e0c5ff +``` + +**Workflow File:** `chef/common-github-actions/.github/workflows/irfan-quality-dashboard.yml` + +**Required Variables:** +- `perform-build` (boolean) - Whether build was performed +- `build-profile` (string) - Build profile +- `language` (string) - Programming language +- `report-unit-test-coverage` (boolean) - Report unit test coverage +- `report-to-atlassian-dashboard` (boolean) - Report to dashboard +- `quality-product-name` (string) - Product name (Chef360, Courier, InSpec) +- `quality-sonar-app-name` (string) - Sonar application name +- `quality-testing-type` (string) - Testing type (Unit, Integration, e2e, API, Performance, Security) +- `quality-service-name` (string) - Service/repository name +- `quality-junit-report` (string) - Path to JUnit report +- `visibility` (string) - Repository visibility +- `go-private-modules` (string) - GOPRIVATE for Go modules +- `udf1`, `udf2`, `udf3` (string) - User defined flags + +**Condition:** `inputs.report-to-atlassian-dashboard == true` + +--- + +## Container Security + +### **Docker Scan** + +**Purpose:** Scans Dockerfiles and built container images for vulnerabilities and misconfigurations. + +**Tools Used:** +- Docker Scout +- Trivy (can also scan containers) + +**What it scans:** +- Base image vulnerabilities +- Layer-specific issues +- Dockerfile best practices +- Container configuration + +**Reporting:** +- Results in GitHub Actions logs +- Uploaded artifacts for detailed analysis + +#### Job Mapping + +**Workflow File:** Inline implementation in `ci-main-pull-request.yml` + +**Condition:** `inputs.perform-docker-scan == true` + +--- + +## Pipeline Execution Flow + +```mermaid +sequenceDiagram + participant PR as Pull Request + participant Pre as Pre-checks + participant Sec as Security Scans + participant Build as Build & Test + participant SAST as SAST Scans + participant Pkg as Package + participant SBOM as SBOM & SCA + participant Dash as Dashboard + + PR->>Pre: Trigger workflow + Pre->>Pre: checkout, complexity checks, linting + Pre->>Sec: TruffleHog, Trivy + Sec->>Build: Build application, run unit tests + Build->>SAST: SonarQube, BlackDuck Polaris + Build->>Pkg: Package binaries, Habitat + Pkg->>Pkg: Grype scan Habitat packages + Build->>SBOM: Generate SBOM, BlackDuck SCA + SBOM->>Dash: Report metrics to Quality Dashboard +``` + +--- + +## Summary Table + +| Tool | Type | Primary Use | Workflow File | Output Location | +|------|------|-------------|---------------|-----------------| +| SCC | Complexity | Code metrics | scc.yml | GitHub Artifacts | +| TruffleHog | Secret Scan | Credential detection | trufflehog.yml | Actions Logs | +| Trivy | Vulnerability | Dependencies & containers | trivy.yml | GitHub Artifacts/Security | +| BlackDuck Polaris | SAST | Security vulnerabilities | Inline | polaris.blackduck.com | +| SonarQube | SAST/Quality | Code quality & security | sonarqube-*-repo.yml | progress.sonar.com | +| BlackDuck SCA | SCA | License & vulnerabilities | sbom.yml | progresssoftware.app.blackduck.com | +| Grype | Vulnerability | Habitat packages | Inline | GitHub Artifacts | +| SBOM Tools | Compliance | Dependency inventory | sbom.yml | GitHub Artifacts | +| Quality Dashboard | Reporting | Aggregated metrics | irfan-quality-dashboard.yml | Atlassian Dashboard | + +--- + +## Quick Reference: Required Secrets + +| Secret | Used By | Purpose | +|--------|---------|---------| +| SONAR_TOKEN | SonarQube | Authentication to SonarQube server | +| SONAR_HOST_URL | SonarQube | SonarQube server URL | +| AKEYLESS_JWT_ID | SonarQube (public/internal) | Azure firewall rules | +| POLARIS_SERVER_URL | BlackDuck Polaris | Polaris server URL | +| POLARIS_ACCESS_TOKEN | BlackDuck Polaris | Polaris authentication | +| BLACKDUCK_SBOM_URL | BlackDuck SCA | BlackDuck SCA server URL | +| BLACKDUCK_SCA_TOKEN | BlackDuck SCA | BlackDuck SCA authentication | +| HAB_PUBLIC_BLDR_PAT | Grype/Habitat | Habitat Builder access token | +| GITHUB_TOKEN | Multiple | GitHub API authentication | + +--- + +## Legend + +- 🔵 **Blue** - Complexity/Code Quality +- 🔴 **Red** - Security Scans +- 🟡 **Yellow** - SAST Tools +- 🟢 **Green** - SBOM/SCA +- 🟣 **Purple** - Reporting/Dashboard + +--- + +## Notes + +1. **Inline vs Reusable Workflows**: Some jobs call reusable workflows (`.yml` files), while others execute steps inline within the main workflow. + +2. **Conditional Execution**: Most jobs have conditions based on input flags (e.g., `inputs.perform-trufflehog-scan`). + +3. **Secrets Management**: Secrets are inherited via `secrets: inherit` or explicitly passed for specific actions. + +4. **Dependencies**: Jobs use `needs:` to establish execution order (e.g., most scans need `checkout` first). + +5. **Parallel Execution**: Jobs without dependencies can run in parallel (e.g., TruffleHog and Trivy can run simultaneously). + +6. **Version Detection**: The pipeline supports dynamic version detection from files, GitHub tags, or releases using `detect-version-source-type` and `detect-version-source-parameter` inputs. + +7. **Language Support**: The pipeline supports multiple languages (Go, Ruby, Rust, JavaScript, TypeScript, Python, Java, C#, PHP) with language-specific build and test configurations. From 194c03bb190be593bd8072a471a1c7a60552fe5d Mon Sep 17 00:00:00 2001 From: Sean Simmons Date: Fri, 20 Feb 2026 09:35:40 -0500 Subject: [PATCH 2/4] updating documentaiton Signed-off-by: Sean Simmons --- HOW-TO-USE.md | 828 +++--------------- ...-documentation.md => PIPELINE-REFERENCE.md | 0 README.md | 9 + 3 files changed, 112 insertions(+), 725 deletions(-) rename combined-documentation.md => PIPELINE-REFERENCE.md (100%) diff --git a/HOW-TO-USE.md b/HOW-TO-USE.md index 29b0a71..47beadd 100644 --- a/HOW-TO-USE.md +++ b/HOW-TO-USE.md @@ -2,6 +2,8 @@ This guide explains how to use the reusable workflows from the `chef/common-github-actions` repository in your own projects. +> **📖 For detailed pipeline architecture, tool reference, and mermaid diagrams, see [PIPELINE-REFERENCE.md](PIPELINE-REFERENCE.md)** + --- ## Table of Contents @@ -9,18 +11,9 @@ This guide explains how to use the reusable workflows from the `chef/common-gith - [Quick Start](#quick-start) - [Versioning with Tags](#versioning-with-tags) - [Available Workflows](#available-workflows) -- [CI/CD Pipeline Architecture](#cicd-pipeline-architecture) -- [Workflow Reference](#workflow-reference) - - [CI Main Pull Request](#ci-main-pull-request) - - [Create Release Tag](#create-release-tag) - - [SCC (Source Code Complexity)](#scc-source-code-complexity) - - [TruffleHog (Secret Scanning)](#trufflehog-secret-scanning) - - [Trivy (Vulnerability Scanning)](#trivy-vulnerability-scanning) - - [SonarQube (SAST)](#sonarqube-sast) - - [SBOM Generation](#sbom-generation) - - [Quality Dashboard](#quality-dashboard) - [Required Secrets](#required-secrets) - [Configuration Examples](#configuration-examples) +- [Input Reference](#input-reference) --- @@ -46,6 +39,7 @@ permissions: jobs: call-ci-main-pr-check-pipeline: + # Pin to a specific version for stability uses: chef/common-github-actions/.github/workflows/ci-main-pull-request.yml@v1.0.7 secrets: inherit permissions: @@ -63,16 +57,7 @@ jobs: ### Step 2: Configure Required Secrets -Ensure your repository or organization has the following secrets configured: - -| Secret | Purpose | -|--------|---------| -| `SONAR_TOKEN` | SonarQube authentication | -| `SONAR_HOST_URL` | SonarQube server URL | -| `POLARIS_ACCESS_TOKEN` | BlackDuck Polaris authentication | -| `POLARIS_SERVER_URL` | BlackDuck Polaris server URL | -| `BLACKDUCK_SCA_TOKEN` | BlackDuck SCA authentication | -| `BLACKDUCK_SBOM_URL` | BlackDuck SCA server URL | +Ensure your repository or organization has the required secrets configured. See [Required Secrets](#required-secrets) below. ### Step 3: Add sonar-project.properties @@ -107,20 +92,15 @@ uses: chef/common-github-actions/.github/workflows/ci-main-pull-request.yml@main Tags follow semantic versioning: `v{MAJOR}.{MINOR}.{PATCH}` -- **MAJOR**: Breaking changes -- **MINOR**: New features, backward compatible -- **PATCH**: Bug fixes, backward compatible +| Bump Type | When to Use | +|-----------|-------------| +| **MAJOR** | Breaking changes | +| **MINOR** | New features, backward compatible | +| **PATCH** | Bug fixes, backward compatible | -### Create Release Tag Workflow +### Automatic Tagging -When code is merged to `main` in `common-github-actions`, a new tag is automatically created. You can also trigger manual tag creation: - -```yaml -# Manual tag creation with version bump -workflow_dispatch: - inputs: - version_bump: 'minor' # major, minor, or patch -``` +When code is merged to `main` in `common-github-actions`, a new patch tag is automatically created via the `create-release-tag.yml` workflow. Manual version bumps can be triggered via workflow dispatch. --- @@ -138,633 +118,7 @@ workflow_dispatch: | SBOM | Software Bill of Materials | `sbom.yml` | | Quality Dashboard | Atlassian quality reporting | `irfan-quality-dashboard.yml` | ---- - -## CI/CD Pipeline Architecture - -### Complete Pipeline Flow - -```mermaid -flowchart TB - subgraph Trigger["🚀 Trigger Events"] - PR[Pull Request] - Push[Push to main/release] - Manual[Manual Dispatch] - end - - subgraph PreChecks["📋 Pre-compilation Checks"] - direction TB - PC[precompilation-checks] - CO[checkout] - PC --> |"detect custom properties"| ENV[Set Environment] - end - - subgraph CodeQuality["📊 Code Quality"] - direction TB - SCC[scc.yml
Source Code Complexity] - LSC[language-specific-checks
Linting] - LAC[language-agnostic-checks
OWASP] - end - - subgraph SecurityScans["🔒 Security Scans"] - direction TB - TH[trufflehog.yml
Secret Scanning] - TV[trivy.yml
Vulnerability Scan] - end - - subgraph BuildTest["🔨 Build & Test"] - direction TB - BUILD[ci-build
Compilation] - UT[ci-unit-test
Unit Tests] - VER[set-application-version] - end - - subgraph SAST["🛡️ SAST Analysis"] - direction TB - SONAR_PUB[Sonar-public-repo] - SONAR_PRIV[Sonar-private-repo] - SONAR_INT[Sonar-internal-repo] - POLARIS[BlackDuck-Polaris-SAST] - end - - subgraph Packaging["📦 Packaging"] - direction TB - PKG[package-binary] - HAB_BUILD[habitat-build] - HAB_PUB[habitat-publish] - GRYPE_LIN[habitat-grype-scan-linux] - GRYPE_WIN[habitat-grype-scan-windows] - PUB[publish] - end - - subgraph SBOM_SCA["📋 SBOM & SCA"] - direction TB - SBOM[sbom.yml
SBOM Generation] - SCA[BlackDuck SCA] - MSFT[Microsoft SBOM] - LICENSE[License Scout] - end - - subgraph Reporting["📈 Reporting"] - direction TB - DASH[quality-dashboard
Atlassian Dashboard] - end - - Trigger --> PreChecks - PreChecks --> CO - CO --> CodeQuality - CO --> SecurityScans - CO --> BuildTest - CO --> POLARIS - - BuildTest --> SAST - BuildTest --> Packaging - BuildTest --> SBOM_SCA - - HAB_BUILD --> HAB_PUB - HAB_PUB --> GRYPE_LIN - HAB_PUB --> GRYPE_WIN - HAB_BUILD --> PUB - - SBOM_SCA --> Reporting - - style Trigger fill:#e1f5fe - style PreChecks fill:#f3e5f5 - style CodeQuality fill:#e8f5e9 - style SecurityScans fill:#ffebee - style BuildTest fill:#fff3e0 - style SAST fill:#fce4ec - style Packaging fill:#e0f2f1 - style SBOM_SCA fill:#f1f8e9 - style Reporting fill:#ede7f6 -``` - -### Nested Workflow Dependencies - -```mermaid -flowchart LR - subgraph Main["ci-main-pull-request.yml"] - direction TB - M_START((Start)) - M_PRE[Pre-checks] - M_CHECKOUT[Checkout] - M_BUILD[Build] - M_END((End)) - end - - subgraph External["Reusable Workflows"] - direction TB - E_SCC["scc.yml"] - E_TH["trufflehog.yml"] - E_TV["trivy.yml"] - E_SONAR_PUB["sonarqube-public-repo.yml"] - E_SONAR_INT["sonarqube-internal-repo.yml"] - E_SBOM["sbom.yml"] - E_QD["irfan-quality-dashboard.yml"] - end - - subgraph Actions["Composite Actions"] - direction TB - A_AZURE["azure-login"] - A_FIREWALL["update-firewall-rule"] - A_GRYPE["chef-download-grype-snapshot"] - end - - M_CHECKOUT --> E_SCC - M_CHECKOUT --> E_TH - M_CHECKOUT --> E_TV - M_BUILD --> E_SONAR_PUB - M_BUILD --> E_SONAR_INT - M_BUILD --> E_SBOM - E_SBOM --> E_QD - - E_SONAR_PUB --> A_AZURE - E_SONAR_INT --> A_AZURE - A_AZURE --> A_FIREWALL - - style Main fill:#e3f2fd - style External fill:#fff8e1 - style Actions fill:#fce4ec -``` - ---- - -## Workflow Reference - -### CI Main Pull Request - -The main CI workflow that orchestrates all security and quality checks. - -**Workflow File:** `ci-main-pull-request.yml` - -#### Input Variables - -```mermaid -flowchart TB - subgraph Required["Required Inputs"] - visibility["visibility
(public/private/internal)"] - language["language
(go/ruby/rust)"] - end - - subgraph Version["Version Configuration"] - version["version
default: 1.0.0"] - detect_type["detect-version-source-type
(none/file/github-tag/github-release)"] - detect_param["detect-version-source-parameter"] - end - - subgraph CodeQuality["Code Quality Flags"] - complexity["perform-complexity-checks
default: true"] - linting["perform-language-linting
default: true"] - scc_output["scc-output-filename
default: scc-complexity"] - end - - subgraph Security["Security Scan Flags"] - trufflehog["perform-trufflehog-scan
default: true"] - trivy["perform-trivy-scan
default: true"] - polaris["perform-blackduck-polaris
default: false"] - sonar["perform-sonarqube-scan
default: true"] - docker["perform-docker-scan
default: false"] - end - - subgraph Polaris["Polaris Configuration"] - pol_app["polaris-application-name"] - pol_proj["polaris-project-name"] - pol_work["polaris-working-directory"] - pol_mode["polaris-assessment-mode
(SAST/CI/SOURCE_UPLOAD)"] - pol_wait["wait-for-scan
default: true"] - end - - subgraph Build["Build Configuration"] - build["build
default: true"] - build_profile["build-profile
default: cli"] - unit_tests["unit-tests
default: true"] - unit_output["unit-test-output-path"] - unit_cmd["unit-test-command-override"] - end - - subgraph Habitat["Habitat Configuration"] - hab_build["habitat-build
default: true"] - hab_publish["publish-habitat-packages
default: false"] - hab_pkg["publish-habitat-hab_package"] - hab_ver["publish-habitat-hab_version"] - hab_rel["publish-habitat-hab_release"] - hab_ch["publish-habitat-hab_channel
default: stable"] - hab_os["publish-habitat-runner_os
default: ubuntu-latest"] - hab_grype["habitat-grype-scan
default: false"] - end - - subgraph SBOM["SBOM Configuration"] - gen_sbom["generate-sbom
default: true"] - gh_sbom["export-github-sbom
default: true"] - msft_sbom["generate-msft-sbom
default: true"] - license["license_scout
default: true"] - bd_sca["perform-blackduck-sca-scan
default: false"] - bd_group["blackduck-project-group-name
default: Chef"] - bd_proj["blackduck-project-name"] - end - - subgraph Quality["Quality Dashboard"] - report_dash["report-to-atlassian-dashboard
default: true"] - report_cov["report-unit-test-coverage
default: true"] - q_prod["quality-product-name"] - q_sonar["quality-sonar-app-name"] - q_type["quality-testing-type"] - q_svc["quality-service-name"] - q_junit["quality-junit-report"] - end - - style Required fill:#ffcdd2 - style Version fill:#c8e6c9 - style CodeQuality fill:#bbdefb - style Security fill:#ffecb3 - style Polaris fill:#f8bbd9 - style Build fill:#d1c4e9 - style Habitat fill:#b2dfdb - style SBOM fill:#c5cae9 - style Quality fill:#dcedc8 -``` - -#### Complete Input Reference - -| Input | Type | Default | Description | -|-------|------|---------|-------------| -| `application` | string | - | Application from repository custom properties | -| `visibility` | string | `public` | Repository visibility (public/private/internal) | -| `go-private-modules` | string | `github.com/progress-platform-services/*` | GOPRIVATE for Go modules | -| `version` | string | `1.0.0` | Project version | -| `detect-version-source-type` | string | `none` | Version detection method | -| `detect-version-source-parameter` | string | - | Parameter for version detection | -| `language` | string | `ruby` | Build language (go/ruby/rust) | -| `perform-complexity-checks` | boolean | `true` | Run SCC complexity checks | -| `scc-output-filename` | string | `scc-complexity` | SCC output filename | -| `perform-language-linting` | boolean | `true` | Run language-specific linting | -| `perform-trufflehog-scan` | boolean | `true` | Run TruffleHog secret scan | -| `perform-trivy-scan` | boolean | `true` | Run Trivy vulnerability scan | -| `build` | boolean | `true` | Run CI build | -| `build-profile` | string | `cli` | Build profile | -| `unit-tests` | boolean | `true` | Run unit tests | -| `unit-test-output-path` | string | `test/unittest` | Unit test output path | -| `unit-test-command-override` | string | - | Custom unit test command | -| `perform-blackduck-polaris` | boolean | `false` | Run BlackDuck Polaris SAST | -| `polaris-application-name` | string | - | Polaris application name | -| `polaris-project-name` | string | `${{ github.event.repository.name }}` | Polaris project name | -| `polaris-working-directory` | string | `.` | Polaris working directory | -| `polaris-config-path` | string | - | Detect configuration file path | -| `polaris-coverity-config-path` | string | - | Coverity configuration file path | -| `polaris-coverity-build-command` | string | `go build` | Coverity build command | -| `polaris-coverity-clean-command` | string | `go clean` | Coverity clean command | -| `polaris-coverity-args` | string | - | Additional Coverity arguments | -| `polaris-detect-search-depth` | string | - | Detect search depth | -| `polaris-detect-args` | string | - | Additional Detect arguments | -| `polaris-assessment-mode` | string | `CI` | Assessment mode (SAST/CI/SOURCE_UPLOAD) | -| `wait-for-scan` | boolean | `true` | Wait for scan completion | -| `perform-sonarqube-scan` | boolean | `true` | Run SonarQube scan | -| `perform-docker-scan` | boolean | `false` | Run Docker scan | -| `report-unit-test-coverage` | boolean | `true` | Report unit test coverage | -| `report-to-atlassian-dashboard` | boolean | `true` | Report to quality dashboard | -| `quality-product-name` | string | `Chef360` | Product name for reporting | -| `quality-sonar-app-name` | string | `YourSonarAppName` | Sonar application name | -| `quality-testing-type` | string | `Integration` | Testing type | -| `quality-service-name` | string | `YourServiceOrRepoName` | Service name | -| `quality-junit-report` | string | `path/to/junit/report` | JUnit report path | -| `package-binaries` | boolean | `true` | Package binaries | -| `habitat-build` | boolean | `true` | Create Habitat packages | -| `publish-habitat-packages` | boolean | `false` | Publish Habitat packages | -| `publish-habitat-hab_package` | string | `core/nginx` | Habitat package name | -| `publish-habitat-hab_version` | string | - | Habitat package version | -| `publish-habitat-hab_release` | string | - | Habitat package release | -| `publish-habitat-hab_channel` | string | `stable` | Habitat channel | -| `publish-habitat-hab_auth_token` | string | - | Habitat auth token | -| `publish-habitat-runner_os` | string | `ubuntu-latest` | Habitat runner OS | -| `habitat-grype-scan` | boolean | `false` | Scan Habitat packages with Grype | -| `publish-packages` | boolean | `true` | Publish packages | -| `generate-sbom` | boolean | `true` | Generate SBOM | -| `export-github-sbom` | boolean | `true` | Export GitHub SBOM | -| `generate-msft-sbom` | boolean | `true` | Generate Microsoft SBOM | -| `license_scout` | boolean | `true` | Run license scout | -| `perform-blackduck-sca-scan` | boolean | `false` | Run BlackDuck SCA scan | -| `blackduck-project-group-name` | string | `Chef` | BlackDuck project group | -| `blackduck-project-name` | string | `${{ github.event.repository.name }}` | BlackDuck project name | -| `blackduck-force-low-accuracy-mode` | boolean | `false` | Force low accuracy mode | -| `run-bundle-install` | boolean | `false` | Run bundle install before scanning | -| `udf1` | string | `default` | User defined flag 1 | -| `udf2` | string | `default` | User defined flag 2 | -| `udf3` | string | `default` | User defined flag 3 | - ---- - -### Create Release Tag - -Automatically creates a git tag when code is merged to main. - -**Workflow File:** `create-release-tag.yml` - -#### Workflow Diagram - -```mermaid -flowchart TB - subgraph Trigger["Trigger"] - PUSH[Push to main] - MANUAL[Manual Dispatch] - end - - subgraph CreateTag["create-tag Job"] - CHECKOUT[Checkout
fetch-depth: 0] - GET_TAG[Get Latest Tag
git describe --tags] - CALC_VER[Calculate New Version
major/minor/patch] - CHECK_EXISTS[Check if Tag Exists] - CREATE[Create & Push Tag
git tag -a] - SUMMARY[Output Summary] - end - - subgraph CreateRelease["create-release Job"] - CHECKOUT2[Checkout] - GEN_NOTES[Generate Release Notes
git log] - CREATE_REL[Create GitHub Release
softprops/action-gh-release] - end - - Trigger --> CHECKOUT - CHECKOUT --> GET_TAG - GET_TAG --> CALC_VER - CALC_VER --> CHECK_EXISTS - CHECK_EXISTS -->|not exists| CREATE - CREATE --> SUMMARY - SUMMARY --> CHECKOUT2 - CHECKOUT2 --> GEN_NOTES - GEN_NOTES --> CREATE_REL - - style Trigger fill:#e1f5fe - style CreateTag fill:#e8f5e9 - style CreateRelease fill:#fff3e0 -``` - -#### Input Variables - -| Input | Type | Default | Description | -|-------|------|---------|-------------| -| `version_bump` | choice | `patch` | Version bump type (major/minor/patch) | -| `custom_version` | string | - | Custom version (overrides version_bump) | - -#### Usage Example - -```yaml -name: Create Release Tag - -on: - push: - branches: [ main ] - workflow_dispatch: - inputs: - version_bump: - description: 'Version bump type' - required: true - default: 'patch' - type: choice - options: [major, minor, patch] - -permissions: - contents: write - -jobs: - create-tag: - uses: chef/common-github-actions/.github/workflows/create-release-tag.yml@main - secrets: inherit - permissions: - contents: write - with: - version_bump: ${{ inputs.version_bump || 'patch' }} -``` - ---- - -### SCC (Source Code Complexity) - -Generates source code complexity metrics using SCC. - -**Workflow File:** `scc.yml` - -#### Workflow Diagram - -```mermaid -flowchart TB - subgraph SCC["scc Job"] - CHECKOUT[Checkout Repository] - INSTALL[Install SCC CLI
go install github.com/boyter/scc/v3@latest] - RUN[Run SCC Analysis] - UPLOAD_TXT[Upload TXT Artifact] - UPLOAD_JSON[Upload JSON Artifact] - UPLOAD_HTML[Upload HTML Artifact] - end - - CHECKOUT --> INSTALL - INSTALL --> RUN - RUN --> UPLOAD_TXT - RUN --> UPLOAD_JSON - RUN --> UPLOAD_HTML - - style SCC fill:#e8f5e9 -``` - -#### Input Variables - -| Input | Type | Default | Description | -|-------|------|---------|-------------| -| `outputfilename` | string | `scc-complexity` | Name of output file (without extension) | - -#### Output Artifacts - -- `{repo}-{branch}-{timestamp}-scc-complexity.txt` - Tabular format -- `{repo}-{branch}-{timestamp}-scc-complexity.json` - JSON detailed format -- `{repo}-{branch}-{timestamp}-scc-complexity.html` - HTML detailed format - ---- - -### TruffleHog (Secret Scanning) - -Scans for accidentally committed secrets in the repository. - -**Workflow File:** `trufflehog.yml` - -#### Workflow Diagram - -```mermaid -flowchart TB - subgraph TruffleHog["Trufflehog Job"] - CHECKOUT[Checkout Repository
fetch-depth: 0] - SCAN[TruffleHog Scan
trufflesecurity/trufflehog@main] - end - - CHECKOUT --> SCAN - - style TruffleHog fill:#ffebee -``` - -#### Input Variables - -None - this workflow has no required inputs. - ---- - -### Trivy (Vulnerability Scanning) - -Scans for vulnerabilities in dependencies. - -**Workflow File:** `trivy.yml` - -#### Workflow Diagram - -```mermaid -flowchart TB - subgraph Trivy["trivy Job"] - CHECKOUT[Checkout Repository] - GEN_PREFIX[Generate Filename Prefix] - SCAN_JSON[Trivy Scan - JSON Output] - UPLOAD_JSON[Upload JSON Artifact] - SCAN_TABLE[Trivy Scan - Table Output] - UPLOAD_TABLE[Upload Table Artifact] - end - - CHECKOUT --> GEN_PREFIX - GEN_PREFIX --> SCAN_JSON - SCAN_JSON --> UPLOAD_JSON - UPLOAD_JSON --> SCAN_TABLE - SCAN_TABLE --> UPLOAD_TABLE - - style Trivy fill:#ffebee -``` - -#### Input Variables - -| Input | Type | Default | Description | -|-------|------|---------|-------------| -| `outputfilename` | string | `trivy-output.json` | Output filename | -| `version` | string | `1.0.0` | Project version | - ---- - -### SonarQube (SAST) - -Static Application Security Testing using SonarQube. - -**Workflow Files:** -- `sonarqube-public-repo.yml` - For public repositories -- `sonarqube-internal-repo.yml` - For internal repositories -- Inline implementation for private repositories - -#### Workflow Diagram - -```mermaid -flowchart TB - subgraph SonarQube["SonarQube Job"] - CHECKOUT[Checkout Repository
fetch-depth: 0] - AZURE[Azure Login
chef/common-github-actions/.github/actions/azure-login] - FIREWALL[Update Firewall Rule] - SCAN[SonarQube Scan
sonarsource/sonarqube-scan-action] - CLEANUP[Cleanup Firewall Rule] - end - - CHECKOUT --> AZURE - AZURE --> FIREWALL - FIREWALL --> SCAN - SCAN --> CLEANUP - - style SonarQube fill:#fff3e0 -``` - -#### Input Variables - -| Input | Type | Required | Description | -|-------|------|----------|-------------| -| `perform-build` | boolean | No | Whether to perform build | -| `build-profile` | string | No | Build profile | -| `language` | string | No | Programming language | -| `report-unit-test-coverage` | boolean | No | Report test coverage | -| `report-to-atlassian-dashboard` | boolean | No | Report to dashboard | -| `quality-product-name` | string | No | Product name | -| `quality-sonar-app-name` | string | No | Sonar application name | -| `quality-testing-type` | string | No | Testing type | -| `quality-service-name` | string | No | Service name | -| `quality-junit-report` | string | No | JUnit report path | -| `visibility` | string | No | Repository visibility | -| `go-private-modules` | string | No | GOPRIVATE setting | -| `udf1`, `udf2`, `udf3` | string | No | User defined flags | - ---- - -### SBOM Generation - -Generates Software Bill of Materials in multiple formats. - -**Workflow File:** `sbom.yml` - -#### Workflow Diagram - -```mermaid -flowchart TB - subgraph SBOM["SBOM Generation"] - GH_SBOM[GitHub SBOM Export
Dependency Graph API] - BD_SCA[BlackDuck SCA Scan
blackduck-inc/black-duck-security-scan] - MSFT_SBOM[Microsoft SBOM Tool] - LICENSE[License Scout
.license_scout.yml] - end - - subgraph Outputs["Output Artifacts"] - SPDX_JSON[SPDX JSON] - SPDX_CSV[SPDX CSV] - BD_REPORT[BlackDuck Report] - MSFT_REPORT[MSFT SBOM Report] - end - - GH_SBOM --> SPDX_JSON - GH_SBOM --> SPDX_CSV - BD_SCA --> BD_REPORT - MSFT_SBOM --> MSFT_REPORT - - style SBOM fill:#e8f5e9 - style Outputs fill:#fff8e1 -``` - -#### Input Variables - -| Input | Type | Default | Description | -|-------|------|---------|-------------| -| `version` | string | Required | Project version | -| `export-github-sbom` | boolean | `true` | Export GitHub SBOM | -| `perform-blackduck-sca-scan` | boolean | `false` | Run BlackDuck SCA | -| `blackduck-project-group-name` | string | `Chef` | BlackDuck project group | -| `blackduck-project-name` | string | - | BlackDuck project name | -| `generate-msft-sbom` | boolean | `true` | Generate Microsoft SBOM | -| `license_scout` | boolean | `true` | Run license scout | -| `go-private-modules` | string | - | GOPRIVATE setting | -| `blackduck-force-low-accuracy-mode` | boolean | `false` | Force low accuracy mode | -| `run-bundle-install` | boolean | `false` | Run bundle install | -| `language` | string | `ruby` | Project language | - ---- - -### Quality Dashboard - -Reports quality metrics to the Atlassian dashboard. - -**Workflow File:** `irfan-quality-dashboard.yml` - -#### Workflow Diagram - -```mermaid -flowchart TB - subgraph QualityDashboard["Quality Dashboard Job"] - SONAR_REPORT[SonarQube Report
Progress-I360/github-action-reporting/sonarqube] - AUTO_REPORT[Automation Report
Progress-I360/github-action-reporting/automation] - end - - SONAR_REPORT --> AUTO_REPORT - - style QualityDashboard fill:#ede7f6 -``` - -#### Input Variables - -Same as SonarQube inputs - see [SonarQube Input Variables](#input-variables-3). +> **See [PIPELINE-REFERENCE.md](PIPELINE-REFERENCE.md) for detailed documentation on each tool, including workflow diagrams and job mappings.** --- @@ -772,40 +126,17 @@ Same as SonarQube inputs - see [SonarQube Input Variables](#input-variables-3). Configure these secrets at the repository or organization level: -### SonarQube - -| Secret | Description | -|--------|-------------| -| `SONAR_TOKEN` | SonarQube authentication token | -| `SONAR_HOST_URL` | SonarQube server URL (progress.sonar.com) | -| `AKEYLESS_JWT_ID` | For Azure firewall rules (public/internal repos) | - -### BlackDuck Polaris (SAST) - -| Secret | Description | -|--------|-------------| -| `POLARIS_SERVER_URL` | Polaris server URL (https://polaris.blackduck.com) | -| `POLARIS_ACCESS_TOKEN` | Polaris authentication token | - -### BlackDuck SCA - -| Secret | Description | -|--------|-------------| -| `BLACKDUCK_SBOM_URL` | BlackDuck SCA server URL | -| `BLACKDUCK_SCA_TOKEN` | BlackDuck SCA authentication token | - -### Habitat - -| Secret | Description | -|--------|-------------| -| `HAB_PUBLIC_BLDR_PAT` | Habitat Builder personal access token | - -### GitHub - -| Secret | Description | -|--------|-------------| -| `GITHUB_TOKEN` | Automatically provided by GitHub Actions | -| `GH_TOKEN` | For accessing private Go modules | +| Secret | Used By | Purpose | +|--------|---------|---------| +| `SONAR_TOKEN` | SonarQube | Authentication token | +| `SONAR_HOST_URL` | SonarQube | Server URL (progress.sonar.com) | +| `AKEYLESS_JWT_ID` | SonarQube | Azure firewall rules (public/internal) | +| `POLARIS_SERVER_URL` | BlackDuck Polaris | Server URL | +| `POLARIS_ACCESS_TOKEN` | BlackDuck Polaris | Authentication token | +| `BLACKDUCK_SBOM_URL` | BlackDuck SCA | Server URL | +| `BLACKDUCK_SCA_TOKEN` | BlackDuck SCA | Authentication token | +| `HAB_PUBLIC_BLDR_PAT` | Habitat/Grype | Builder access token | +| `GH_TOKEN` | Go modules | Private module access | --- @@ -863,14 +194,6 @@ jobs: ### Ruby Project (Gem) ```yaml -name: CI Pipeline - -on: - pull_request: - branches: [ main ] - push: - branches: [ main ] - jobs: ci: uses: chef/common-github-actions/.github/workflows/ci-main-pull-request.yml@v1.0.7 @@ -883,21 +206,16 @@ jobs: language: 'ruby' version: '1.0.0' - # Code Quality perform-complexity-checks: true perform-language-linting: true - - # Security Scans perform-trufflehog-scan: true perform-trivy-scan: true perform-sonarqube-scan: true - # Build build: true unit-tests: true run-bundle-install: true # For projects without committed Gemfile.lock - # SBOM generate-sbom: true license_scout: true ``` @@ -905,14 +223,6 @@ jobs: ### Habitat Package ```yaml -name: CI Pipeline - -on: - pull_request: - branches: [ main ] - push: - branches: [ main ] - jobs: ci: uses: chef/common-github-actions/.github/workflows/ci-main-pull-request.yml@v1.0.7 @@ -924,7 +234,6 @@ jobs: visibility: ${{ github.event.repository.visibility }} language: 'rust' - # Security Scans perform-trufflehog-scan: true perform-trivy-scan: true @@ -934,22 +243,14 @@ jobs: publish-habitat-packages: true publish-habitat-hab_package: 'myorg/mypackage' publish-habitat-hab_channel: 'stable' - publish-habitat-runner_os: 'ubuntu-latest' habitat-grype-scan: true - # SBOM generate-sbom: true ``` ### Minimal Security Scan Only ```yaml -name: Security Scan - -on: - pull_request: - branches: [ main ] - jobs: security: uses: chef/common-github-actions/.github/workflows/ci-main-pull-request.yml@v1.0.7 @@ -975,12 +276,89 @@ jobs: --- +## Input Reference + +### Core Inputs + +| Input | Type | Default | Description | +|-------|------|---------|-------------| +| `visibility` | string | `public` | Repository visibility (public/private/internal) | +| `language` | string | `ruby` | Build language (go/ruby/rust) | +| `version` | string | `1.0.0` | Project version | +| `go-private-modules` | string | `github.com/progress-platform-services/*` | GOPRIVATE setting | + +### Security Scan Flags + +| Input | Type | Default | Description | +|-------|------|---------|-------------| +| `perform-complexity-checks` | boolean | `true` | Run SCC complexity checks | +| `perform-language-linting` | boolean | `true` | Run language-specific linting | +| `perform-trufflehog-scan` | boolean | `true` | Run TruffleHog secret scan | +| `perform-trivy-scan` | boolean | `true` | Run Trivy vulnerability scan | +| `perform-sonarqube-scan` | boolean | `true` | Run SonarQube scan | +| `perform-blackduck-polaris` | boolean | `false` | Run BlackDuck Polaris SAST | +| `perform-docker-scan` | boolean | `false` | Run Docker scan | + +### Build Configuration + +| Input | Type | Default | Description | +|-------|------|---------|-------------| +| `build` | boolean | `true` | Run CI build | +| `build-profile` | string | `cli` | Build profile | +| `unit-tests` | boolean | `true` | Run unit tests | +| `run-bundle-install` | boolean | `false` | Run bundle install (Ruby) | + +### BlackDuck Polaris + +| Input | Type | Default | Description | +|-------|------|---------|-------------| +| `polaris-application-name` | string | - | Application name (Chef-Chef360, etc.) | +| `polaris-project-name` | string | repo name | Project name | +| `polaris-working-directory` | string | `.` | Working directory | +| `polaris-assessment-mode` | string | `CI` | Mode (SAST/CI/SOURCE_UPLOAD) | +| `wait-for-scan` | boolean | `true` | Wait for scan completion | + +### SBOM & SCA + +| Input | Type | Default | Description | +|-------|------|---------|-------------| +| `generate-sbom` | boolean | `true` | Generate SBOM | +| `export-github-sbom` | boolean | `true` | Export GitHub SBOM | +| `generate-msft-sbom` | boolean | `true` | Generate Microsoft SBOM | +| `license_scout` | boolean | `true` | Run license scout | +| `perform-blackduck-sca-scan` | boolean | `false` | Run BlackDuck SCA scan | +| `blackduck-project-group-name` | string | `Chef` | BlackDuck project group | +| `blackduck-project-name` | string | repo name | BlackDuck project name | + +### Habitat Packaging + +| Input | Type | Default | Description | +|-------|------|---------|-------------| +| `package-binaries` | boolean | `true` | Package binaries | +| `habitat-build` | boolean | `true` | Create Habitat packages | +| `publish-habitat-packages` | boolean | `false` | Publish to Builder | +| `publish-habitat-hab_package` | string | `core/nginx` | Package name | +| `publish-habitat-hab_channel` | string | `stable` | Channel | +| `habitat-grype-scan` | boolean | `false` | Scan with Grype | + +### Quality Dashboard + +| Input | Type | Default | Description | +|-------|------|---------|-------------| +| `report-to-atlassian-dashboard` | boolean | `true` | Report to dashboard | +| `report-unit-test-coverage` | boolean | `true` | Report coverage | +| `quality-product-name` | string | `Chef360` | Product name | + +> **For a complete list of all inputs with detailed descriptions, see [PIPELINE-REFERENCE.md](PIPELINE-REFERENCE.md)** + +--- + ## Support For issues or questions: -1. Check the [DEV-README.md](.github/workflows/DEV-README.md) for development notes -2. Review the [combined-documentation.md](combined-documentation.md) for detailed tool information +1. Check [PIPELINE-REFERENCE.md](PIPELINE-REFERENCE.md) for detailed tool documentation +2. Review [DEV-README.md](.github/workflows/DEV-README.md) for development notes 3. Open an issue in this repository --- diff --git a/combined-documentation.md b/PIPELINE-REFERENCE.md similarity index 100% rename from combined-documentation.md rename to PIPELINE-REFERENCE.md diff --git a/README.md b/README.md index e363591..35ff0f1 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,15 @@ # Common Github Actions for Chef organization Location for reusable workflows +## 📖 Read This Before Using + +| Document | Description | +|----------|-------------| +| **[HOW-TO-USE.md](HOW-TO-USE.md)** | Quick start guide, configuration examples, and input reference | +| **[PIPELINE-REFERENCE.md](PIPELINE-REFERENCE.md)** | Detailed tool documentation, mermaid diagrams, and job mappings | + +--- + ## Naming convention Typical workflows are stored in the `.github\workflows` directory. From a1a0eca2708aa76baa663584b7a9353e772f7cc6 Mon Sep 17 00:00:00 2001 From: Sean Simmons Date: Fri, 20 Feb 2026 09:49:18 -0500 Subject: [PATCH 3/4] adding updates to the version to include things like -beta and -rc1 Signed-off-by: Sean Simmons --- .github/workflows/create-release-tag.yml | 74 +++++++++++++++++++++--- 1 file changed, 65 insertions(+), 9 deletions(-) diff --git a/.github/workflows/create-release-tag.yml b/.github/workflows/create-release-tag.yml index 236e495..95dacdf 100644 --- a/.github/workflows/create-release-tag.yml +++ b/.github/workflows/create-release-tag.yml @@ -76,26 +76,78 @@ jobs: echo "latest_tag=${LATEST_TAG}" >> $GITHUB_OUTPUT echo "Latest tag: ${LATEST_TAG}" - - name: Calculate new version + - name: Validate and parse version id: calc_version run: | LATEST_TAG="${{ steps.get_latest_tag.outputs.latest_tag }}" + # Function to validate semver format (vX.Y.Z or X.Y.Z where X, Y, Z are integers) + validate_semver() { + local version="$1" + local stripped="${version#v}" # Remove 'v' prefix if present + + # Check if it matches X.Y.Z where X, Y, Z are non-negative integers + if [[ "$stripped" =~ ^([0-9]+)\.([0-9]+)\.([0-9]+)$ ]]; then + echo "valid" + else + echo "invalid" + fi + } + + # Function to extract semver components + extract_semver() { + local version="$1" + local stripped="${version#v}" # Remove 'v' prefix if present + + # Extract just the X.Y.Z part, ignoring any suffix like -rc1, -beta, etc. + if [[ "$stripped" =~ ^([0-9]+)\.([0-9]+)\.([0-9]+) ]]; then + echo "${BASH_REMATCH[1]}.${BASH_REMATCH[2]}.${BASH_REMATCH[3]}" + else + echo "" + fi + } + # Handle custom version input if [ -n "${{ inputs.custom_version }}" ]; then - NEW_VERSION="${{ inputs.custom_version }}" - echo "Using custom version: ${NEW_VERSION}" - echo "new_version=${NEW_VERSION}" >> $GITHUB_OUTPUT + CUSTOM_VER="${{ inputs.custom_version }}" + CUSTOM_VER="${CUSTOM_VER#v}" # Strip 'v' prefix if user included it + + if [[ "$(validate_semver "$CUSTOM_VER")" != "valid" ]]; then + echo "❌ Error: Custom version '$CUSTOM_VER' is not a valid semantic version." + echo " Expected format: X.Y.Z (e.g., 1.2.3)" + echo " Each component must be a non-negative integer." + exit 1 + fi + + echo "Using custom version: ${CUSTOM_VER}" + echo "new_version=${CUSTOM_VER}" >> $GITHUB_OUTPUT exit 0 fi - # Strip 'v' prefix for version calculation - VERSION=${LATEST_TAG#v} + # Validate latest tag format + EXTRACTED_VERSION=$(extract_semver "$LATEST_TAG") + + if [ -z "$EXTRACTED_VERSION" ]; then + echo "⚠️ Warning: Latest tag '$LATEST_TAG' is not a valid semantic version." + echo " Expected format: vX.Y.Z (e.g., v1.2.3)" + echo " Starting from v0.0.0 instead." + EXTRACTED_VERSION="0.0.0" + elif [ "$EXTRACTED_VERSION" != "${LATEST_TAG#v}" ]; then + echo "⚠️ Warning: Latest tag '$LATEST_TAG' contains a suffix." + echo " Using base version: $EXTRACTED_VERSION" + fi # Split version into parts - MAJOR=$(echo $VERSION | cut -d. -f1) - MINOR=$(echo $VERSION | cut -d. -f2) - PATCH=$(echo $VERSION | cut -d. -f3) + MAJOR=$(echo "$EXTRACTED_VERSION" | cut -d. -f1) + MINOR=$(echo "$EXTRACTED_VERSION" | cut -d. -f2) + PATCH=$(echo "$EXTRACTED_VERSION" | cut -d. -f3) + + # Verify components are numeric (defensive check) + if ! [[ "$MAJOR" =~ ^[0-9]+$ ]] || ! [[ "$MINOR" =~ ^[0-9]+$ ]] || ! [[ "$PATCH" =~ ^[0-9]+$ ]]; then + echo "❌ Error: Version components must be numeric." + echo " Got: MAJOR=$MAJOR, MINOR=$MINOR, PATCH=$PATCH" + exit 1 + fi # Default to patch bump for push events, use input for workflow_dispatch BUMP_TYPE="${{ inputs.version_bump }}" @@ -117,6 +169,10 @@ jobs: patch) PATCH=$((PATCH + 1)) ;; + *) + echo "❌ Error: Invalid bump type '$BUMP_TYPE'. Must be one of: major, minor, patch" + exit 1 + ;; esac NEW_VERSION="${MAJOR}.${MINOR}.${PATCH}" From 58f528853702047093bba5b5e0275a6b43b320ad Mon Sep 17 00:00:00 2001 From: Sean Simmons Date: Fri, 20 Feb 2026 10:09:18 -0500 Subject: [PATCH 4/4] fixing race condition Signed-off-by: Sean Simmons --- .github/workflows/create-release-tag.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/create-release-tag.yml b/.github/workflows/create-release-tag.yml index 95dacdf..464966c 100644 --- a/.github/workflows/create-release-tag.yml +++ b/.github/workflows/create-release-tag.yml @@ -253,6 +253,7 @@ jobs: uses: actions/checkout@v4 with: fetch-depth: 0 + ref: ${{ needs.create-tag.outputs.new_tag }} - name: Generate release notes id: release_notes