diff --git a/.github/workflows/create-release-tag.yml b/.github/workflows/create-release-tag.yml new file mode 100644 index 0000000..464966c --- /dev/null +++ b/.github/workflows/create-release-tag.yml @@ -0,0 +1,306 @@ +# 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: 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 + 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 + + # 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 "$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 }}" + 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)) + ;; + *) + echo "❌ Error: Invalid bump type '$BUMP_TYPE'. Must be one of: major, minor, patch" + exit 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 + ref: ${{ needs.create-tag.outputs.new_tag }} + + - 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..47beadd --- /dev/null +++ b/HOW-TO-USE.md @@ -0,0 +1,371 @@ +# 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. + +> **📖 For detailed pipeline architecture, tool reference, and mermaid diagrams, see [PIPELINE-REFERENCE.md](PIPELINE-REFERENCE.md)** + +--- + +## Table of Contents + +- [Quick Start](#quick-start) +- [Versioning with Tags](#versioning-with-tags) +- [Available Workflows](#available-workflows) +- [Required Secrets](#required-secrets) +- [Configuration Examples](#configuration-examples) +- [Input Reference](#input-reference) + +--- + +## 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: + # 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: + 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 required secrets configured. See [Required Secrets](#required-secrets) below. + +### 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}` + +| Bump Type | When to Use | +|-----------|-------------| +| **MAJOR** | Breaking changes | +| **MINOR** | New features, backward compatible | +| **PATCH** | Bug fixes, backward compatible | + +### Automatic Tagging + +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. + +--- + +## 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` | + +> **See [PIPELINE-REFERENCE.md](PIPELINE-REFERENCE.md) for detailed documentation on each tool, including workflow diagrams and job mappings.** + +--- + +## Required Secrets + +Configure these secrets at the repository or organization level: + +| 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 | + +--- + +## 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 +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' + + perform-complexity-checks: true + perform-language-linting: true + perform-trufflehog-scan: true + perform-trivy-scan: true + perform-sonarqube-scan: true + + build: true + unit-tests: true + run-bundle-install: true # For projects without committed Gemfile.lock + + generate-sbom: true + license_scout: true +``` + +### Habitat Package + +```yaml +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' + + 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' + habitat-grype-scan: true + + generate-sbom: true +``` + +### Minimal Security Scan Only + +```yaml +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 +``` + +--- + +## 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 [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 + +--- + +## 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/PIPELINE-REFERENCE.md b/PIPELINE-REFERENCE.md new file mode 100644 index 0000000..ffb863e --- /dev/null +++ b/PIPELINE-REFERENCE.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. 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.