Skip to content

Contributing to GitOps Promoter

Thanks for helping improve GitOps Promoter. The project is still young; we keep this guide short so you can ship a fix or feature without a long checklist.

From idea to merge

  1. Open an issue or discussion when it helps: bugs and feature work benefit from an issue; questions and design chat fit Discussions. Small or obvious changes can go straight to a PR when the intent is clear.
  2. Fork the repository on GitHub, clone your fork, and create a branch from main. Push work to your fork only.
  3. Make focused changes — one logical change per PR when possible.
  4. Run checks that match what you changed:
    • Go only (no CRD, webhook, or generated install / apply-config churn): go mod tidy, make lint, make test-parallel, make fuzz-replay (replay seeds (f.Add) + corpus (testdata/fuzz); same as CI).
    • APIs, CRDs, webhooks, or bundled install YAML (anything make build-installer regenerates—config/, dist/install.yaml, deepcopy/applyconfiguration, extension icon output, hack/celcost/report.md): make build-installer, commit the full diff, then go mod tidy, make lint, make test-parallel.
    • SCM interfaces (internal/scms/): make mockery-gen, commit internal/scms/mock/ (CI checks this separately from build-installer).
    • ui/: make lint-ui, make test-unit-test-extension, make test-ui-test-dashboard.
    • docs/ (this site): make lint-docs.
    • CI also runs Nilaway and spell checking; use make nilaway-no-test locally if you want parity before pushing.
  5. Open a pull request from your fork into main on argoproj-labs/gitops-promoter, with a short title and enough context for reviewers (what changed, why). Use Fixes #123 / Closes #123 when it applies. Every commit must be DCO sign-off (see below).
  6. Iterate on review — CI must be green; maintainers will help get it over the line.

Testing expectations

Substantive new or changed user-facing behavior (APIs, controllers, webhooks, or UI) should include automated tests in the same pull request unless maintainers explicitly agree otherwise. Reviewers expect this during code review, and failing tests block merge.

How we test (stack):

  • Go (controller and cluster behavior): Ginkgo suites with envtest, which runs a real Kubernetes API server from test binaries for integration-style tests against our APIs and reconcilers.
  • UI (dashboard and Argo CD extension): unit tests via the Node.js tooling and npm scripts used in CI (lint and test targets for the dashboard and extension).
  • Static analysis: golangci-lint, Nilaway, and other checks run in CI on every change.

DCO sign-off

Pull requests must pass the Developer Certificate of Origin (DCO) check: every commit needs a Signed-off-by line (this is not GPG signing). The email in that line should match your GitHub account. Use git commit -s / git commit --amend -s when you forget.

To add a prepare-commit-msg hook that signs off automatically, follow Argoproj’s instructions: copy community/dco-signoff-hook/prepare-commit-msg from argoproj/argoproj into .git/hooks/prepare-commit-msg in your clone (merge with an existing hook if you already have one), and ensure it is executable (chmod +x).

Where things live

Area Path
Controller entrypoint cmd/
Reconcilers internal/controller/
API types (CRDs) api/v1alpha1/
Install / RBAC / CRD bases config/
Metrics internal/metrics/
SCM provider integrations internal/scms/ (see Adding an SCM Provider)
User docs (MkDocs) docs/
Dashboard & Argo CD extension ui/
Envtest-based integration tests internal/ (via Ginkgo)

Design patterns

  • Reconcilers — Follow controller-runtime style used in internal/controller/: idempotent reconcile loops, structured logging, and the same client/scheme/recorder patterns as neighboring controllers.
  • Tests — Extend Ginkgo suites under internal/ and reuse envtest patterns from internal/controller/suite_test.go when testing cluster behavior; mirror how similar resources are covered today.
  • APIs and RBAC — Express API permissions with // +kubebuilder:rbac on the reconcilers in internal/controller/*_controller.go (not by editing config/rbac/role.yaml). Regenerate via make build-installer so rules stay aligned with what the binary actually needs.
  • Commit status controllers — If you create or update CommitStatus objects, follow Commit status development best practices (standard labels, owner references, and keys that match PromotionStrategy config).
  • Metrics — Register operational metrics in internal/metrics and describe them for operators in Metrics (see the note in internal/metrics/metrics.go).
  • SCM providers — New or extended provider code lives under internal/scms/<provider>/. Call metrics.RecordSCMCall for every SCM REST request so metrics and debug logs stay correct; see Adding an SCM Provider.
  • Finalizers — When adding or changing deletion ordering, follow Using finalizers (naming, who adds them, and how to watch related objects during delete).
  • Status writes — Status subresource updates go through the deferred utils.HandleReconciliationResult using per-controller SSA; see Maintaining resource status.

Questions?

Use Discussions or comment on your PR. Thanks again.