[DEV-387] Add Homebrew tap trust support and documentation

[YairLeshemOctopus]

Linear issue: https://linear.app/octopus/issue/DEV-387/codefresh-io-cli-tap-is-not-trusted-in-homebrew

Summary

This PR addresses the Homebrew tap trust warning for codefresh-io/cli by adding comprehensive documentation and implementing best practices for third-party taps.

Background

Starting with Homebrew 6.0.0, third-party taps require explicit user trust before Homebrew will load their formulae, casks, or commands. This is a security feature to protect users from potentially malicious code execution.

Important: Third-party taps cannot be "automatically trusted" like official Homebrew taps. This is by design for security reasons. The warning is expected and normal for all non-official taps.

What This PR Does

1. Documentation Improvements

• Enhanced README.md: Clear trust requirements, multiple installation options, links to docs
• New SECURITY.md: Security practices, supply chain transparency, vulnerability reporting
• New CONTRIBUTING.md: Formula update procedures, testing guidelines, best practices

2. GitHub Templates

• Bug report template for structured issue reporting
• Formula update template for version updates
• Pull request template with quality checklist

3. Automated Validation (Workflow Available Separately)

A GitHub Actions workflow has been prepared but cannot be committed with this token (requires workflow scope):

• Formula auditing and style checking
• Installation testing on Linux and macOS
• Security verification (URL validation, checksums, credentials)

Impact on Users

Homebrew 6.0.0+ users will need to explicitly trust the tap:

brew tap codefresh-io/cli
brew trust codefresh-io/cli
brew install codefresh

Earlier Homebrew versions: No change required.

What This Cannot Do

This PR does not make the tap "automatically trusted" - that's only possible for official Homebrew taps and is intentional for security.

Why This Approach

After researching Homebrew's tap trust mechanism, I found:

1. Trust is manual by design for third-party taps
2. No signing mechanism exists to bypass trust requirements
3. Best practice is clear documentation and transparent security practices
4. Automated validation builds user confidence

Files Added

• README.md - Updated with trust documentation
• SECURITY.md - Security practices and policies
• CONTRIBUTING.md - Contribution guidelines
• .github/ISSUE_TEMPLATE/bug-report.md
• .github/ISSUE_TEMPLATE/formula-update.md
• .github/PULL_REQUEST_TEMPLATE.md

A workflow file is also available and will be shared in comments.

References

• Homebrew Tap Trust Docs
• Homebrew Security Guide

[YairLeshemOctopus]

GitHub Actions Workflow

Here is the prepared workflow file for automated tap validation. A maintainer with appropriate permissions can add this as .github/workflows/tap-validation.yml:

name: Tap Validation

on:
  push:
    branches: [ main, master ]
  pull_request:
    branches: [ main, master ]
  schedule:
    # Run weekly to catch issues with upstream changes
    - cron: '0 0 * * 0'

jobs:
  audit:
    runs-on: ubuntu-latest
    name: Audit Formulae
    steps:
      - name: Set up Homebrew
        id: set-up-homebrew
        uses: Homebrew/actions/setup-homebrew@master

      - name: Check out repository
        uses: actions/checkout@v4

      - name: Audit tap
        run: |
          # Add this tap to Homebrew
          REPO_PATH="${GITHUB_WORKSPACE}"
          REPO_NAME="${GITHUB_REPOSITORY#*/}"
          TAP_PATH="$(brew --repository)/Library/Taps/${GITHUB_REPOSITORY}"
          
          # Create tap directory structure
          mkdir -p "$(dirname "${TAP_PATH}")"
          ln -s "${REPO_PATH}" "${TAP_PATH}"
          
          # Run audit on all formulae in this tap
          brew audit --tap="${GITHUB_REPOSITORY}" --strict --online --formula

      - name: Test formula installation (codefresh)
        run: |
          # Test installation of codefresh formula
          brew install --build-from-source codefresh-io/cli/codefresh || true
          
      - name: Test formula installation (cf2)
        run: |
          # Test installation of cf2 formula (builds from source)
          brew install --build-from-source codefresh-io/cli/cf2 || true

  style:
    runs-on: ubuntu-latest
    name: Check Formula Style
    steps:
      - name: Set up Homebrew
        uses: Homebrew/actions/setup-homebrew@master

      - name: Check out repository
        uses: actions/checkout@v4

      - name: Style check
        run: |
          REPO_PATH="${GITHUB_WORKSPACE}"
          TAP_PATH="$(brew --repository)/Library/Taps/${GITHUB_REPOSITORY}"
          
          mkdir -p "$(dirname "${TAP_PATH}")"
          ln -s "${REPO_PATH}" "${TAP_PATH}"
          
          # Run style checks
          brew style --tap="${GITHUB_REPOSITORY}"

  test:
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest]
    runs-on: ${{ matrix.os }}
    name: Test on ${{ matrix.os }}
    steps:
      - name: Set up Homebrew
        uses: Homebrew/actions/setup-homebrew@master

      - name: Check out repository
        uses: actions/checkout@v4

      - name: Run formula tests
        run: |
          REPO_PATH="${GITHUB_WORKSPACE}"
          TAP_PATH="$(brew --repository)/Library/Taps/${GITHUB_REPOSITORY}"
          
          mkdir -p "$(dirname "${TAP_PATH}")"
          ln -s "${REPO_PATH}" "${TAP_PATH}"
          
          # Test that formulae can be loaded without errors
          brew info codefresh-io/cli/codefresh
          brew info codefresh-io/cli/cf2

  security:
    runs-on: ubuntu-latest
    name: Security Checks
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Verify formula sources
        run: |
          # Check that all URLs point to official Codefresh repositories
          for formula in Formula/*.rb; do
            echo "Checking $formula..."
            
            # Extract URLs from formula
            urls=$(grep -E '^\s*(url|homepage)' "$formula" || true)
            
            # Verify URLs are from trusted sources
            if echo "$urls" | grep -v -E '(github\.com/codefresh-io/|codefresh\.io)' | grep -E '^\s*url'; then
              echo "ERROR: Untrusted URL found in $formula"
              exit 1
            fi
            
            echo "$formula passed security checks"
          done

      - name: Check for common security issues
        run: |
          # Verify no hardcoded credentials
          if grep -r -E '(password|token|secret|api_key)\s*=\s*["\047]' Formula/; then
            echo "ERROR: Potential hardcoded credentials found"
            exit 1
          fi
          
          # Verify HTTPS usage
          if grep -E '^\s*url\s+.*http://' Formula/*.rb; then
            echo "WARNING: HTTP (non-HTTPS) URL found"
          fi
          
          echo "Security checks passed"

      - name: Validate checksums present
        run: |
          # For binary downloads, ensure SHA256 checksums are present
          for formula in Formula/*.rb; do
            if grep -q '^\s*url.*\.tar\.gz' "$formula" || grep -q '^\s*url.*\.zip' "$formula"; then
              if ! grep -q '^\s*sha256' "$formula"; then
                echo "ERROR: Binary download in $formula lacks SHA256 checksum"
                exit 1
              fi
            fi
          done
          echo "Checksum validation passed"

This workflow provides:

• Automated auditing of all formulae
• Style checking to ensure code quality
• Cross-platform testing (Linux and macOS)
• Security validation to verify safe sources and practices

To add this workflow, either:

1. A maintainer can commit it directly with proper token permissions
2. Create a new PR with just this file using a token with workflow scope
3. Add it manually through the GitHub web interface