Development workflow

The day-to-day cycle for landing a change in the Datadog Agent.

Branches

• The default branch is main. All PRs target main.
• Release branches follow 7.NN.x (for example, 7.55.x). Backports go through cherry-pick PRs and are gated by the qa/skip-qa and qa/rc-required labels.
• Feature branches live in the contributor's fork, then are submitted as PRs.

Opening a PR

1. Sign the CLA if you are an external contributor — handled automatically by cla.yml GitHub Action.

2. Follow .github/PULL_REQUEST_TEMPLATE.md. The template enforces a description, a "Motivation" section, and a "Describe how to test/QA your changes" section.

3. Add release notes for any user-facing or operator-facing change. The repo uses reno-style YAML notes under releasenotes/notes/ (and releasenotes-dca/notes/ for the Cluster Agent). Generate one with:

   dda inv release.add-release-note "summary of the change"

4. Run linters and tests locally. CI will run them too, but the pre-commit hook (.pre-commit-config.yaml) and the local dda inv linter.go save round trips.

5. Push to your fork and open a PR. GitHub Actions will:

   • Apply labels (labeler.yml, add-label-pr.yml, code-review-complexity.yml).
   • Add reviewers based on CODEOWNERS and the add-reviewer-bot-pr.yml workflow.
   • Trigger CI on GitLab (the primary CI system).

CI pipelines

The repository has two CI systems:

System	Where	What it runs
GitLab	.gitlab-ci.yml + .gitlab/	Primary. Builds, unit tests, integration tests, packaging, deploys.
GitHub Actions	.github/workflows/	Auxiliary. Repo housekeeping, release automation, documentation, some lints.

Most blocking checks are on GitLab. PR-branch CI runs a subset to keep wall-clock time low; the full E2E matrix runs on main and release branches.

The note from AGENTS.md worth internalizing:

Most E2E tests only run on main, release branches (N.N.x), and RC tags — not on PR branches. Be extra careful reviewing packaging, startup/shutdown, and cross-component changes.

If a change crosses one of those high-risk boundaries it likely needs the qa/rc-required label so QA picks it up before the next release candidate.

Code review

• CODEOWNERS (.github/CODEOWNERS) lists the teams that own each path. They are auto-assigned. The merge queue requires their approval before merging.
• Code-review skills are published as Claude plugins from the Datadog Claude Marketplace — /go-review, /go-improve, /py-review, /py-improve. They are optional but used in practice.
• Stale documentation is treated as a bug. If a PR changes behavior but doesn't touch the corresponding docs, comments, or doc-strings, expect the reviewer to ask for them in the same PR.

Merge queue

The merge queue is enabled. Once a PR has approvals and green CI, the author (or bot) adds it to the queue. The queue rebases against main and re-runs CI before merging. add-dependabot-pr-to-mq.yml automates queue entry for dependency bumps.

Backports

To backport a change to a release branch:

1. Land the change on main.
2. Cherry-pick into the release branch, opening a PR with [backport <branch>] in the title.
3. The backport-pr.yml workflow can automate this when the PR has the right label.

Release process

• Releases are coordinated by the agent-platform team and tooled in tasks/release.py. The full process is documented in the developer site under docs/public/.
• Release notes are aggregated from releasenotes/notes/*.yaml into CHANGELOG.rst at release time. Do not edit CHANGELOG.rst manually.
• Version metadata lives in release.json.

What to update with each PR

A short checklist:

• Code under pkg/, comp/, cmd/, etc.

• Tests next to the code (*_test.go) or under test/.

• Release notes under releasenotes/notes/ if user-visible.

• Documentation in docs/public/ for new operator-facing behavior.

• The relevant AGENTS.md if conventions change. The root AGENTS.md has an explicit section on this:

  AI agents: when working on any task, if you notice a gap or inaccuracy in an AGENTS.md or skill file, fix it.

• BUILD.bazel files, kept in sync via dda inv tidy.

The full list of build tags lives in tasks/build_tags.py.

Common pitfalls

From AGENTS.md's review guidelines section:

• E2E coverage with fakeintake. Unit tests aren't enough for changes that affect outgoing payloads. Add an E2E test that checks fakeintake.
• Branch-conditional CI. Bugs in packaging, startup, and cross-component messaging may not be caught by PR CI. Apply qa/rc-required if in doubt.
• Multi-platform divergence. Linux, Windows, macOS code paths drift. Touch one, test the others — at minimum read the *_linux.go / *_windows.go siblings.
• Concurrency. Send-on-closed-channel and goroutine leaks are recurring bugs at component shutdown. New goroutines need a teardown story.
• Graceful degradation. Functions exposed to UIs and APIs must return safe defaults when a dependency isn't ready.