Skip to content

Add AGENTS.md#22

Merged
tamalsaha merged 1064 commits into
mainfrom
add-agents-md
May 15, 2026
Merged

Add AGENTS.md#22
tamalsaha merged 1064 commits into
mainfrom
add-agents-md

Conversation

@tamalsaha
Copy link
Copy Markdown

Summary

  • Add AGENTS.md describing repo purpose, architecture, common Make targets, and conventions for coding agents (Claude Code and similar tools).

Test plan

  • CI green

dependabot Bot and others added 30 commits December 17, 2025 14:16
…t-sh#3404)

Bumps [tj-actions/changed-files](https://github.com/tj-actions/changed-files) from 47.0.0 to 47.0.1.
- [Release notes](https://github.com/tj-actions/changed-files/releases)
- [Changelog](https://github.com/tj-actions/changed-files/blob/main/HISTORY.md)
- [Commits](tj-actions/changed-files@v47.0.0...v47.0.1)

---
updated-dependencies:
- dependency-name: tj-actions/changed-files
  dependency-version: 47.0.1
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Signed-off-by: Marcin Franczyk <marcin0franczyk@gmail.com>
* ENG-10378  | Cross vCluster APIs (loft-sh#3389)

* Add vcluster.yaml resource proxy configuration

* Start proxy

* Move proxy config to experimental

* Rename start func

* Vendor in dev platform changes

* Bump admin-apis

* Update config schema (loft-sh#3406)

* Cleanup vendor modules (loft-sh#3415)

* Cleanup duplicate config entry, revert admin apis bump (loft-sh#3416)

* Eng 10546/cleanup duplicate config (loft-sh#3417)

* Cleanup duplicate config entry, revert admin apis bump

* Update vendor, cleanup not used config struct

* ENG-10546 | Inject custom error responder (loft-sh#3428)

* Extract StartAPIServer from StartAPIServiceProxy

* Add HandlerWithErrorResponder to allow injection of custom errorResponder
…#3435)

Bumps [anchore/sbom-action](https://github.com/anchore/sbom-action) from 0.20.11 to 0.21.0.
- [Release notes](https://github.com/anchore/sbom-action/releases)
- [Changelog](https://github.com/anchore/sbom-action/blob/main/RELEASE.md)
- [Commits](anchore/sbom-action@v0.20.11...v0.21.0)

---
updated-dependencies:
- dependency-name: anchore/sbom-action
  dependency-version: 0.21.0
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
…oxy (loft-sh#3436)

* Add config validation for experimental custom resource proxy
…ctures

- Restructure README to be use-case based, aligned with vcluster.com homepage
- Add new architectures: Standalone, Auto Nodes, Private Nodes with expandable sections
- Add What's New section highlighting v0.30 (VPN & Netris) and v0.26 (Hybrid Scheduling)
- Update use cases table with correct solution links
- Reimagine Key Features section with better organization
- Add architecture comparison table and expandable architecture details
- Add architecture diagrams (PNG) for all architecture types
- Update social badges: Slack (4.2K+), X/Twitter (3.5K+), LinkedIn (14K+)
- Add Killercoda section for browser-based testing
- Update Trusted By section with correct case study links
- Expandable Conference Talks and Community Voice sections (latest to oldest)
- Simplify contributing section
- Reduce logo size and spacing
- Fix all broken links and update to correct vcluster.com URLs
…t-sh#3437)

Backport failures previously aborted silently, requiring log diving
to understand which files conflicted. With commitConflicts enabled,
PRs are created with conflict markers visible in the diff, letting
reviewers gauge resolution effort at a glance.

Addresses OPS-461
…t-sh#3449)

Linear sync created duplicate comments on issues when same ID appeared
in both PR body and branch name. Example: ENG-8061 got two identical
"Now available in stable release v0.30.4" comments 1 second apart.

Root cause: IssueIDs() extracted from both PR body AND branch name,
returning duplicates when both contained the same issue reference.
This was exposed by commit e480400 which added stable release comments
for already-released issues - before that, duplicates were silently
skipped because issue was already in "Released" state.

Resolves OPS-460
…oft-sh#3434)

* fix: add missing slash after port in registry proxy URL replacement

* feat: Refactor helper function and add tests
Fixes an issue when a single architecture image was pushed to the private registry
PRs occasionally merged with out-of-sync vendor directories, causing
build failures after merge. Root cause: go mod tidy/vendor not run
before committing changes to go.mod or Go files.

This check runs go mod tidy && go mod vendor, then uses git status
--porcelain to detect any uncommitted changes. Fails fast with clear
instructions if developer forgot to sync.

Follows existing pattern from "Verify schema changes" step in same
workflow.

Related: OPS-368
…oft-sh#3469)

DEVOPS-471

Hardcoded \w{3}-\d{4} regex only matched 3-letter team keys like
ENG or OPS. Linear renamed OPS to DEVOPS (6 chars), breaking issue
detection in PR bodies and branch names.

New regex \w{2,10}-\d{1,5} supports:
- Team keys from 2-10 characters (QA, ENG, DEVOPS, etc.)
- Issue numbers from 1-5 digits (realistic for any team)

Added test cases for DEVOPS, QA, mixed team keys, and edge cases.
mfranczy and others added 28 commits April 22, 2026 21:53
Signed-off-by: Marcin Franczyk <marcin0franczyk@gmail.com>
If telemetry is not disabled explicitly(enabled by default on
installation), it unnecessarily introduces lag to the completion script
generation and completion generation during usage in shell.

This PR skips entirely telemetry when it is either `completion`
subcommand or hidden magic commands for completion script purpose.
loft-sh#3888)

Signed-off-by: Marcin Franczyk <marcin0franczyk@gmail.com>
- google.golang.org/grpc v1.78.0 → v1.80.0 (fixes SNYK-GOLANG-GOOGLEGOLANGORGGRPC-15691172, incorrect authorization via malformed :path headers)
- github.com/buger/jsonparser v1.1.1 → v1.1.2 (fixes SNYK-GOLANG-GITHUBCOMBUGERJSONPARSER-15674455, panic on malformed JSON)
- go.opentelemetry.io/otel v1.40.0 → v1.43.0 (fixes baggage header DoS and untrusted search path via kenv)

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
…-sh#3899)

* ci(e2e-ginkgo): post sticky PR comment with last e2e run status

Mirrors loft-sh/loft-enterprise#6754 and loft-sh/vcluster-pro#1728 for the
e2e-ginkgo workflow.

When the workflow detects a PR description edit that does not change the
label-filter block, it skips the e2e-tests job. GitHub then renders the PR
check as "Skipped", hiding the actual status of the last real run.

This change posts a sticky comment from the e2e-tests job using
loft-sh/github-actions/.github/actions/sticky-pr-comment@sticky-pr-comment/v1.
The comment carries:

- Status (Passed / Failed / Cancelled, derived from job.status so build/setup
  failures also surface).
- Head commit SHA.
- A link to the workflow run.

Because the upsert step lives inside e2e-tests and not in a separate
unconditional job, it is skipped together with the rest of the job - which is
exactly what we want: the previous comment is preserved and the last real
status stays visible on the PR.

The workflow-level permission was bumped from pull-requests: read to
pull-requests: write so secrets.GITHUB_TOKEN can upsert the comment.

The marker (<!-- e2e-ginkgo-status -->) and title ("E2E Ginkgo Tests") are
scoped to this workflow so it does not collide with the equivalent comments
from e2e-next in vcluster-pro or e2e-ginkgo in loft-enterprise.

* ci(e2e-ginkgo): skip sticky comment upsert on fork PRs

GITHUB_TOKEN is read-only for pull_request events from forks regardless
of the workflow-level permissions block, so the upsert step 403s. Gate
the step on same-repo PRs only; fork PRs skip it cleanly.
* chore(e2e-next): LazyVCluster initialization

* chore(e2e-next): fix lint

* chore(e2e-next): add failed vcluster diagnostic

* chore(e2e-next): Update suites to use lazyvcluster

* chore(e2e-next): fix conflicts

* chore(e2e-next): readme fix

* chore(e2e-next): update e2e-next .claude/ rules and references

* chore(e2e-next): fix not working tests

* chore(e2e-next): fixes

* chore(e2e-next): lint fix

* chore(e2e-next): remove randomize

* chore(e2e-next); remove temp file

* chore(e2e-next): fixes after CR
Fixes Resource not accessible by integration (HTTP 403)
…grade pod

`vcluster node upgrade` supported a `--bundle-repository` flag on the
local CLI but never forwarded it into the in-pod `/vcluster node upgrade`
command, so setting it was a silent no-op. Also, the flag default was a
hard-coded github URL — overriding it in the upgrade pod meant we could
not honor the image's own default for air-gapped or CP-served bundles.

Change:

- Default the CLI flag to empty. Empty means "use whatever the upgrade
  image bakes in" (still the github URL for standard images; something
  else for CP-served bundles).
- When non-empty, pass the value into the spawned upgrade pod's
  `--bundle-repository` arg.

ENGCP-562.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat: sanitise pod name in events
* fix(justfile): Add GO_PRIVATE envs to `_ensure_linters` command
vcluster connect/create and platform connect/create previously cleared
sleepmode.loft.sh/force-duration on a sleeping instance and silently
woke it, violating the prevent-wakeup contract.

WaitForVirtualClusterInstance and WaitForSpaceInstance now take a
forceWakeup parameter; when false, sleeping instances with an
unexpired force-duration return an error pointing at the explicit
wakeup command. resume / platform wakeup pass forceWakeup=true.

resolves ENGCP-349

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…-sh#3886)

* Enable wildcard support for custom resource proxy

* fix: skip disabled entries from cross-entry proxy validation

Disabled custom resource proxy entries do not produce a route at runtime
(parseProxyTargets filters by Enabled), so they should not participate in
wildcard/explicit conflict or group-version agreement checks.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Bind kine's metrics listener to 127.0.0.1:2381 and proxy it through the
control plane on /metrics/kine when a database backing store is in use.
Add a ServiceMonitor endpoint to scrape it. Snapshot restore explicitly
disables the listener to avoid a port conflict with the running kine.

Closes ENGCP-400

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds GCP OIDC auth, gcloud setup, and upload-report/reports-bucket/
workflow-file inputs to the run-ginkgo call sites in e2e-ginkgo.yaml
and e2e-ginkgo-nightly.yaml. Mirrors loft-sh/vcluster-pro#1766.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…oft-sh#3920)

* ci(release): switch to repository-dispatch composite for vcluster-docs notify

Why: legacy push-to-vcluster-docs path embedded vcluster-docs structure
(versioned-folder paths, partial generators, branch naming) into this repo.
That coupled docs layout to vcluster's release pipeline and meant any docs
restructure required PRs here. The new contract delegates routing entirely
to vcluster-docs's handle-source-release receiver (DEVOPS-888) via the
generic repository-dispatch action (DEVOPS-887).

Source repo now only emits:
- vcluster-released (config schema regen)
- vcluster-cli-released (CLI docs regen)

Receiver does classify-version → run-generator → PR. Removing
sync-config-schema.yaml entirely because its sole purpose was the
push-to-docs flow now superseded by the receiver.

Closes DEVOPS-889 (vcluster side / PR #3 of the cross-repo pair).

* ci(release): make vcluster-docs dispatch best-effort

Why: a transient dispatch failure (network blip, expired token, receiver
deploy in flight) should not fail the release pipeline. The receiver in
vcluster-docs reconciles on the next release if missed; docs lagging by
one release is much cheaper than blocking a release on a docs notify.

Mirrors the posture of the legacy update-docs job in loft-enterprise
sync-api.yaml, which carried continue-on-error for the same reason.

* ci(release): use existing org-level VCLUSTERLABS_DISPATCH_TOKEN

Why: this token already exists at org level with "All repositories"
visibility, so no new secret provisioning is needed in this repo. Single
rotation point shared with loft-enterprise's matching dispatch keeps both
source-repo invocations byte-identical and cuts the audit/rotation
surface in half compared to mirroring a new repo-level secret.

Spec named CROSS_REPO_DISPATCH_TOKEN; deviation is intentional and was
flagged in the PR description for reviewer visibility.
Bumps [github.com/docker/cli](https://github.com/docker/cli) from 28.2.2+incompatible to 29.2.0+incompatible.
- [Commits](docker/cli@v28.2.2...v29.2.0)

---
updated-dependencies:
- dependency-name: github.com/docker/cli
  dependency-version: 29.2.0+incompatible
  dependency-type: direct:production
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
…ill (loft-sh#3929)

without a top-level pointer, agents working on `.github/` workflows
discovered the reuse-not-inline convention only after touching a CI file
(the github-actions-developer skill auto-loads on those paths). a short
note in root CLAUDE.md surfaces it earlier and links the canonical
shared-actions repo.

closes DEVOPS-876
…d service (loft-sh#3918)

* Protect against deletion of resource proxy client service

* Generic apiservice deletion prevention policy

* Enable protection binding for metricsserver apiservice
…oft-sh#3932)

The /e2e-next/ rule routes all changes under that tree to eng-qa, but the
lifecycle (vcluster connect/pause/resume) and snapshot/restore suites
exercise control-plane behavior. Carve those two subtrees out to
eng-control-plane so review requests land with the team that owns the
underlying product code; eng-qa retains ownership of the framework
layer (clusters, setup, labels, init) and the rest of e2e-next.

Motivating example: loft-sh#3931, which fixes a KUBECONFIG race in the
connect/snapshot test helpers and should have routed to control-plane.
Parallel ginkgo workers share the filesystem, and any helper that runs
the vcluster CLI as a child process inherits KUBECONFIG from the OS env
(or defaults to ~/.kube/config). When two suites concurrently create
kind clusters, that shared file is rewritten and the current context
flips, so a vcluster CLI call may not find its host cluster at all.
Tests then fail with "couldn't find vcluster X" or "no configuration
has been provided" depending on which write wins the race.

The connect tests and the snapshot/restore helpers now set KUBECONFIG
on the child cmd's env to point at the framework's per-cluster temp
kubeconfig. The programmatic connectcmd.Run used by snapshot restore
reads the same ambient env, so override and restore KUBECONFIG around
that call too. snapshotCtx threads the host kubeconfig through
createSnapshot / restoreVCluster / runVClusterCmd so every caller stays
on the temp kubeconfig.
Signed-off-by: Tamal Saha <tamal@appscode.com>
@tamalsaha tamalsaha merged commit 563a0dd into main May 15, 2026
11 of 14 checks passed
@tamalsaha tamalsaha deleted the add-agents-md branch May 15, 2026 13:36
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.