From ad215f284bb2a5adbff520936f25c48b4b6a2f26 Mon Sep 17 00:00:00 2001
From: unkin-agent <unkin-agent@unkin.net>
Date: Sat, 24 Oct 2026 16:35:11 +1100
Subject: [PATCH 1/2] Add artifactapi_remote_vcs resource

---
 docs/resources/remote_vcs.md                  | 30 +++++++++++++++++++
 .../resources/artifactapi_remote_vcs/main.tf  | 26 ++++++++++++++++
 internal/provider/resource_remote_vcs.go      |  3 ++
 3 files changed, 59 insertions(+)
 create mode 100644 docs/resources/remote_vcs.md
 create mode 100644 examples/resources/artifactapi_remote_vcs/main.tf
 create mode 100644 internal/provider/resource_remote_vcs.go

diff --git a/docs/resources/remote_vcs.md b/docs/resources/remote_vcs.md
new file mode 100644
index 0000000..c041d6f
--- /dev/null
+++ b/docs/resources/remote_vcs.md
@@ -0,0 +1,30 @@
+# `artifactapi_remote_vcs`
+
+Per-type remote resources manage upstream repository proxies. Each type applies its own mutability classification rules automatically (e.g., Docker classifies tag manifests as mutable and blobs as immutable; Helm classifies `index.yaml` as mutable).
+
+## Common Attributes
+
+| Attribute            | Required | Default | Description                                                       |
+|----------------------|----------|---------|-------------------------------------------------------------------|
+| `name`               | Yes      |         | Unique name (forces replacement on change)                        |
+| `base_url`           | Yes      |         | Upstream repository URL                                           |
+| `description`        | No       | `""`    | Human-readable description                                        |
+| `username`           | No       | `""`    | Upstream auth username (sensitive)                                 |
+| `password`           | No       | `""`    | Upstream auth password (sensitive)                                 |
+| `immutable_ttl`      | No       | `0`     | TTL in seconds for immutable artifacts (0 = cache forever)        |
+| `mutable_ttl`        | No       | `3600`  | TTL in seconds for mutable artifacts                              |
+| `check_mutable`      | No       | `true`  | Enable conditional revalidation for mutable artifacts             |
+| `patterns`           | No       |         | Allowlist of path patterns to proxy (empty = all)                 |
+| `blocklist`          | No       |         | Paths to always deny (checked before patterns)                    |
+| `mutable_patterns`   | No       |         | Override: treat matching paths as mutable                         |
+| `immutable_patterns` | No       |         | Override: treat matching paths as immutable                       |
+| `quarantine_enabled` | No       | `false` | Enable quarantine for new artifacts                               |
+| `quarantine_days`    | No       | `3`     | Days to quarantine new artifacts                                  |
+| `stale_on_error`     | No       | `true`  | Serve stale cache when upstream is unreachable                    |
+| `upstream_dial_timeout` | No    | `0`     | Upstream TCP connect timeout in seconds (0 = server default)      |
+| `upstream_tls_timeout` | No     | `0`     | Upstream TLS handshake timeout in seconds (0 = server default)    |
+| `upstream_response_header_timeout` | No | `0` | Upstream response-header timeout in seconds (0 = server default) |
+
+## Example
+
+See `examples/resources/artifactapi_remote_vcs/main.tf`.
diff --git a/examples/resources/artifactapi_remote_vcs/main.tf b/examples/resources/artifactapi_remote_vcs/main.tf
new file mode 100644
index 0000000..565db88
--- /dev/null
+++ b/examples/resources/artifactapi_remote_vcs/main.tf
@@ -0,0 +1,26 @@
+terraform {
+  required_providers {
+    artifactapi = {
+      source  = "artifactapi.example.com/terraform-unkin/artifactapi"
+      version = "0.0.1"
+    }
+  }
+}
+
+provider "artifactapi" {
+  endpoint = "https://artifactapi.example.com"
+}
+
+# VCS remote caches GitHub/Gitea source archives and release assets.
+# Tag, commit and release paths are immutable; branch archives redirect to
+# the archive of the branch's current commit, re-resolved after mutable_ttl.
+resource "artifactapi_remote_vcs" "github" {
+  name        = "github-vcs"
+  base_url    = "https://github.com"
+  description = "GitHub source archives and release assets"
+
+  immutable_ttl = 0
+  mutable_ttl   = 600
+
+  patterns = ["^cli/cli/", "^psf/requests/"]
+}
diff --git a/internal/provider/resource_remote_vcs.go b/internal/provider/resource_remote_vcs.go
new file mode 100644
index 0000000..dbeedd4
--- /dev/null
+++ b/internal/provider/resource_remote_vcs.go
@@ -0,0 +1,3 @@
+package provider
+
+func init() { registerResource(newRemoteResource("vcs")) }
-- 
2.47.3


From 05e65c76667973223e98dbcb7faec0ece467e356 Mon Sep 17 00:00:00 2001
From: unkin-agent <unkin-agent@unkin.net>
Date: Sat, 24 Oct 2026 16:35:30 +1100
Subject: [PATCH 2/2] Describe vcs path handling in the remote_vcs docs

---
 docs/resources/remote_vcs.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/resources/remote_vcs.md b/docs/resources/remote_vcs.md
index c041d6f..cb4fca3 100644
--- a/docs/resources/remote_vcs.md
+++ b/docs/resources/remote_vcs.md
@@ -1,6 +1,6 @@
 # `artifactapi_remote_vcs`
 
-Per-type remote resources manage upstream repository proxies. Each type applies its own mutability classification rules automatically (e.g., Docker classifies tag manifests as mutable and blobs as immutable; Helm classifies `index.yaml` as mutable).
+Caches GitHub (`base_url = "https://github.com"`) or Gitea source archives and release assets. Tag, commit and release-download paths are immutable; branch archives redirect to the archive of the branch's current commit, re-resolved after `mutable_ttl`. Paths: [vcs remote](https://git.unkin.net/unkin/artifactapi/src/branch/master/docs/vcs/remote.md).
 
 ## Common Attributes
 
-- 
2.47.3