@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 +10 -10
- package/docs/development.md +24 -0
- package/docs/gateway.md +24 -4
- package/examples/gitvend.yaml +0 -1
- package/package.json +1 -1
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,
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
60
|
-
- [Repository creation controls](https://github.com/colony-2/gitvend/blob/v0.0.
|
|
61
|
-
- [JobDB plugin setup and issuer configuration](https://github.com/colony-2/gitvend/blob/v0.0.
|
|
62
|
-
- [Permission syntax](https://github.com/colony-2/gitvend/blob/v0.0.
|
|
63
|
-
- [Docker Compose deployment](https://github.com/colony-2/gitvend/blob/v0.0.
|
|
64
|
-
- [Developer guide: source builds, tests, and releases](https://github.com/colony-2/gitvend/blob/v0.0.
|
|
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)
|
package/docs/development.md
CHANGED
|
@@ -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
|
|
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
|
-
|
|
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.
|
|
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
|
package/examples/gitvend.yaml
CHANGED
package/package.json
CHANGED