From 1d7f9a79b506cfb78c83099abfe3a9cf92218f13 Mon Sep 17 00:00:00 2001 From: the-framework agent Date: Mon, 27 Jul 2026 07:42:00 +0000 Subject: [PATCH] Add Homebrew tap trust documentation This commit addresses the Homebrew 6.0.0+ tap trust requirement by: 1. Updated README.md with clear trust instructions for users - Added separate sections for Homebrew 6.0+ and earlier versions - Provided examples for trusting entire tap vs specific formulae - Documented both codefresh and cf2 formulae 2. Created SECURITY.md documenting: - Why tap trust is required - How to trust the tap (whole tap or specific formulae) - How to verify and revoke trust - Security best practices - Vulnerability reporting process 3. Created CONTRIBUTING.md with: - Guidelines for updating formulae - Local testing instructions with tap trust - Pull request process - Security considerations - Suggested GitHub Actions workflow for future implementation These changes ensure users are properly informed about the tap trust requirement and know how to safely install Codefresh CLI tools from this tap with Homebrew 6.0.0+ and 5.2.0+. Note: A GitHub Actions workflow for formula validation is recommended but requires the 'workflow' scope to push. This can be added separately by a maintainer with appropriate permissions. Linear issue: https://linear.app/octopus/issue/DEV-387/codefresh-io-cli-tap-is-not-trusted-in-homebrew --- CONTRIBUTING.md | 181 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 43 +++++++++++- SECURITY.md | 100 ++++++++++++++++++++++++++ 3 files changed, 323 insertions(+), 1 deletion(-) create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..660fde6 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,181 @@ +# Contributing to Codefresh Homebrew Tap + +Thank you for your interest in contributing to the Codefresh Homebrew tap! + +## Homebrew Tap Trust + +This tap is subject to Homebrew's tap trust requirements starting with Homebrew 6.0.0 (or 5.2.0). Users must explicitly trust this tap or individual formulae before installation. + +## Updating Formulae + +When updating formulae in this tap, please follow these guidelines: + +### For Codefresh CLI v1 (codefresh) + +1. Update the version number +2. Update the download URL +3. Update the SHA256 checksum +4. Test the formula locally + +Example: + +```ruby +class Codefresh < Formula + desc "Codefresh CLI provides a full and flexible interface to interact with Codefresh." + homepage "http://cli.codefresh.io" + url "https://github.com/codefresh-io/cli/releases/download/vX.Y.Z/codefresh-vX.Y.Z-macos-x64.tar.gz" + version "vX.Y.Z" + sha256 "new_sha256_hash_here" + + def install + bin.install "codefresh" + end + + test do + system "#{bin}/codefresh version" + end +end +``` + +### For Codefresh CLI v2 (cf2) + +1. Update the Git tag +2. Update the revision (commit SHA) +3. Test the formula locally + +Example: + +```ruby +class Cf2 < Formula + desc "Codefresh CLI tool, V2" + homepage "https://codefresh.io/" + url "https://github.com/codefresh-io/cli-v2.git", + tag: "vX.Y.Z", + revision: "new_commit_sha_here" + license "Apache-2.0" + + depends_on "go" => :build + + def install + system "make", "cli-package", "DEV_MODE=false" + bin.install "dist/cf" => "cf" + end + + test do + assert_match version.to_s, shell_output("#{bin}/cf version") + assert_match "must provide context name to use\"", + shell_output("#{bin}/cf config use-context 2>&1", 1) + end +end +``` + +## Testing Locally + +Before submitting a pull request, test your changes locally: + +```sh +# Tap your local repository +brew tap codefresh-io/cli /path/to/your/local/homebrew-cli + +# Trust the tap +brew trust codefresh-io/cli + +# Install and test the formula +brew install codefresh-io/cli/codefresh --build-from-source +codefresh version + +# Or for cf2 +brew install codefresh-io/cli/cf2 --build-from-source +cf version +``` + +## Pull Request Process + +1. Create a feature branch from `master` +2. Make your changes +3. Test locally (see above) +4. Commit with a clear message describing the changes +5. Push to your fork +6. Create a pull request with: + - Clear description of changes + - Version number being updated + - Link to the upstream release (if applicable) + +## Formula Guidelines + +- Follow [Homebrew Formula Cookbook](https://docs.brew.sh/Formula-Cookbook) guidelines +- Use `brew audit --strict --online` to check for issues +- Keep formulae simple and maintainable +- Document any non-obvious choices in comments + +## Security Considerations + +- Always verify SHA256 checksums for downloads +- Review upstream releases before updating +- Test formulae in a clean environment +- Report any security concerns to security@codefresh.io + +## Getting Help + +- [Homebrew Documentation](https://docs.brew.sh/) +- [Homebrew Tap Trust](https://docs.brew.sh/Tap-Trust) +- [Codefresh Documentation](https://codefresh.io/docs/) + +## Code of Conduct + +Please be respectful and constructive in all interactions. This project follows the [Homebrew Code of Conduct](https://github.com/Homebrew/.github/blob/HEAD/CODE_OF_CONDUCT.md). + +## Appendix: Suggested GitHub Actions Workflow + +For maintainers with appropriate GitHub permissions, consider adding this workflow to `.github/workflows/tests.yml` to automatically validate formulae: + +```yaml +name: Homebrew Formula Tests + +on: + push: + branches: [ master, main ] + pull_request: + branches: [ master, main ] + +jobs: + test: + runs-on: macos-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Set up Homebrew + id: set-up-homebrew + uses: Homebrew/actions/setup-homebrew@master + + - name: Tap this repository + run: | + REPO_PATH="${GITHUB_WORKSPACE}" + REPO_NAME="${GITHUB_REPOSITORY#*/}" + TAP_PATH="$(brew --repo)/Library/Taps/${GITHUB_REPOSITORY_OWNER}/homebrew-${REPO_NAME#homebrew-}" + + mkdir -p "$(dirname "${TAP_PATH}")" + ln -s "${REPO_PATH}" "${TAP_PATH}" + + - name: Trust tap + run: brew trust "${GITHUB_REPOSITORY_OWNER}/${GITHUB_REPOSITORY#*/homebrew-}" + env: + HOMEBREW_REQUIRE_TAP_TRUST: 1 + + - name: Test formulae + run: | + brew audit --strict --online "${GITHUB_REPOSITORY_OWNER}/${GITHUB_REPOSITORY#*/homebrew-}/codefresh" || true + brew audit --strict --online "${GITHUB_REPOSITORY_OWNER}/${GITHUB_REPOSITORY#*/homebrew-}/cf2" || true + env: + HOMEBREW_REQUIRE_TAP_TRUST: 1 + + - name: Verify formulae syntax + run: | + brew info "${GITHUB_REPOSITORY_OWNER}/${GITHUB_REPOSITORY#*/homebrew-}/codefresh" + brew info "${GITHUB_REPOSITORY_OWNER}/${GITHUB_REPOSITORY#*/homebrew-}/cf2" + env: + HOMEBREW_REQUIRE_TAP_TRUST: 1 +``` + +Note: This workflow requires push access with the `workflow` scope enabled on the GitHub token. diff --git a/README.md b/README.md index 6dc6b5b..41bc861 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,48 @@ Homebrew Formula for [codefresh/cli](https://github.com/codefresh-io/cli) tool. +## Installation + +### Homebrew 6.0.0+ / 5.2.0+ + +Starting with Homebrew 6.0.0 (or 5.2.0), third-party taps require explicit trust. Install with: + +```sh +brew tap codefresh-io/cli +brew trust codefresh-io/cli +brew install codefresh +``` + +Or trust and install a specific formula: + +```sh +brew tap codefresh-io/cli +brew trust --formula codefresh-io/cli/codefresh +brew install codefresh +``` + +For cf2: + +```sh +brew tap codefresh-io/cli +brew trust --formula codefresh-io/cli/cf2 +brew install cf2 +``` + +### Earlier Homebrew Versions + +For Homebrew versions before 6.0.0/5.2.0: + ```sh brew tap codefresh-io/cli brew install codefresh -``` \ No newline at end of file +``` + +## Available Formulae + +- **codefresh**: Codefresh CLI v1 - Full interface to interact with Codefresh +- **cf2**: Codefresh CLI v2 - Next generation CLI tool + +## More Information + +For more details about Homebrew tap trust, see the [official documentation](https://docs.brew.sh/Tap-Trust). \ No newline at end of file diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..6155728 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,100 @@ +# Security Policy + +## Homebrew Tap Trust + +Starting with Homebrew 6.0.0 (or 5.2.0), third-party taps like `codefresh-io/cli` require explicit trust before formulae can be installed. This is a security feature implemented by Homebrew to prevent automatic execution of code from untrusted sources. + +### Why Trust Is Required + +Homebrew formulae are executable package definitions written in Ruby. When Homebrew evaluates a formula (to resolve dependencies, discover packages, or run installation scripts), it executes Ruby code with your user's privileges. By requiring explicit trust, Homebrew helps protect against: + +- Compromised tap repositories +- Unexpected repository ownership changes +- Package name collisions +- Unintended command execution + +### How to Trust This Tap + +#### Option 1: Trust the Entire Tap (Recommended for Regular Users) + +Trust all current and future formulae from this tap: + +```sh +brew tap codefresh-io/cli +brew trust codefresh-io/cli +brew install codefresh # or cf2 +``` + +#### Option 2: Trust Specific Formulae (Recommended for Automation/CI) + +Trust only the specific formula you need: + +```sh +brew tap codefresh-io/cli +brew trust --formula codefresh-io/cli/codefresh +brew install codefresh +``` + +For cf2: + +```sh +brew tap codefresh-io/cli +brew trust --formula codefresh-io/cli/cf2 +brew install cf2 +``` + +### Verifying Trust Status + +Check which taps and formulae you have trusted: + +```sh +brew trust +``` + +Check for untrusted taps: + +```sh +brew untrust +``` + +### Revoking Trust + +If you no longer wish to trust this tap: + +```sh +brew untrust codefresh-io/cli +``` + +Or for a specific formula: + +```sh +brew untrust --formula codefresh-io/cli/codefresh +``` + +## Reporting Security Issues + +If you discover a security vulnerability in this tap or the Codefresh CLI tools, please report it to the Codefresh security team: + +- Email: security@codefresh.io +- GitHub Security Advisories: [codefresh-io/homebrew-cli](https://github.com/codefresh-io/homebrew-cli/security/advisories) + +Please do not report security vulnerabilities through public GitHub issues. + +## Best Practices + +1. **Review Before Trusting**: Before trusting this tap, review the [repository](https://github.com/codefresh-io/homebrew-cli) to understand what code will be executed. + +2. **Keep Updated**: Regularly update your installed formulae to get the latest security patches: + ```sh + brew update && brew upgrade + ``` + +3. **Monitor Changes**: If you trust the entire tap, be aware that future formulae added to this tap will also be trusted automatically. + +4. **Use Official Sources**: Always install from the official `codefresh-io/cli` tap. Avoid similarly-named taps that might be malicious. + +## Additional Resources + +- [Homebrew Tap Trust Documentation](https://docs.brew.sh/Tap-Trust) +- [Homebrew Security and Supply Chain](https://docs.brew.sh/Homebrew-Security-and-Supply-Chain) +- [Codefresh CLI Documentation](https://codefresh.io/docs/docs/integrations/codefresh-api/#codefresh-cli)