harbor-cli/CONTRIBUTING.md

Contributing to Harbor CLI

Thank you for your interest in contributing to the Harbor CLI project! We welcome contributions of all kinds, from bug fixes and documentation improvements to new features and suggestions.

Overview

The Harbor CLI is a powerful command-line tool to interact with the Harbor container registry. It's built in Go and helps users manage Harbor resources like projects, registries, artifacts, and more — directly from their terminal.

Getting Started

Run using Container

You can try the CLI immediately using Docker:

docker run -ti --rm -v $HOME/.harbor/config.yaml:/root/.harbor/config.yaml registry.goharbor.io/harbor-cli/harbor-cli --help

Alias (Optional)

echo "alias harbor='docker run -ti --rm -v \$HOME/.harbor/config.yaml:/root/.harbor/config.yaml registry.goharbor.io/harbor-cli/harbor-cli'" >> ~/.zshrc
source ~/.zshrc

Build from Source

Make sure Go is installed (≥ v1.24).

git clone https://github.com/goharbor/harbor-cli.git && cd harbor-cli
go build -o harbor-cli cmd/harbor/main.go
./harbor-cli --help

Alternatively, use Dagger for isolated builds:

dagger call build-dev --platform darwin/arm64 export --path=./harbor-cli
./harbor-dev --help

Project Structure

..
├── cmd/harbor/           # Entry point (main.go) and all CLI commands (Cobra-based)
├── pkg/                  # Shared utilities and internal packages used across commands
├── doc/                 # Project documentation
├── test/                 # CLI tests and test data
├── .github/              # GitHub workflows and issue templates
├── go.mod / go.sum       # Go module dependencies
└── README.md             # Project overview and usage

How to Contribute

1. Fork and Clone

git clone https://github.com/your-username/harbor-cli.git
cd harbor-cli

2. Create Your Feature Branch

git checkout -b feat/<your-feature-name>

3. Make Your Changes

Follow coding and formatting guidelines.

4. Test Locally

Ensure your changes work as expected.

gofmt -s -w .
dagger call build-dev --platform darwin/arm64 export --path=./harbor-cli  #Recommended
./harbor-dev --help

If dagger is not installed in your system, you can also build the project using the following commands:

gofmt -s -w .
go build -o ./bin/harbor-cli cmd/harbor/main.go
./bin/harbor-cli --help

5. Update Documentation

Before committing, always regenerate the documentation if you've made any code changes or added new commands:

dagger call run-doc export --path=./doc

6. Commit with a clear message

git commit -s -m "feat(project): add delete command for project resources"

7. Push and Open a PR

git push origin feat/<your-feature-name>

Then, Open a Pull Request on GitHub

🧪 Running Tests

✅ Note: Add your CLI or unit tests to the test/ directory.

go test ./...

🧹 Code Guidelines

• Use go fmt ./... to format your code.
• Use descriptive commit messages:
  • feat: New feature
  • fix: Bug fix
  • docs: Documentation only
  • test: Adding or updating tests
  • refactor: Code cleanup
  • chore: Maintenance tasks

📬 Communication

• Slack: Join us in #harbor-cli
• Issues: Use GitHub Issues for bugs, ideas, or questions.
• Mailing List:
  • Users: harbor-users@lists.cncf.io
  • Devs: harbor-dev@lists.cncf.io

📄 License

All contributions are under the Apache 2.0 License.

---

Thank you for contributing to Harbor CLI! Your work helps improve the Harbor ecosystem for everyone. 🙌