Skip to content

docs: adding DAG overview of tasks#177

Merged
sunib merged 6 commits into
mainfrom
docs
Jul 1, 2026
Merged

docs: adding DAG overview of tasks#177
sunib merged 6 commits into
mainfrom
docs

Conversation

@sunib

@sunib sunib commented Jul 1, 2026

Copy link
Copy Markdown
Contributor

Description

Brief description of the changes in this PR.

Type of Change

Please delete options that are not relevant.

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Documentation update
  • Refactoring (no functional changes)
  • Performance improvement
  • Test coverage improvement

Testing

  • Unit tests pass locally
  • Integration tests pass locally
  • Manual testing completed (if applicable)
  • New tests added for new functionality

Checklist

  • My code follows the style guidelines of this project
  • I have performed a self-review of my own code
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • I have added tests that prove my fix is effective or that my feature works
  • New and existing unit tests pass locally with my changes
  • Any dependent changes have been merged and published in downstream modules

Related Issues

Closes #(issue number)

Screenshots (if applicable)

Add screenshots to help explain your changes.

Additional Notes

Any additional information that reviewers should know.

Summary by CodeRabbit

  • New Features
    • Added an e2e cleanup task to remove cached per-spec repository checkouts and related artifacts.
    • Improved Flux operator installation to use deterministic, pinned manifests and artifact-based deployment.
  • Documentation
    • Expanded Task/DAG and e2e/runbook documentation; clarified what task lint covers.
    • Removed obsolete design and migration docs.
  • Build & CI
    • Reworked linting gates and Task lint orchestration (Go, Actions, Dockerfiles, Helm).
    • Hardened CI/developer container builds, added Hadolint configuration, and switched Codecov uploads to OIDC.

@coderabbitai

coderabbitai Bot commented Jul 1, 2026

Copy link
Copy Markdown

Review Change Stack

📝 Walkthrough

Walkthrough

The PR updates Task-based lint orchestration, CI lint/upload behavior, devcontainer tool versions, Task documentation, and E2E Flux bootstrap and cleanup tasks. Three legacy docs are removed, and docs/tasks-overview.md becomes the main Task workflow reference.

Changes

Task orchestration and linting updates

Layer / File(s) Summary
Task lint graph and repo lint rules
Taskfile-build.yml, .golangci.yml, .hadolint.yaml, AGENTS.md
lint becomes an aggregate task over Go, Dockerfile, GitHub Actions, and Helm linting, with per-task sources and task lint guidance updated; Go lint exclusions and Hadolint repo rules are adjusted to match.
CI workflow and devcontainer toolchain
.github/workflows/ci.yml, .devcontainer/Dockerfile
The CI workflow switches to task lint, uses OIDC for Codecov uploads, and enables id-token permissions; the devcontainer Dockerfile adds pipefail shells, hadolint installation, and centralized version variables for CI/dev tooling.
Tasks overview document
docs/tasks-overview.md
Adds the Task workflow overview, DAG diagrams, incremental rerun behavior, stamp model, and Task style rules.
cleanup-stamp-repos task
test/e2e/Taskfile.yml
Adds a task that reports and removes .stamps/repos and .stamps/e2e-repo-artifacts when present.
Flux operator e2e bootstrap
test/e2e/Taskfile.yml, test/e2e/setup/flux-operator/flux-instance.yaml
The Flux e2e bootstrap now renders operator YAMLs into stamp-local files, uses a pinned operator-manifest ref, and interpolates ${FLUX_VERSION} in the Flux instance manifest.

Estimated code review effort: 4 (Complex) | ~45 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Description check ⚠️ Warning The PR description follows the template, but the Description, Related Issues, Screenshots, and Additional Notes sections are still placeholders. Replace the placeholders with a brief summary of the actual changes, add any related issue number, and include notes or screenshots if relevant.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title is concise and matches the main docs change about adding a task DAG overview.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (1)
docs/tasks-overview.md (1)

41-51: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Consider adding cleanup-stamp-repos to the task table.

The same PR adds cleanup-stamp-repos to test/e2e/Taskfile.yml, but this table of important tasks doesn't mention it alongside clean-cluster/clean.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/tasks-overview.md` around lines 41 - 51, Add the missing
`cleanup-stamp-repos` entry to the task table in `docs/tasks-overview.md` so it
appears alongside `task clean-cluster` and `task clean`. Update the “What it
does” and “When to run it” text to briefly describe its purpose in the same
style as the existing task rows, keeping the documentation aligned with the
`test/e2e/Taskfile.yml` task set.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/tasks-overview.md`:
- Line 18: Fix the typos in the docs text within the tasks overview entry:
change “to much” to “too much” in both occurrences and “powerfull” to “powerful”
in the same sentence. Update the wording in the affected paragraph only, keeping
the rest of the content unchanged and preserving the existing style of the
documentation.

---

Nitpick comments:
In `@docs/tasks-overview.md`:
- Around line 41-51: Add the missing `cleanup-stamp-repos` entry to the task
table in `docs/tasks-overview.md` so it appears alongside `task clean-cluster`
and `task clean`. Update the “What it does” and “When to run it” text to briefly
describe its purpose in the same style as the existing task rows, keeping the
documentation aligned with the `test/e2e/Taskfile.yml` task set.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: bc804d48-602b-434e-be1e-200d44829054

📥 Commits

Reviewing files that changed from the base of the PR and between 318d718 and 97fbbaa.

📒 Files selected for processing (5)
  • docs/design/audit-ingestion-decision-record.md
  • docs/design/best-practices-webhook-ingress.md
  • docs/task-migration-plan.md
  • docs/tasks-overview.md
  • test/e2e/Taskfile.yml
💤 Files with no reviewable changes (3)
  • docs/task-migration-plan.md
  • docs/design/audit-ingestion-decision-record.md
  • docs/design/best-practices-webhook-ingress.md

Comment thread docs/tasks-overview.md Outdated

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

♻️ Duplicate comments (1)
.github/workflows/ci.yml (1)

401-402: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Same fail_ci_if_error: true concern as the unit-test upload.

This directly contradicts the "Fail-safe: a coverage hiccup must never fail the e2e gate" comment on the adjacent Collect E2E coverage step (Line 381) — collection failures are swallowed, but a subsequent Codecov upload failure will now fail the whole e2e job.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/ci.yml around lines 401 - 402, The Codecov upload in the
e2e workflow is still configured to fail the job on upload errors, which
conflicts with the fail-safe coverage collection behavior. In the e2e coverage
upload step in the CI workflow, remove or disable fail-on-error behavior so a
Codecov hiccup does not fail the entire e2e gate, while keeping the `Collect E2E
coverage` step tolerant of collection issues.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/ci.yml:
- Line 23: The workflow-level id-token permission is too broad and should only
be granted to the jobs that actually upload to Codecov. Remove the global
id-token: write from the CI workflow permissions and add it under the test and
e2e job permissions instead, keeping the rest of the jobs (lint, build, etc.)
without OIDC access. Use the job names test and e2e to locate the exact places
to scope the permission.
- Around line 226-227: The Codecov upload step in the CI workflow is currently
configured to fail the job on upload errors, which conflicts with the pipeline’s
non-fatal coverage collection behavior. Update the Codecov upload configuration
in the workflow so coverage upload failures are tolerated rather than failing
the unit-test and e2e gates, keeping the behavior consistent with the existing
fail-safe logic used for coverage collection elsewhere in the CI job.

In `@Taskfile-build.yml`:
- Around line 164-186: The parallel lint fan-out can race with
generate/manifests because lint-helm triggers helm-sync -> manifests ->
generate, which rewrites generated API and CRD files while lint-golang is
scanning api/**/*.go. Update the Taskfile build flow so lint-golang does not run
concurrently with generate, either by making lint-golang depend on
generate/manifests or by making the top-level lint target wait for those tasks
before fanning out, using the existing lint-golang, lint-helm, generate, and
manifests task names to place the fix correctly.

---

Duplicate comments:
In @.github/workflows/ci.yml:
- Around line 401-402: The Codecov upload in the e2e workflow is still
configured to fail the job on upload errors, which conflicts with the fail-safe
coverage collection behavior. In the e2e coverage upload step in the CI
workflow, remove or disable fail-on-error behavior so a Codecov hiccup does not
fail the entire e2e gate, while keeping the `Collect E2E coverage` step tolerant
of collection issues.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: fdcb4768-2a0b-4884-95e7-d2e4f0e755d6

📥 Commits

Reviewing files that changed from the base of the PR and between 97fbbaa and f591f68.

📒 Files selected for processing (7)
  • .devcontainer/Dockerfile
  • .github/workflows/ci.yml
  • .golangci.yml
  • .hadolint.yaml
  • AGENTS.md
  • Taskfile-build.yml
  • docs/tasks-overview.md
💤 Files with no reviewable changes (1)
  • .golangci.yml
✅ Files skipped from review due to trivial changes (1)
  • .hadolint.yaml

Comment thread .github/workflows/ci.yml Outdated
Comment thread .github/workflows/ci.yml Outdated
Comment thread Taskfile-build.yml Outdated

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (1)
Taskfile-build.yml (1)

36-59: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Remove leftover webhook generation now that config/webhook/manifests.yaml is dropped from generates:.

generates: (lines 37-38) no longer lists the webhook manifest, matching the webhook-removal effort, but cmds still creates config/webhook (Line 42) and invokes controller-gen's webhook marker (Line 53). This keeps writing an untracked file that Task can't fingerprint/prune, effectively regenerating stale cruft on every run.

♻️ Proposed cleanup
-        mkdir -p config/crd/bases config/rbac config/webhook
+        mkdir -p config/crd/bases config/rbac
         ...
         {{.CONTROLLER_GEN}} \
           rbac:roleName=gitops-reverser \
           crd \
-          webhook \
           paths=./api/... \
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@Taskfile-build.yml` around lines 36 - 59, The Taskfile build still
regenerates webhook output even though `config/webhook/manifests.yaml` was
removed from `generates:`. Update the `cmds` block in `Taskfile-build.yml` to
stop creating `config/webhook` and remove the `webhook` argument from the
`controller-gen` invocation so the `controller-gen` step only writes the CRD and
RBAC artifacts that are still tracked.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@Taskfile-build.yml`:
- Around line 36-59: The Taskfile build still regenerates webhook output even
though `config/webhook/manifests.yaml` was removed from `generates:`. Update the
`cmds` block in `Taskfile-build.yml` to stop creating `config/webhook` and
remove the `webhook` argument from the `controller-gen` invocation so the
`controller-gen` step only writes the CRD and RBAC artifacts that are still
tracked.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: a76fc82c-aedb-4a93-b879-a19c61ba9f2a

📥 Commits

Reviewing files that changed from the base of the PR and between f591f68 and d577b2d.

📒 Files selected for processing (3)
  • .github/workflows/ci.yml
  • Taskfile-build.yml
  • docs/tasks-overview.md

sunib and others added 2 commits July 1, 2026 11:46
…rgetting files in sources for examples) and pinning all flux versions (also for cluster buildup).
The `task lint cache check` step failed with "Illegal option -o pipefail":
container jobs default to `sh`, which rejects `set -o pipefail`. Pin the step
to `shell: bash` (which GitHub already invokes with -eo pipefail).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@sunib
sunib merged commit f7a8b6a into main Jul 1, 2026
14 checks passed
@sunib
sunib deleted the docs branch July 1, 2026 18:21
@coderabbitai coderabbitai Bot mentioned this pull request Jul 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant