diff --git a/.github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug-report.md new file mode 100644 index 0000000..ffa301b --- /dev/null +++ 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 + + + +## Formula Affected + + +- [ ] `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 + + + +## Actual Behavior + + + +``` + +``` + +## Environment + +- **macOS version**: +- **Homebrew version**: +- **Formula version**: +- **Architecture**: + +## Additional Context + + + +## 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 new file mode 100644 index 0000000..0435b24 --- /dev/null +++ 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 + + +- [ ] `codefresh` (V1 CLI) +- [ ] `cf2` (V2 CLI) + +## New Version + +**Version**: +**Release URL**: + +## Checklist + +- [ ] New version is released and stable +- [ ] Release notes reviewed +- [ ] No known critical issues + +## Additional Context + + diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..2459a3e --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,54 @@ +## Description + + + +## 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 + + + +- [ ] 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**: +- **Architecture**: +- **Homebrew 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 + + + +## Release Notes + + + +## Additional Notes + + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..a64e96b --- /dev/null +++ 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 index 6dc6b5b..a5c1fa4 100644 --- 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 -``` \ No newline at end of file + +# 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) \ No newline at end of file diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..e346945 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,92 @@ +# Security Policy + +## Tap Security and Trust + +This Homebrew tap is maintained by Codefresh and provides formulae for official Codefresh CLI tools. We take security seriously and follow best practices to ensure the integrity of our formulae. + +### What We Do + +- **Official Source Only**: All formulae in this tap install binaries or build from official Codefresh repositories +- **Checksum Verification**: Binary downloads include SHA256 checksums to verify integrity +- **Transparent Build Process**: Source-based formulae (like `cf2`) build from tagged releases in public GitHub repositories +- **Regular Updates**: We keep formulae updated with the latest stable releases +- **Minimal Code**: Formulae contain only the necessary installation logic, reducing attack surface + +### What You Should Do + +Before trusting this tap, you should: + +1. **Review the Formulae**: All formulae are visible in the `Formula/` directory +2. **Verify the Source**: Check that URLs point to official `github.com/codefresh-io/` repositories +3. **Check Checksums**: For binary downloads, verify SHA256 checksums match official releases +4. **Monitor Updates**: Watch this repository for changes if you want to track updates + +### Homebrew Tap Trust + +Starting with Homebrew 6.0.0, taps require explicit trust to protect users from potentially malicious code. This is a security feature, not a deficiency of this tap. + +To trust this tap: +```sh +brew trust codefresh-io/cli +``` + +Or trust individual formulae: +```sh +brew trust --formula codefresh-io/cli/codefresh +brew trust --formula codefresh-io/cli/cf2 +``` + +### Reporting Security Issues + +If you discover a security vulnerability in this tap or our formulae, please report it responsibly: + +1. **Do not** open a public GitHub issue +2. Use GitHub's [Security Advisories](https://github.com/codefresh-io/homebrew-cli/security/advisories) feature +3. Or email security concerns to Codefresh security team + +Please include: +- Description of the vulnerability +- Steps to reproduce +- Potential impact +- Suggested fix (if applicable) + +We will respond to security reports within 48 hours and work to address valid issues promptly. + +### Supply Chain Security + +Our formulae follow these supply chain security practices: + +- **Pinned Versions**: We use specific version tags and commit SHAs +- **HTTPS Only**: All downloads use HTTPS URLs +- **Official Sources**: Downloads come only from official Codefresh repositories +- **License Declarations**: Formulae include license information where applicable +- **Build Transparency**: Source builds use public `Makefile` targets from official repositories + +### Verification + +You can verify the integrity of this tap by: + +1. **Checking the Repository**: This is the official tap at `github.com/codefresh-io/homebrew-cli` +2. **Reviewing Formula Content**: All formulae are plain Ruby files in the `Formula/` directory +3. **Comparing Checksums**: For binary downloads, compare SHA256 with official releases +4. **Building from Source**: The `cf2` formula builds from source, allowing full transparency + +### Additional Resources + +- [Homebrew Security Documentation](https://docs.brew.sh/Homebrew-Security-and-Supply-Chain) +- [Homebrew Tap Trust Documentation](https://docs.brew.sh/Tap-Trust) +- [Codefresh CLI Repository](https://github.com/codefresh-io/cli) +- [Codefresh CLI V2 Repository](https://github.com/codefresh-io/cli-v2) + +## Supported Versions + +We maintain formulae for actively supported versions of Codefresh CLI tools. Security updates are applied as new releases become available. + +| Formula | Status | Notes | +|---------|--------|-------| +| `codefresh` | Legacy/Maintenance | Version 1.x, maintained for backwards compatibility | +| `cf2` | Active | Version 2.x, actively developed and recommended | + +## License + +This tap is provided under the same license terms as the Codefresh CLI tools it distributes. See [LICENSE](LICENSE) for details.