@colony2/gitvend 0.0.4 → 0.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -10,13 +10,13 @@ The gateway sits between agents and GitHub. It holds your upstream GitHub tokens
10
10
  checks each agent's signed permissions, and forwards authorized Git requests.
11
11
  You can configure different upstream tokens for different organizations, deny
12
12
  writes to protected branches, and control whether new repositories are created
13
- publicly or privately with issues, projects, wiki, and pull requests enabled.
13
+ publicly or privately with issues, projects, and wiki enabled.
14
14
 
15
15
  The gateway supports GitHub and GitHub Enterprise-compatible endpoints. It needs
16
16
  no database or GitHub App. Agents connect over HTTPS; GitHub's own access and
17
17
  branch rules continue to apply.
18
18
 
19
- [Set up and use the gateway →](https://github.com/colony-2/gitvend/blob/v0.0.4/docs/gateway.md)
19
+ [Set up and use the gateway →](https://github.com/colony-2/gitvend/blob/v0.0.6/docs/gateway.md)
20
20
 
21
21
  ## JobDB plugin
22
22
 
@@ -29,7 +29,7 @@ The plugin keeps its signing key on the JobDB host, and the gateway verifies the
29
29
  resulting tokens with the matching public key. Workers receive neither the
30
30
  signing key nor the upstream GitHub token.
31
31
 
32
- [Set up the JobDB plugin →](https://github.com/colony-2/gitvend/blob/v0.0.4/docs/jobdb-secret-provider.md)
32
+ [Set up the JobDB plugin →](https://github.com/colony-2/gitvend/blob/v0.0.6/docs/jobdb-secret-provider.md)
33
33
 
34
34
  ## Install
35
35
 
@@ -52,13 +52,13 @@ that includes `jobdb-gitvend-secret-provider` when using the plugin; older packa
52
52
  may contain only `gitvend`.
53
53
 
54
54
  For a container deployment, use the published image with the
55
- [Docker Compose guide](https://github.com/colony-2/gitvend/blob/v0.0.4/docs/docker-compose.md).
55
+ [Docker Compose guide](https://github.com/colony-2/gitvend/blob/v0.0.6/docs/docker-compose.md).
56
56
 
57
57
  ## Guides
58
58
 
59
- - [Gateway setup, Git usage, and operations](https://github.com/colony-2/gitvend/blob/v0.0.4/docs/gateway.md)
60
- - [Repository creation controls](https://github.com/colony-2/gitvend/blob/v0.0.4/docs/gateway.md#repository-creation-defaults)
61
- - [JobDB plugin setup and issuer configuration](https://github.com/colony-2/gitvend/blob/v0.0.4/docs/jobdb-secret-provider.md)
62
- - [Permission syntax](https://github.com/colony-2/gitvend/blob/v0.0.4/docs/permission-syntax.md)
63
- - [Docker Compose deployment](https://github.com/colony-2/gitvend/blob/v0.0.4/docs/docker-compose.md)
64
- - [Developer guide: source builds, tests, and releases](https://github.com/colony-2/gitvend/blob/v0.0.4/docs/development.md)
59
+ - [Gateway setup, Git usage, and operations](https://github.com/colony-2/gitvend/blob/v0.0.6/docs/gateway.md)
60
+ - [Repository creation controls](https://github.com/colony-2/gitvend/blob/v0.0.6/docs/gateway.md#repository-creation-defaults)
61
+ - [JobDB plugin setup and issuer configuration](https://github.com/colony-2/gitvend/blob/v0.0.6/docs/jobdb-secret-provider.md)
62
+ - [Permission syntax](https://github.com/colony-2/gitvend/blob/v0.0.6/docs/permission-syntax.md)
63
+ - [Docker Compose deployment](https://github.com/colony-2/gitvend/blob/v0.0.6/docs/docker-compose.md)
64
+ - [Developer guide: source builds, tests, and releases](https://github.com/colony-2/gitvend/blob/v0.0.6/docs/development.md)
@@ -83,6 +83,30 @@ Git features. See the [design](git-proxy-design.md) for requirements and tradeof
83
83
  [c2r](https://github.com/colony-2/c2r) informed the provisioning approach; Gitvend
84
84
  uses a direct GitHub adapter and copies no c2r source.
85
85
 
86
+ ### Git interoperability regression coverage
87
+
88
+ Linux and macOS CI run the full race suite and vet, including actual Git clients
89
+ and `git-http-backend`. The test jobs print the Git version they exercised.
90
+ The local backend alone does not reproduce every GitHub response format; tests
91
+ also inject the upload-pack service preamble observed from GitHub.
92
+
93
+ | Behavior | Regression coverage |
94
+ | --- | --- |
95
+ | Upload-pack discovery | Bare v2 and service-header-prefixed v2; real discovery, clone and fetch; malformed headers and downgrades rejected. |
96
+ | Push transport | Twelve real-Git scenarios: full/shallow checkout × new/existing branch × small/default-buffer-overflow/configured-buffer-overflow pack. Each attempts a denied push before an allowed one and verifies the remote ref. |
97
+ | First push and upstream refusal | A large first push provisions and populates a new repository; shallow pushes to an upstream that refuses missing history remain rejected and do not create refs. |
98
+ | HTTP authentication probes | Flush-only requests with fixed-length, chunked and gzip bodies; JWT and write authorization required; no upstream calls or repository creation. |
99
+ | Shallow push metadata | Preserve declarations before ref commands and leave pack bytes unread; reject malformed or misplaced declarations and enforce command byte/ref limits. |
100
+ | Malformed probes | Reject truncation, read errors, trailing commands, additional flushes and pack data. |
101
+
102
+ When a production compatibility failure is reported, first add a test that
103
+ reproduces its wire format or real-client behavior and fails on the existing code.
104
+ For parser changes, include both accepted traffic and malformed/unauthorized
105
+ variants, then seed the wire fuzzer with the new valid format. Statement coverage
106
+ alone cannot establish protocol compatibility. These tests use local upstreams;
107
+ they do not replace a deployment smoke test against GitHub with the operator's
108
+ actual credentials and repository settings.
109
+
86
110
  ## Release automation
87
111
 
88
112
  The [release workflow](../.github/workflows/release.yaml) follows [c2j's release pattern](https://github.com/colony-2/c2j/blob/main/.github/workflows/release.yaml). Successful pushes to `main` in the `colony-2` organization run the test suite, automatically bump and push a version tag (patch by default), build both executables for four platforms, and publish GitHub release archives and checksums. It then publishes `@colony2/gitvend` to npm with `gitvend` and `jobdb-gitvend-secret-provider` commands after installing and smoke-testing the installed commands against the published assets. It also publishes Linux amd64/arm64 container images to `ghcr.io/colony-2/gitvend` with the release tag and `latest`, using `GITHUB_TOKEN` with package-write permission.
package/docs/gateway.md CHANGED
@@ -302,7 +302,6 @@ creation_defaults:
302
302
  has_issues: false
303
303
  has_projects: false
304
304
  has_wiki: false
305
- has_pull_requests: false
306
305
  ```
307
306
 
308
307
  Supported settings use GitHub's field names:
@@ -310,7 +309,7 @@ Supported settings use GitHub's field names:
310
309
  | Settings | Values and behavior |
311
310
  | --- | --- |
312
311
  | `visibility` | `private` (default) or `public`. |
313
- | `has_issues`, `has_projects`, `has_wiki`, `has_pull_requests` | Optional booleans. An explicit `false` disables the feature; omission leaves GitHub's default. |
312
+ | `has_issues`, `has_projects`, `has_wiki` | Optional booleans. An explicit `false` disables the feature; omission leaves GitHub's default. |
314
313
  | `description`, `homepage` | Optional strings applied to newly created repositories. |
315
314
  | `pull_request_creation_policy` | Optional `all` or `collaborators_only`. |
316
315
  | `allow_squash_merge`, `allow_merge_commit`, `allow_rebase_merge` | Optional booleans. At least one merge method must remain available. |
@@ -322,7 +321,7 @@ are not accepted. GitHub organization policies and upstream permissions can
322
321
  reject settings; these errors fail provisioning rather than silently changing
323
322
  requested options. See the [GitHub creation API](https://docs.github.com/en/rest/repos/repos#create-an-organization-repository).
324
323
 
325
- Pull request availability and its creation policy use GitHub's
324
+ When configured, `pull_request_creation_policy` uses GitHub's
326
325
  [repository update API](https://docs.github.com/en/rest/repos/repos#update-a-repository)
327
326
  after creation or successful name reconciliation, before forwarding discovery
328
327
  and the first push. The API credential must authorize these repository updates
@@ -333,6 +332,19 @@ enforcement. An existing repository found by the initial lookup is left unchange
333
332
  including on a later retry or after a gateway restart. Gitvend does not store
334
333
  pending provisioning state or roll back repository creation.
335
334
 
335
+ The error and audit reason include the failed settings step: an upstream HTTP
336
+ status, an omitted response field, or a field that differs from the requested
337
+ value. Raw upstream error bodies and credentials are not included. For a rejected
338
+ update, check the API credential's access to the new repository and its permission
339
+ to change settings (fine-grained GitHub tokens require **Administration: write**).
340
+ For omitted or mismatched fields, check the repository's actual pull request
341
+ settings and the upstream API's support for those fields. This failure occurs
342
+ before Gitvend forwards discovery or the push; it does not publish the commit.
343
+ Complete the settings on the existing repository before retrying the push:
344
+ retrying alone does not repeat the settings update. Omitting
345
+ `pull_request_creation_policy` skips this update for future repositories and
346
+ accepts the forge's default policy.
347
+
336
348
  Defaults belong to the upstream provider, not to a JWT signing key or JobDB
337
349
  tenant. Different providers can use different tokens and defaults for distinct
338
350
  organizations/users. Provider selection uses the URL alias; overlapping owners
@@ -355,6 +367,12 @@ jq -c 'select(.audit.operation == "git-receive-pack") | .audit' audit.jsonl
355
367
 
356
368
  Push audit distinguishes `accepted`, `rejected`, `partial` and `unknown`; HTTP 200 alone is not success. Creation outcomes are `created`, `reconciled`, `configuration_failed`, `rejected` or `unknown` and do not claim that a subsequent push succeeded. A crash can leave an admission with no final record. Log delivery is best-effort, with retention and durability handled by your logging infrastructure. Inspect the remote refs before retrying an interrupted push; gitvend never retries a push automatically.
357
369
 
370
+ Large pushes can begin with a flush-only HTTP authentication probe. These are
371
+ logged as `git-receive-pack-probe`; an accepted probe means the gateway accepted
372
+ the credential and found writable refs. It does not verify upstream permissions,
373
+ create a repository, or update any refs. The subsequent push is authorized and
374
+ audited separately as `git-receive-pack`.
375
+
358
376
  ### Multiple instances
359
377
 
360
378
  Run any number of instances behind the same HTTPS endpoint with matching configuration, trusted keys and credentials. No shared disk, database, distributed lock or sticky session is required. Configuration/key rotations must reach each instance; a reload on one instance does not update others. `max_concurrent` and request limits apply per instance. If you need fleet-wide rate limits or creation budgets, enforce them outside gitvend. A metrics export endpoint is not implemented.
@@ -430,7 +448,9 @@ legacy single-dash long flags. For credential helpers, Git appends the final ope
430
448
 
431
449
  ## Compatibility
432
450
 
433
- Supported object format is SHA-1. SSH, Git LFS, Git protocol v0/v1 fetch, signed push certificates, push options, named shallow exclusions, ref-in-want, offloaded pack/bundle URLs and provider-managed ref namespaces are rejected or not advertised. Branch writes can include workflow files; CI execution and secrets remain governed by the forge's configuration. GitHub branch rules continue to apply to the shared upstream identity.
451
+ Supported object format is SHA-1. Pushes from shallow clones and streamed large
452
+ pushes are supported; the upstream still validates object connectivity and can
453
+ reject a push with missing history. SSH, Git LFS, Git protocol v0/v1 fetch, signed push certificates, push options, named shallow exclusions, ref-in-want, offloaded pack/bundle URLs and provider-managed ref namespaces are rejected or not advertised. Branch writes can include workflow files; CI execution and secrets remain governed by the forge's configuration. GitHub branch rules continue to apply to the shared upstream identity.
434
454
 
435
455
  Use a disposable repository to confirm your upstream token, organization creation
436
456
  policy, workflow permissions and GitHub Enterprise version before rolling out to
@@ -26,6 +26,5 @@ providers:
26
26
  has_issues: false
27
27
  has_projects: false
28
28
  has_wiki: false
29
- has_pull_requests: false
30
29
  denies:
31
30
  - '!github.com/fooorg/*#(main|master):wd'
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@colony2/gitvend",
3
- "version": "0.0.4",
3
+ "version": "0.0.6",
4
4
  "description": "Git HTTPS gateway with signed repository and branch permissions",
5
5
  "license": "UNLICENSED",
6
6
  "homepage": "https://github.com/colony-2/gitvend",