Contributing to Argo CD

Guidelines for contributing code to the Argo CD project

Overview

The Argo CD project continuously grows, both in terms of features and community size. It gets adopted by more and more organizations which entrust Argo CD to handle their critical production workloads. Thus, we need to take great care with any changes that affect compatibility, performance, scalability, stability and security of Argo CD.

Before starting work on larger features, please raise an Enhancement Proposal or Bug Issue first. This ensures your idea aligns with the project’s strategy and increases the likelihood of your code being merged.

Quick Start

The fastest way to start contributing is to look for issues labeled with:

• help-wanted
• good first issue

These issues have already been triaged and accepted. If attached to the next version milestone, they’ll receive prioritized reviews.

Enhancement Proposal Process

Triage Workflow

Enhancement proposals go through a transparent triage process:

1. Incoming - New proposals waiting for triage
2. Active - Currently being triaged
3. Accepted - Approved for implementation
4. Declined - Rejected with reasoning provided
5. Needs discussion - Requires more information or a design document

Triage Cadence

• Triage happens in our weekly contributor’s meeting
• Everyone is invited to participate
• We aim to triage at least 10 proposals per week
• Proposals are generally processed in FIFO order

Proposal Outcomes

Accepted

When a proposal is accepted, it’s been deemed valuable to the community and fits the strategic roadmap. Implementation may begin by the proposal creator or another community member.

Declined

Proposals are declined when they don’t align with project direction, would be breaking for many users, or don’t meet strategic goals. Discussion is facilitated before declining.

Needs Discussion

Some proposals require more information or a formal design document. You may be asked to provide additional details or join a contributor’s meeting.

Design Documents

For substantial changes, a formal design document is required using this template.

Design documents should address:

• The problem being solved
• Proposed solution and alternatives
• Migration and upgrade paths
• Security implications
• Performance considerations

Design documents are submitted as PRs and discussed during review. Once merged, the design is approved for implementation.

Contributor Meetings

Join our weekly virtual meetings to discuss enhancements and participate in triage:

• Schedule: Every Thursday at 8:15 AM Pacific Time (convert to your timezone)
• Format: Zoom meeting
• Agenda Document (includes Zoom link)

Please add your items to the agenda before the meeting.

Before Submitting Your First PR

1. Read the Guidelines

   Familiarize yourself with the Toolchain Guide to understand our build system and CI processes.

2. Set Up Your Environment

   Follow the Development Environment guide to configure your local setup.

3. Understand the Process

   Review our PR submission requirements and quality standards.

Submitting Pull Requests

PR Title Convention

Use one of these prefixes for your PR title:

• ci: - Updates or improves CI workflows
• fix: - Bug fixes
• feat: - New features
• test: - Adds or improves tests
• docs: - Documentation improvements
• chore: - Internal improvements (build, tests, etc.)
• refactor: - Code refactoring without new features or bug fixes

Bad Example

Add documentation for GitHub SSO integration

Before Submitting

Pre-submission Checklist

1. Rebase your branch against upstream main:

git fetch upstream
git rebase upstream/main

2. Run pre-commit checks:

make pre-commit-local

3. Ensure all tests pass locally:

make test

CI Pipeline

Your PR must pass these automated checks:

• Build the Go code (make build)
• Generate API glue code and manifests (make codegen)
• Run Go linter (make lint)
• Run unit tests (make test)
• Run E2E tests (make test-e2e)
• Build and lint UI code (make lint-ui)
• Build the argocd CLI (make cli)

Code Coverage

We use CodeCov to track test coverage. Your PR should:

• Not significantly decrease overall coverage
• Include tests for new features
• Aim for at least 80% coverage for new modules

Check coverage for a specific module:

make test TEST_MODULE=github.com/argoproj/argo-cd/server/cache

Cherry-Picking Fixes

For bug fixes that should be backported to release branches:

1. Add a cherry-pick/x.y label to your PR (e.g., cherry-pick/3.1)
2. The cherry-pick bot will automatically create backport PRs when your PR merges

If you don’t have label permissions, ask a maintainer to add them for you.

Getting Help

Need guidance? Join us on Slack:

• Join Argo Slack
• Connect in the #argo-cd-contributors channel

Additional Resources

Development Environment

Set up your local development environment

Architecture

Understand Argo CD’s component architecture

Toolchain Guide

Learn about our build tools and processes

GitHub Repository

Visit the source code repository