codefresh-io · YairLeshemOctopus · Jul 28, 2026
diff --git a/.github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug-report.md
@@ -0,0 +1,54 @@
+---
+name: Bug Report
+about: Report an issue with a formula in this tap
+title: '[BUG] '
+labels: bug
+assignees: ''
+---
+
+## Bug Description
+
+<!-- A clear description of the bug -->
+
+## Formula Affected
+
+<!-- Which formula has the issue? -->
+- [ ] `codefresh` (V1 CLI)
+- [ ] `cf2` (V2 CLI)
+
+## Steps to Reproduce
+
+```sh
+# Commands you ran that produced the error
+brew tap codefresh-io/cli
+brew install ...
+```
+
+## Expected Behavior
+
+<!-- What should happen? -->
+
+## Actual Behavior
+
+<!-- What actually happened? -->
+
+```
+<!-- Paste error messages or unexpected output here -->
+```
+
+## Environment
+
+- **macOS version**: <!-- e.g., macOS 14.1 Sonoma -->
+- **Homebrew version**: <!-- Run: brew --version -->
+- **Formula version**: <!-- Run: brew info codefresh-io/cli/formula-name -->
+- **Architecture**: <!-- Intel or Apple Silicon (M1/M2/M3) -->
+
+## Additional Context
+
+<!-- Any other information that might help diagnose the issue -->
+
+## Note
+
+**If this is a bug with the CLI tool itself** (not the Homebrew formula), please report it at:
+- Codefresh CLI V1: https://github.com/codefresh-io/cli/issues
+- Codefresh CLI V2: https://github.com/codefresh-io/cli-v2/issues
diff --git a/.github/ISSUE_TEMPLATE/formula-update.md b/.github/ISSUE_TEMPLATE/formula-update.md
@@ -0,0 +1,28 @@
+---
+name: Formula Update Request
+about: Request an update to a formula for a new version
+title: '[UPDATE] formula-name: version X.Y.Z available'
+labels: enhancement
+assignees: ''
+---
+
+## Formula to Update
+
+<!-- Which formula needs updating? -->
+- [ ] `codefresh` (V1 CLI)
+- [ ] `cf2` (V2 CLI)
+
+## New Version
+
+**Version**: <!-- e.g., v1.2.4 -->
+**Release URL**: <!-- Link to GitHub release -->
+
+## Checklist
+
+- [ ] New version is released and stable
+- [ ] Release notes reviewed
+- [ ] No known critical issues
+
+## Additional Context
+
+<!-- Any other relevant information about this update -->
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,54 @@
+## Description
+
+<!-- Describe what this PR changes and why -->
+
+## Type of Change
+
+- [ ] Formula update (new version)
+- [ ] Bug fix (formula installation/build issue)
+- [ ] New formula
+- [ ] Documentation update
+- [ ] CI/workflow improvement
+- [ ] Other (please describe)
+
+## Formulae Affected
+
+- [ ] `codefresh` (V1 CLI)
+- [ ] `cf2` (V2 CLI)
+- [ ] Documentation/infrastructure only
+
+## Testing
+
+<!-- Describe how you tested these changes -->
+
+- [ ] Tested installation: `brew install --build-from-source ./Formula/formula-name.rb`
+- [ ] Tested functionality: `brew test formula-name`
+- [ ] Ran audit: `brew audit --strict Formula/formula-name.rb`
+- [ ] Ran style check: `brew style Formula/formula-name.rb`
+
+### Test Environment
+
+- **macOS version**: <!-- e.g., macOS 14.1 Sonoma -->
+- **Architecture**: <!-- Intel or Apple Silicon -->
+- **Homebrew version**: <!-- output of: brew --version -->
+
+## Checklist
+
+- [ ] Formulae use HTTPS URLs only
+- [ ] Binary downloads include SHA256 checksums
+- [ ] Version numbers updated correctly
+- [ ] Commit message follows format: `formula-name: description`
+- [ ] Changes tested locally
+- [ ] Documentation updated (if needed)
+
+## Related Issues
+
+<!-- Link any related issues: Fixes #123 or Related to #456 -->
+
+## Release Notes
+
+<!-- For version updates, link to release notes -->
+
+## Additional Notes
+
+<!-- Any other information reviewers should know -->
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,165 @@
+# Contributing to homebrew-cli
+
+Thank you for your interest in contributing to the Codefresh Homebrew tap!
+
+## Updating Formulae
+
+### When to Update
+
+Formulae should be updated when:
+- A new version of Codefresh CLI is released
+- Security vulnerabilities are discovered in current versions
+- Bug fixes are available
+- Build process changes are needed
+
+### How to Update
+
+#### Updating `codefresh` (V1 CLI)
+
+1. Check for new releases at https://github.com/codefresh-io/cli/releases
+2. Download the new binary and calculate SHA256:
+   ```sh
+   curl -L -o codefresh.tar.gz https://github.com/codefresh-io/cli/releases/download/vX.Y.Z/codefresh-vX.Y.Z-macos-x64.tar.gz
+   shasum -a 256 codefresh.tar.gz
+   ```
+3. Update `Formula/codefresh.rb`:
+   - Change `url` to point to new version
+   - Update `version` string
+   - Update `sha256` with calculated value
+4. Test the formula:
+   ```sh
+   brew install --build-from-source ./Formula/codefresh.rb
+   brew test codefresh
+   ```
+
+#### Updating `cf2` (V2 CLI)
+
+1. Check for new releases at https://github.com/codefresh-io/cli-v2/releases
+2. Note the git tag and commit SHA
+3. Update `Formula/cf2.rb`:
+   - Change `tag` to new version (e.g., `v1.0.8`)
+   - Update `revision` to the commit SHA of that tag
+4. Test the formula:
+   ```sh
+   brew install --build-from-source ./Formula/cf2.rb
+   brew test cf2
+   ```
+
+### Formula Best Practices
+
+- **Use HTTPS URLs only**
+- **Include SHA256 checksums** for binary downloads
+- **Pin to specific versions/commits** using tags and revision SHAs
+- **Test on macOS** if possible (GitHub Actions runs on Linux)
+- **Follow Homebrew style guide**: Run `brew style Formula/your-formula.rb`
+- **Audit changes**: Run `brew audit --strict Formula/your-formula.rb`
+
+## Testing Changes
+
+### Local Testing
+
+Before submitting a PR:
+
+1. **Test installation**:
+   ```sh
+   brew install --build-from-source ./Formula/formula-name.rb
+   ```
+
+2. **Test functionality**:
+   ```sh
+   brew test formula-name
+   ```
+
+3. **Run audit**:
+   ```sh
+   brew audit --strict --online Formula/formula-name.rb
+   ```
+
+4. **Check style**:
+   ```sh
+   brew style Formula/formula-name.rb
+   ```
+
+### CI Testing
+
+Pull requests automatically run:
+- Formula auditing
+- Style checks
+- Installation tests
+- Security validation
+
+Check the Actions tab for results.
+
+## Pull Request Process
+
+1. **Fork this repository**
+2. **Create a feature branch**:
+   ```sh
+   git checkout -b update-formula-vX.Y.Z
+   ```
+3. **Make your changes**
+4. **Test thoroughly** (see above)
+5. **Commit with clear message**:
+   ```sh
+   git commit -m "formula-name: update to version X.Y.Z"
+   ```
+6. **Push and create PR**:
+   ```sh
+   git push origin update-formula-vX.Y.Z
+   ```
+7. **Describe changes** in PR description, including:
+   - What version you're updating to
+   - Link to release notes
+   - What you tested
+
+## Commit Message Format
+
+Follow Homebrew conventions:
+
+```
+formula-name: update to version X.Y.Z
+
+- Updated URL and SHA256 for new release
+- Tested on macOS Sonoma
+
+Release notes: https://github.com/codefresh-io/cli/releases/tag/vX.Y.Z
+```
+
+Other common prefixes:
+- `formula-name: add new formula`
+- `formula-name: fix build failure`
+- `formula-name: add test`
+- `README: update installation instructions`
+- `workflow: improve CI testing`
+
+## Security
+
+### Reporting Security Issues
+
+See [SECURITY.md](SECURITY.md) for how to report security vulnerabilities.
+
+### Security in Formulae
+
+When contributing:
+- Only use official Codefresh sources
+- Verify checksums for binary downloads
+- Don't hardcode credentials
+- Use HTTPS for all URLs
+- Minimize arbitrary code execution
+
+## Code of Conduct
+
+This project follows the Homebrew Code of Conduct. Be respectful and constructive.
+
+## Questions?
+
+- **For formula issues**: Open an issue in this repository
+- **For CLI bugs**: Report in the respective CLI repository ([cli](https://github.com/codefresh-io/cli) or [cli-v2](https://github.com/codefresh-io/cli-v2))
+- **For Homebrew questions**: See [Homebrew documentation](https://docs.brew.sh)
+
+## Resources
+
+- [Homebrew Formula Cookbook](https://docs.brew.sh/Formula-Cookbook)
+- [Homebrew Acceptable Formulae](https://docs.brew.sh/Acceptable-Formulae)
+- [Homebrew Ruby Style Guide](https://docs.brew.sh/Ruby-Style-Guide)
+- [Homebrew Tap Trust Documentation](https://docs.brew.sh/Tap-Trust)
diff --git a/README.md b/README.md
@@ -1,8 +1,71 @@
 # homebrew-cli
 
-Homebrew Formula for [codefresh/cli](https://github.com/codefresh-io/cli) tool.
+[![Tap Validation](https://github.com/codefresh-io/homebrew-cli/actions/workflows/tap-validation.yml/badge.svg)](https://github.com/codefresh-io/homebrew-cli/actions/workflows/tap-validation.yml)
 
+Homebrew Formula for Codefresh CLI tools:
+- [codefresh/cli](https://github.com/codefresh-io/cli) - Codefresh CLI V1 (legacy)
+- [codefresh/cli-v2](https://github.com/codefresh-io/cli-v2) - Codefresh CLI V2
+
+## Installation
+
+### Trusting the Tap (Required for Homebrew 6.0.0+)
+
+Starting with Homebrew 6.0.0, third-party taps require explicit trust before use. This is a security feature to protect users from potentially malicious code.
+
+**Option 1: Trust the entire tap (recommended for regular users)**
+```sh
+brew tap codefresh-io/cli
+brew trust codefresh-io/cli
+brew install codefresh  # or: brew install cf2
+```
+
+**Option 2: Trust specific formulae only**
 ```sh
 brew tap codefresh-io/cli
+brew trust --formula codefresh-io/cli/codefresh
 brew install codefresh
-```
+
+# Or for cf2:
+brew trust --formula codefresh-io/cli/cf2
+brew install cf2
+```
+
+**Option 3: Install without pre-tapping (implicit trust)**
+```sh
+brew install codefresh-io/cli/codefresh
+```
+
+### Legacy Installation (Homebrew < 6.0.0)
+
+```sh
+brew tap codefresh-io/cli
+brew install codefresh  # or: brew install cf2
+```
+
+## Available Formulae
+
+### Codefresh CLI V1 (`codefresh`)
+```sh
+brew install codefresh-io/cli/codefresh
+```
+
+The original Codefresh CLI providing full interface to interact with Codefresh.
+
+### Codefresh CLI V2 (`cf2`)
+```sh
+brew install codefresh-io/cli/cf2
+```
+
+The next-generation Codefresh CLI tool.
+
+## Why Trust is Required
+
+Homebrew formulae can execute arbitrary code during installation. By requiring explicit trust, Homebrew ensures you're aware of which third-party sources you're allowing to run code on your system.
+
+This tap is maintained by Codefresh and contains only formulae for official Codefresh CLI tools. For more information about our security practices, see [SECURITY.md](SECURITY.md).
+
+## More Information
+
+- [Homebrew Tap Trust Documentation](https://docs.brew.sh/Tap-Trust)
+- [Codefresh CLI Documentation](https://codefresh.io/docs/docs/cli/getting-started/)
+- [Report Security Issues](https://github.com/codefresh-io/homebrew-cli/security/advisories)