Skip to content

fix(#8367): sign GitHub scaffold commits with createCommitOnBranch - #8368

Merged
waynesun09 merged 1 commit into
fullsend-ai:mainfrom
gwenneg:fix/signed-scaffold-commits
Oct 17, 2026
Merged

waynesun09 merged 1 commit into
fullsend-ai:mainfrom
gwenneg:fix/signed-scaffold-commits

Conversation

@gwenneg

@gwenneg gwenneg commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

Summary

fullsend repos install created GitHub scaffold commits through the Git Data REST API, which GitHub signs only for App installation tokens. With the credentials an operator uses (gh auth token, fine-grained or classic PAT) the commit was unsigned, so a ruleset with required_signatures rejected the ref update — and the CLI reported it as "scaffold branch is protected; configure branch protection". Organization-level rulesets cover every branch, so PR delivery failed as well as --direct.

Closes #8367.

  • GitHub client: a commit made only of regular inline files (mode 100644, no LocalPath), and every deletion-only commit, is now created with the GraphQL createCommitOnBranch mutation. GitHub signs those for any credential (author = authenticated account, committer = GitHub, as in the web UI). expectedHeadOid gives compare-and-swap; STALE_DATA maps to forge.ErrNonFastForward (existing retry), ruleset violations and classic BRANCH_PROTECTION_RULE_VIOLATION errors map to forge.ErrBranchProtected (existing --direct → PR fallback), NOT_FOUND/FORBIDDEN to their sentinels.
  • Vendored installs unchanged: any file with a LocalPath or a non-100644 mode keeps the streamed Git Data REST path (unsigned with user tokens). On the signed path a mode-only difference on an existing file counts as unchanged, since the mutation cannot change it and identical content would otherwise produce an empty commit on every converge.
  • Error text: new forge.ErrSignedCommitsRequired, wrapped alongside ErrBranchProtected when GitHub says "Commits must have verified signatures" (REST or GraphQL), so layers names the rule instead of advising on branch protection. GraphQL RATE_LIMITED (reported with HTTP 200) surfaces as a 429 APIError so IsRateLimitError/forge.IsTransient keep working; a SAML-enforcement FORBIDDEN is a credential error, not a protection rule. Classic protection on the REST ref update returns only the failed check ("Changes must be made through a pull request.", "Cannot change this locked branch", "Commits must have verified signatures."), which the classifier did not recognise; the shared matcher now knows those texts.
  • No feature flag. The repo gates only opt-in side effects behind toggles (FULLSEND_GITLAB_PIPELINE_VAR_RESTRICTION) and removed an operator flag in ADR 0078; a "legacy commits" escape hatch here would be a path e2e never exercises, re-creating the blind spot below. The REST path stays for the cases the mutation cannot serve.
  • Docs/ADR: ADR 0140 records the decision, alternatives and trade-offs; docs/cli/repos.md gains a "Signed commits" section next to DCO sign-off (they are independent); repo-management, architecture and the threat model's commit-signing passage are annotated; forge.Client interface docs describe the per-forge signing and mode semantics.

Trade-offs recorded in ADR 0140

  • The signature is GitHub's web-flow key attesting that GitHub created the commit for the authenticated account — not the operator's own key; policies that verify a specific key or a Sigstore identity are not met.
  • The executable bit is no longer a managed property of GitHub installs (the standard install writes only regular files; the vendored binary is chmod +x-ed by the installer action).
  • Vendored installs (vendor: true) cannot target signature-requiring repositories.
  • "Signed if supported" is silently false on GHES without web commit signing enabled.
  • Behaviour tests run as App installations, for which REST commits were already signed, and their PR runs install in vendored mode, which keeps the REST path, so they cannot catch a regression to REST for user tokens; unit tests pin the mutation for the regular-file case. A behaviour test with a user PAT against a ruleset-protected repository is a follow-up.

Verification

  • Live probes on a throwaway branch of a personal fork with a temporary required_signatures ruleset (details in repos install: GitHub scaffold commits are unsigned with user tokens and rejected by rulesets requiring verified signatures #8367): user-token REST commit unsigned and rejected with "Commits must have verified signatures"; GraphQL commit verified: valid and accepted; STALE_DATA, NOT_FOUND and FORBIDDEN responses captured and mapped as above.
  • Live probes on the same fork with classic branch protection (require a pull request, a required status check, lock branch, require signed commits; each alone and combined, "include administrators" on): the mutation answers BRANCH_PROTECTION_RULE_VIOLATION with protected branch '<name>' check failed: followed by the failed checks; the REST ref update answers 422 with the failed check alone. Classic "Require signed commits" accepts the mutation's commit (verified: valid) and rejects the unsigned REST commit. The captured messages are the test fixtures.
  • Rebased onto main (280 commits): one conflict in repo-management.md resolved by keeping both sides; the operator-facing text now says "vendored install" / vendor: true, since Make repos install manifest-driven and remove persistent-setting flags #8219 made repos.yaml the only source of the vendoring setting.
  • go build ./..., go vet, make go-test on the rebased head; patch coverage on changed code: new functions 100%, commitFilesTo 88%, DeleteFiles 84%, layers branches covered.
  • ADR lint scripts (lint-adr-status, lint-adr-numbers), lint-docs-links, whitespace/EOF checks run directly (pre-commit is not installed on the authoring machine; CI runs the full hook set).
  • Not run: behaviour/e2e suites (see trade-offs).

🤖 Generated with Claude Code

@github-actions

github-actions Bot commented Oct 12, 2026 •

Copy link
Copy Markdown

E2E tests are running

Authorization passed for this commit. See the E2E Tests workflow for results.

@github-actions

github-actions Bot commented Oct 12, 2026 •

Copy link
Copy Markdown

Site preview

Preview: https://717ea206-site.fullsend-ai.workers.dev

Commit: 3918a7c6493bc02982027df6373acd0f071274d8

@codecov

codecov Bot commented Oct 12, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 96.95817% with 8 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
internal/forge/github/commit_graphql.go 95.23% 4 Missing and 4 partials ⚠️

📢 Thoughts on this report? Let us know!

@gwenneg
gwenneg marked this pull request as ready for review October 13, 2026 09:47
@gwenneg
gwenneg requested a review from a team October 13, 2026 09:47
@qodo-code-review

Copy link
Copy Markdown

PR Summary by Qodo

Sign GitHub scaffold commits made with operator credentials

🐞 Bug fix ✨ Enhancement 🧪 Tests 📝 Documentation 🕐 40+ Minutes

Grey Divider

AI Description

• Use GitHub-signed commits for regular scaffold files and deletions, allowing signature-required
 installs.
• Retain streamed Git Data commits for vendored binaries and non-regular file modes.
• Classify signature-rule failures explicitly and document signing behavior and limitations.
Diagram

graph TD
  L["Scaffold delivery"] --> F["Forge client"] --> D["Tree diff"] --> E{"GraphQL eligible?"} -->|Yes| G["Signed GraphQL"] --> H["Rule handling"]
  E -->|No| R["Git Data REST"] --> H
Loading
High-Level Assessment

The following are alternative approaches to this PR:

1. Sign REST commits with an operator PGP key
  • ➕ Would attest to the operator's own signing key.
  • ➕ Could retain REST support for file modes.
  • ➖ Requires accessible, registered PGP key material and exact commit serialization.
  • ➖ Does not accommodate operators who use SSH signing keys.
2. Make all commits with a GitHub App token
  • ➕ Preserves the REST path for streamed files and executable modes.
  • ➕ GitHub signs REST commits made with installation tokens.
  • ➖ Requires an installed App and token-minting dependency for human-run commands.
  • ➖ Makes the App bot, rather than the operator, the commit author.

Recommendation: Keep the PR's selective GraphQL approach: it signs ordinary human-run scaffold commits without new credentials or local key management while preserving REST capabilities for vendoring. The remaining unsigned vendor case and GitHub Enterprise Server signing dependency are explicit limitations.

Files changed (13) +1316 / -162

Enhancement (1) +31 / -4
forge.goExpose signature-rule failures in the forge contract +31/-4

Expose signature-rule failures in the forge contract

• Adds ErrSignedCommitsRequired and its predicate. Documents per-forge signing, deletion, and mode behavior on the commit interface.

internal/forge/forge.go

Bug fix (3) +367 / -132
commit_graphql.goImplement signed GraphQL branch commits +211/-0

Implement signed GraphQL branch commits

• Builds createCommitOnBranch requests for inline additions and deletions using an expected head OID. Adds GitHub Enterprise Server endpoint resolution and classifies GraphQL rule, race, credential, and rate-limit errors.

internal/forge/github/commit_graphql.go

github.goRoute eligible commits through the signed mutation +134/-131

Route eligible commits through the signed mutation

• Selects GraphQL after the existing tree diff, retains REST for changes needing streaming or special modes, and moves deletion-only commits to GraphQL. Shares commit retries, identifies signature-rule rejections on REST, and centralizes GraphQL endpoint selection.

internal/forge/github/github.go

commit.goReport signature requirements during scaffold delivery +22/-1

Report signature requirements during scaffold delivery

• Replaces generic branch-protection advice with a signing-specific hint for rejected PR-branch commits. Preserves direct-to-PR fallback and gives it a signing-specific warning.

internal/layers/commit.go

Tests (4) +785 / -26
commit_graphql_test.goCover signed commit selection and GraphQL failures +664/-0

Cover signed commit selection and GraphQL failures

• Tests mutation payloads, deletion filtering, idempotence, mode and vendor routing, retries, error classification, and GitHub Enterprise Server endpoints. Also checks REST signature-rule classification.

internal/forge/github/commit_graphql_test.go

github_test.goAdapt GitHub commit tests to both paths +51/-26

Adapt GitHub commit tests to both paths

• Updates deletion and regular-file fixtures for GraphQL commits while pinning existing Git Data race and protection tests to non-regular modes.

internal/forge/github/github_test.go

signed_commits_test.goTest the signature-rule sentinel +18/-0

Test the signature-rule sentinel

• Verifies that a signature rejection is identifiable independently while remaining a branch-protection error.

internal/forge/signed_commits_test.go

commit_test.goTest signing-specific delivery messages and fallback +52/-0

Test signing-specific delivery messages and fallback

• Covers signature rejection on scaffold and feature branches and confirms direct delivery still falls back to a PR.

internal/layers/commit_test.go

Documentation (5) +133 / -0
0140-sign-github-scaffold-commits-via-createcommitonbranch.mdRecord the server-side signing decision +109/-0

Record the server-side signing decision

• Documents the signature-rules failure, considered alternatives, GraphQL eligibility, and consequences for vendoring, file modes, identity, and GitHub Enterprise Server.

docs/ADRs/0140-sign-github-scaffold-commits-via-createcommitonbranch.md

architecture.mdDescribe GitHub scaffold commit routing +6/-0

Describe GitHub scaffold commit routing

• Adds the signed GraphQL path and the streamed Git Data exception to the architecture overview.

docs/architecture.md

repos.mdExplain signed commits to CLI users +8/-0

Explain signed commits to CLI users

• Distinguishes cryptographic signatures from DCO sign-off and documents GitHub and GitLab behavior, token support, vendoring limitations, and file-mode semantics.

docs/cli/repos.md

repo-management.mdAdd scaffold-signing guidance +8/-0

Add scaffold-signing guidance

• Explains forge-side signing alongside sign-off instructions and links to the detailed CLI guidance.

docs/guides/getting-started/repo-management.md

security-threat-model.mdClarify install-time signature provenance +2/-0

Clarify install-time signature provenance

• Separates GitHub-signed operator scaffold commits from agent-generated commits and limits what the GitHub signature attests.

docs/problems/security-threat-model.md

@qodo-code-review

qodo-code-review Bot commented Oct 13, 2026 •

Copy link
Copy Markdown

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

Grey Divider


Action required

1. One ADR combines several decisions ✗ Dismissed
Description
ADR 0140 places the GitHub mutation choice, credential and signer semantics, concurrency behavior,
error mapping, and caller messaging in one Decision section. These are distinct implementation and
policy decisions that should be split into separate ADRs or separately identified decisions so later
changes do not obscure which architectural choice is being revised.
Code

docs/ADRs/0140-sign-github-scaffold-commits-via-createcommitonbranch.md[R64-67]

+The GitHub forge client creates a commit with the GraphQL
+`createCommitOnBranch` mutation whenever every file in it is a regular
+inline file (mode `100644`, no `LocalPath`), and for every deletion-only
+commit. GitHub signs those commits for any credential type; the author is
Evidence
The new ADR's Decision section makes multiple independent choices rather than recording one
decision: it selects the GraphQL mutation and signing behavior, defines concurrency handling, maps
errors, and changes caller messaging.

docs/ADRs/0140-sign-github-scaffold-commits-via-createcommitonbranch.md[62-76]
Skill: writing-adrs

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
ADR 0140 records several distinct decisions in one Decision section, including the commit mechanism, signing identity, and file eligibility rules.

## Fix Focus Areas
- docs/ADRs/0140-sign-github-scaffold-commits-via-createcommitonbranch.md[62-87]

## Recommended Fix
Restructure the Decision section into separately labeled decisions, or create separate ADRs where the choices have independent rationale and consequences. Preserve the documented trade-offs and references while making each decision independently identifiable.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


2. User-token signing remains untested ✗ Dismissed
Description
The added tests exercise mocked GraphQL mutations but do not authenticate with a user token, enforce
a required-signatures rule, or verify that the resulting commit is marked Verified. The regression
suite therefore cannot detect a user-token path that still produces an unsigned commit, which is the
failure this change is intended to prevent for install, upgrade, and uninstall delivery.
Code

internal/forge/github/commit_graphql_test.go[R120-149]

+func TestCommitFiles_GraphQL_RegularFilesTakeSignedPath(t *testing.T) {
+	const message = "chore: initialize fullsend per-repo installation [skip ci]\n\nSigned-off-by: Install User <install@example.com>"
+	var mutations int
+	srv, calls := graphqlCommitServer(t, "main", nil, func(w http.ResponseWriter, input commitMutationInput) {
+		mutations++
+		assert.Equal(t, "org/repo", input.Branch.RepositoryNameWithOwner)
+		assert.Equal(t, "main", input.Branch.BranchName)
+		assert.Equal(t, "abc123", input.ExpectedHeadOid)
+		assert.Equal(t, "chore: initialize fullsend per-repo installation [skip ci]", input.Message.Headline)
+		if assert.NotNil(t, input.Message.Body) {
+			assert.Equal(t, "Signed-off-by: Install User <install@example.com>", *input.Message.Body)
+		}
+		if assert.Len(t, input.FileChanges.Additions, 2) {
+			assert.Equal(t, ".fullsend/config.yaml", input.FileChanges.Additions[0]["path"])
+			decoded, err := base64.StdEncoding.DecodeString(input.FileChanges.Additions[0]["contents"])
+			assert.NoError(t, err)
+			assert.Equal(t, "version: \"1\"\n", string(decoded))
+		}
+		assert.Empty(t, input.FileChanges.Deletions)
+		graphqlCommitOK(w, "newcommit")
+	})
+
+	committed, err := newTestClient(t, srv).CommitFiles(context.Background(), "org", "repo", message, []forge.TreeFile{
+		{Path: ".fullsend/config.yaml", Content: []byte("version: \"1\"\n"), Mode: "100644"},
+		{Path: ".github/workflows/fullsend.yaml", Content: []byte("name: fullsend\n"), Mode: "100644"},
+	})
+	require.NoError(t, err)
+	assert.True(t, committed)
+	assert.Equal(t, 1, mutations)
+	assertNoGitDataWrites(t, *calls)
Evidence
The new regular-file test uses a generic mocked client and only asserts the mutation payload and
request path; it does not model a user-token credential, a required-signatures ruleset, or Verified
commit state. The deletion tests likewise only classify mocked GraphQL errors, so the required
user-token signature-enforcement regression remains absent.

Cover user-token signature enforcement in regression tests
internal/forge/github/commit_graphql_test.go[120-149]
internal/forge/github/commit_graphql_test.go[527-556]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The regression tests only verify that a mocked GraphQL mutation is called; they do not exercise a user-token credential under required-signatures enforcement or verify a Verified commit. Add coverage for the credential type and enforcement scenario that exposed the original issue.

## Fix Focus Areas
- internal/forge/github/commit_graphql_test.go[120-149]
- internal/forge/github/commit_graphql_test.go[346-356]
- internal/forge/github/commit_graphql_test.go[527-556]

## Recommended Fix
Add a regression test that uses a PAT or `gh auth`-style user token, delivers install or uninstall scaffold files through the signed path, simulates or verifies the repository required-signatures rule, and asserts that delivery succeeds with a Verified commit. Include the same enforcement coverage for the relevant upgrade and uninstall flows, rather than relying only on mocked mutation responses.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


3. Scaffold files are stored as base64 ✗ Dismissed
Description
createCommitOnBranch base64-encodes each TreeFile before assigning it to the GraphQL contents
field. GitHub expects the file contents directly, so regular scaffold files are committed as encoded
text instead of their original contents and the resulting install or upgrade writes incorrect files.
Code

internal/forge/github/commit_graphql.go[R104-107]

+		adds = append(adds, map[string]string{
+			"path":     f.Path,
+			"contents": base64.StdEncoding.EncodeToString(content),
+		})
Evidence
The signed implementation places base64.StdEncoding.EncodeToString(content) in the GraphQL
contents field, while the added tests explicitly decode that field before comparing it with the
expected bytes, so the tests mask the incorrect wire representation. This violates the required
preservation of scaffold write semantics.

Preserve scaffold file modes and write semantics
internal/forge/github/commit_graphql.go[98-107]
internal/forge/github/commit_graphql_test.go[132-136]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The signed GraphQL path base64-encodes file bytes before sending them as `FileAddition.contents`, but GitHub expects the original file contents. This causes scaffold files to be committed as base64 text instead of their intended contents.

## Fix Focus Areas
- internal/forge/github/commit_graphql.go[98-107]
- internal/forge/github/commit_graphql_test.go[120-200]

## Recommended Fix
Send the file bytes as the contents string without base64 encoding, using the representation required by `createCommitOnBranch`. Update the mutation tests to assert the raw wire contents so they catch an encoding regression.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools



Remediation recommended

4. Some protected-branch rejections no longer trigger the PR fallback ✓ Resolved
Description
isBranchProtectionMessage now matches only "protected branch" where it used to match any
"protected", and isBranchProtectionError (the REST ref-update classifier) now calls it. A 422
from PATCH /git/refs that says e.g. "Cannot update this protected ref." is no longer wrapped as
forge.ErrBranchProtected, so on the Git Data path (--vendor) commitScaffoldDirect no longer
falls back to a PR and the install fails with a generic commit error.
Code

internal/forge/github/github.go[R1709-1714]

+func isBranchProtectionMessage(message string) bool {
+	msg := strings.ToLower(message)
+	return strings.Contains(msg, "protected branch") ||
		strings.Contains(msg, "required status") ||
		strings.Contains(msg, "required review") ||
		strings.Contains(msg, "rule violation")
Evidence
The SAML exclusion is only needed for GraphQL FORBIDDEN errors, but the narrower match is shared
with the REST classifier at line 1588. That classifier only runs on 422 responses from ref updates,
and the comment on APIError.Unwrap says the word "protected" in a ref-update 422 is what signals
branch protection. Narrowing the match there drops any protection wording that is not literally
"protected branch", and the existing tests only cover "Protected branch …" strings.

internal/forge/github/github.go[219-226]
internal/forge/github/github.go[1584-1597]
internal/forge/github/github_test.go[1755-1834]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The change from "protected" to "protected branch" in `isBranchProtectionMessage` also narrows the REST ref-update classifier `isBranchProtectionError`. As a result, 422 messages like "Cannot update this protected ref." are no longer mapped to ErrBranchProtected.

## Fix Focus Areas
- internal/forge/github/github.go[1691-1715]
- internal/forge/github/commit_graphql.go[169-177]

## Recommended Fix
Keep the broad `"protected"` match in `isBranchProtectionError`, which is already limited to 422 ref updates, for example `strings.Contains(lowerAPIErrorText(apiErr), "protected") || isBranchProtectionMessage(...)`. Apply the SAML-safe narrow match only in the GraphQL classifier, or exclude "saml enforcement" explicitly there. Add a test case for "Cannot update this protected ref."

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


5. Rate limits abort scaffold commits ✓ Resolved
Description
classifyCreateCommitErrors converts a GraphQL RATE_LIMITED response into a 429 error only after
the HTTP request has completed, but isRetriableCommitError does not recognize that error. When
GitHub returns a rate-limit error inside an HTTP 200 response, the transport retry is bypassed and
the commit fails immediately instead of being retried.
Code

internal/forge/github/commit_graphql.go[R192-193]

+	if e := first("RATE_LIMITED"); e != nil {
+		return fmt.Errorf("create commit on branch: %w", &APIError{StatusCode: http.StatusTooManyRequests, Message: e.Message})
Evidence
The mutation decodes GraphQL errors after c.post returns successfully and classifies
RATE_LIMITED as a 429 error. HTTP 200 does not enter the transport's status-based retry path; the
commit retry loop accepts only errors recognized by isRetriableCommitError, which checks
non-fast-forward and GraphQL NOT_FOUND but not rate limits.

internal/forge/github/commit_graphql.go[132-151]
internal/forge/github/commit_graphql.go[192-210]
internal/forge/github/github.go[1367-1372]
internal/forge/github/github.go[377-387]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
GraphQL `RATE_LIMITED` errors arrive in HTTP 200 responses, bypassing transport retries. The classifier marks them as 429 errors, but the commit retry loop does not retry them.

## Fix Focus Areas
- internal/forge/github/commit_graphql.go[192-210]
- internal/forge/github/github.go[1349-1372]

## Recommended Fix
Retry GraphQL rate-limit errors with an appropriate backoff, while preserving the existing stale-head and replica-lag retries. Add a test where a rate-limited mutation succeeds on a subsequent attempt.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


6. Core threat model names the product ✓ Resolved
Description
The new threat-model paragraph refers to the fullsend CLI and its install-time behavior directly
in a core document outside docs/problems/applied/. Readers now receive a product-specific workflow
in the generic problem document instead of a reusable problem statement or a link to an
organization-specific applied document.
Code

docs/problems/security-threat-model.md[534]

+Install-time scaffold commits that the `fullsend` CLI creates on an operator's behalf are a separate, decided case: on GitHub they are created through the `createCommitOnBranch` mutation so that GitHub signs them ([ADR 0140](../ADRs/0140-sign-github-scaffold-commits-via-createcommitonbranch.md)). That signature attests that GitHub created the commit for the authenticated account; it is not the operator's own key, and it says nothing about agent-generated commits, which still take a local `git push`.
Evidence
The changed line in a core problem document names the product-specific fullsend CLI and describes
its product workflow. The checklist requires organization-specific project or system identifiers to
be kept under docs/problems/applied/.

Rule 1062038: Separate generic and organization-specific problem documents
docs/problems/security-threat-model.md[534-534]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The core security threat model introduces the product-specific `fullsend` CLI and install workflow inline, rather than keeping organization-specific details under `docs/problems/applied/`.

## Fix Focus Areas
- docs/problems/security-threat-model.md[534-534]
- docs/problems/applied/[relevant organization document]

## Recommended Fix
Rewrite the core paragraph using generic language about install-time scaffold commits, and move any `fullsend`-specific workflow details to the appropriate document under `docs/problems/applied/<org-name>/`. Link to that applied document from the core problem file if the relationship is needed.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


View medium (2)
7. Setup guide leaves forge terms undefined ✓ Resolved
Description
The new guide paragraph uses createCommitOnBranch, the Git Data API, and Gitaly without linking
them to the glossary or defining them when first introduced. A platform administrator following the
procedure must infer the meaning and relevance of these implementation terms from the surrounding
claims.
Code

docs/guides/getting-started/repo-management.md[R540-546]

+Independently of the DCO trailer, scaffold commits are cryptographically
+signed by the forge: on GitHub through the `createCommitOnBranch` mutation
+(the commits show as **Verified** and pass rulesets that require signatures,
+whichever token type the install uses — except `--vendor` installs, whose
+binary goes through the unsigned Git Data API), on GitLab through Gitaly
+when the instance is configured for it. See
+[Signed commits](../../cli/repos.md#signed-commits).
Evidence
The changed guide text introduces multiple implementation-specific forge terms and abbreviations
without a glossary link or an inline definition at first use. This conflicts with the guide
terminology requirement.

docs/guides/getting-started/repo-management.md[540-546]
Skill: writing-user-docs

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The new repository-management guide introduces forge-specific terms such as `createCommitOnBranch`, Git Data API, and Gitaly without a glossary link or inline first-use definitions.

## Fix Focus Areas
- docs/guides/getting-started/repo-management.md[540-546]
- docs/glossary.md[relevant entries]

## Recommended Fix
Add glossary entries and link each term on first use, or replace the jargon with short inline definitions explaining that the mutation creates signed commits server-side, the Git Data API creates unsigned user-token commits for unsupported file modes, and Gitaly is GitLab's server-side Git service.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


8. Forge changes lack required e2e gate ✗ Dismissed
Description
The PR changes forge and layer code, but the repository's E2E workflow runs make behaviour-test
rather than the required make e2e-test job and the PR description does not state that the required
command passed. These changes can therefore merge without the checklist's required end-to-end
validation for critical forge and layer paths.
Code

internal/forge/github/commit_graphql.go[R73-84]

+func (c *LiveClient) commitFilesViaGraphQL(ctx context.Context, owner, repo, branch, headSHA, message string, changed []forge.TreeFile) error {
+	var additions []forge.TreeFile
+	var deletions []string
+	for _, f := range changed {
+		if f.Delete {
+			deletions = append(deletions, f.Path)
+		} else {
+			additions = append(additions, f)
+		}
+	}
+	_, err := c.createCommitOnBranch(ctx, owner, repo, branch, headSHA, message, additions, deletions)
+	return err
Evidence
The changed files are under internal/forge/ and internal/layers/, which activates the end-to-end
testing rule. The available E2E workflow invokes make behaviour-test, while neither the supplied
PR description nor the workflow provides evidence of a required make e2e-test job.

Rule 1062051: Run end-to-end tests for critical internal modules before merge
internal/forge/github/commit_graphql.go[73-84]
internal/layers/commit.go[345-350]
.github/workflows/e2e.yml[194-198]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Critical forge and layer code was changed without evidence of the required `make e2e-test` check.

## Fix Focus Areas
- internal/forge/github/commit_graphql.go[73-84]
- internal/layers/commit.go[345-350]
- .github/workflows/e2e.yml[194-198]

## Recommended Fix
Add or update a required CI job for changes under `internal/forge/` and `internal/layers/` that runs `make e2e-test`, or explicitly document an equivalent command and make it a required status check. Run the job for this change and record the successful result in the PR checks or description.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


Grey Divider

Context sources
✅ Compliance rules (platform): 89 rules
✅ Skills: 5 invoked
  writing-user-docs
  writing-adrs
  check-patch-coverage
  cutting-releases
  adr-corner
✅ Cross-repo context — repo relationships
  Explored: repo: fullsend-ai/.fullsend (sha: 7c163cad) — View relationship
  Explored: repo: fullsend-ai/agents (sha: e0166257) — View relationship
Review mode: Auto: 🧠 Deep: Large security-sensitive behavioral change spans multiple independent GitHub paths and error flows.

Grey Divider

Tip of the day
💡 Did you know, you can see how risky a PR is at a glance with blast radius labels

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Grey Divider

Qodo Logo

Comment thread internal/forge/github/commit_graphql.go Resolved
Comment thread docs/problems/security-threat-model.md Resolved
Comment thread internal/forge/github/commit_graphql.go Resolved
Comment thread internal/forge/github/commit_graphql.go Resolved
Comment thread internal/forge/github/github.go Resolved
@gwenneg

gwenneg commented Oct 13, 2026

Copy link
Copy Markdown
Contributor Author

/review

@gwenneg

gwenneg commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor Author

The branch from this PR was successfully built and used locally to onboard the following repo through the GitHub's GraphQL API: RedHatInsights/notifications-gw#1002

Comment thread docs/cli/repos.md Resolved
Comment thread internal/forge/github/commit_graphql.go Resolved
Comment thread internal/forge/github/commit_graphql.go Resolved
Comment thread internal/layers/commit.go Resolved

@waynesun09 waynesun09 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

One finding on the GraphQL branch-protection classification, inline.

Comment thread internal/forge/github/commit_graphql.go Resolved
@gwenneg
gwenneg force-pushed the fix/signed-scaffold-commits branch from c2aa9ae to a95fa3d Compare October 15, 2026 21:49

@waynesun09 waynesun09 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

One finding on merge readiness, inline.

…OnBranch

GitHub signs Git Data REST commits only for App installation tokens, so
scaffold commits made with an operator's token were unsigned, rulesets
with required_signatures rejected them, and the CLI reported the branch
as protected.

Create commits of regular inline files (and deletions) with the GraphQL
createCommitOnBranch mutation, which GitHub signs for any credential;
keep the streamed Git Data path for vendored installs. Map STALE_DATA
onto the non-fast-forward retry and rule violations onto
ErrBranchProtected, and add forge.ErrSignedCommitsRequired so callers
name the signature rule. Classic branch protection is recognised by its
BRANCH_PROTECTION_RULE_VIOLATION type on GraphQL and by the bare check
text it returns on REST, which the ref-update classifier missed for a
pull-request, lock or signature rule. A STALE_DATA answer to a mutation
the transport resent after a 5xx or timeout is checked against the
branch content, so a commit GitHub had already applied is still
reported as made. A RATE_LIMITED answer is resent after the wait
GitHub's headers ask for, or reported at once when that wait is long.
Record the decision and its trade-offs in ADR 0140.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Signed-off-by: Gwenneg Lepage <gwenneg@gmail.com>

@waynesun09 waynesun09 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

One finding on verification coverage, inline.

Comment thread docs/cli/repos.md Resolved
@waynesun09 waynesun09 added the ok-to-test Allow e2e CI to run after maintainer review (must be re-applied after each push) label Oct 17, 2026

@waynesun09 waynesun09 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

LGTM.

@waynesun09
waynesun09 added this pull request to the merge queue Oct 17, 2026
Merged via the queue into fullsend-ai:main with commit 0cb88dc Oct 17, 2026
86 of 87 checks passed
@gwenneg
gwenneg deleted the fix/signed-scaffold-commits branch October 17, 2026 20:30

This branch was successfully deployed

1 active and 1 inactive deployments
dev — 3918a7c6 Deployed Oct 17, 2026 by waynesun09 via run / playback #4807
site-preview — 3918a7c6 Deployed Oct 16, 2026 by github-actions[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ok-to-test Allow e2e CI to run after maintainer review (must be re-applied after each push)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

repos install: GitHub scaffold commits are unsigned with user tokens and rejected by rulesets requiring verified signatures

2 participants