You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 02c935e
Browse filesBrowse the repository at this point in the historyBrowse files
<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
2
+
<!-- SPDX-License-Identifier: Apache-2.0 -->
3
+
4
+
# Git and GitHub Access Hard Stop
5
+
6
+
Use this guardrail from any workflow that runs `git`, `ssh`, or `gh` commands.
7
+
8
+
If a Git/GitHub command fails because of authentication, authorization, missing credentials, SSO, token scope, SSH key setup, remote access, or push permissions, stop and ask the user to resolve access.
9
+
10
+
Do **not** work around access failures by:
11
+
12
+
- switching remote protocols or remotes;
13
+
- editing credentials, tokens, or SSH config;
14
+
- generating new tokens or SSH keys;
15
+
- rewriting remotes to bypass permissions;
16
+
- force-pushing or bypassing branch protections/required checks.
17
+
18
+
Report the exact command, the relevant error output, and the next action needed from the user, then wait.
19
+
20
+
This hard stop is for access/authentication/authorization problems only. Normal Git workflow problems such as merge conflicts, stale branches, dirty worktrees, or mechanical rebase conflicts should be handled by the relevant workflow. Stop for user guidance only when conflict resolution would change behavior, alter contributor intent, or require a design decision.
-**CI failure:** inspect the failing job logs, fix the root cause, rerun relevant local checks, commit, push, and monitor again.
36
+
-**CodeRabbit or PR Review Advisor correctness/security/test-coverage finding:** address it when valid, rerun relevant checks, commit, push, and monitor again.
37
+
-**Style nits or false positives:** avoid unnecessary churn. Note the rationale in your final report or comment on the PR when reviewer-visible context is useful.
38
+
-**Ambiguous, risky, broad, or design-changing feedback:** stop and consult the user before changing code.
39
+
40
+
Repeat until required CI is green and there are no unresolved actionable CodeRabbit or PR Review Advisor findings, or until the user tells you to stop.
41
+
42
+
If any follow-up push or `gh`/GitHub query hits SSH, authentication, remote access, authorization, or permission problems, follow [Git and GitHub Access Hard Stop](git-github-hard-stop.md). Do not stop for ordinary merge conflicts or dirty-worktree state; resolve mechanical conflicts in the relevant workflow and ask the user only when resolution would change behavior or contributor intent.
Copy file name to clipboardExpand all lines: .agents/skills/nemoclaw-contributor-create-pr/SKILL.md
+93-24Lines changed: 93 additions & 24 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
---
2
2
name: nemoclaw-contributor-create-pr
3
-
description: Create GitHub pull requests that follow the NemoClaw PR template. Use when the user wants to create a new PR, submit code for review, open a pull request, or push changes for review. Trigger keywords - create PR, pull request, new PR, submit for review, open PR, push for review.
3
+
description: Create GitHub pull requests that follow the NemoClaw PR template, then monitor CI and automated review feedback. Use when the user wants to create a new PR, submit code for review, open a pull request, or push changes for review. Trigger keywords - create PR, pull request, new PR, submit for review, open PR, push for review.
4
4
---
5
5
6
6
# Create GitHub Pull Request
@@ -12,6 +12,11 @@ Create pull requests on the NemoClaw GitHub repository using the `gh` CLI. This
12
12
- The `gh` CLI must be authenticated (`gh auth status`).
13
13
- You must be in the NemoClaw git repository.
14
14
- You must have commits on a branch that is pushed to the remote.
15
+
- The PR description must include a valid DCO `Signed-off-by:` declaration, and every commit that will appear in the PR must appear as `Verified` in GitHub.
16
+
17
+
## Hard Stop: Git, SSH, and Authentication Problems
18
+
19
+
Follow the shared [Git and GitHub Access Hard Stop](../_shared/git-github-hard-stop.md) guardrail for SSH, authentication, remote access, authorization, or permission failures. Resolve ordinary Git workflow problems such as merge conflicts or dirty worktrees in the current workflow.
15
20
16
21
## Step 1: Verify Branch State
17
22
@@ -35,27 +40,47 @@ Before creating a PR, verify the branch.
35
40
git status
36
41
```
37
42
38
-
## Step 2: Run Pre-PR Checks
43
+
## Step 2: Choose Efficient Pre-PR Checks
44
+
45
+
Do not rerun the whole local gate just to create a PR when Git hooks already supplied that evidence.
46
+
Use the checks that match the diff and the verification you already have.
39
47
40
-
Choose checks based on the files changed.
48
+
### Hook Evidence
41
49
42
-
For code changes, run both checks and confirm they pass before proceeding:
50
+
If the commits were created normally and the branch was pushed normally, count the installed hooks as verification:
-`pre-push` runs TypeScript build and type-check gates.
55
+
56
+
If hooks were skipped with `--no-verify`, were not installed, failed, or you cannot tell whether they ran, run a manual diff-scoped fallback before creating the PR:
43
57
44
58
```bash
45
-
npx prek run --all-files
46
-
npm test
59
+
npx prek run --from-ref main --to-ref HEAD
47
60
```
48
61
49
-
For doc-only changes, do not run the full test suite unless the docs change requires it.
50
-
Run the docs and hook checks instead:
62
+
Use `npx prek run --all-files` only when you need a whole-repository baseline, such as changing hook configuration, formatter configuration, generated-check scripts, or other repo-wide validation behavior.
63
+
64
+
### Targeted Tests
65
+
66
+
Run the smallest meaningful tests for changed behavior:
67
+
68
+
- CLI or root `src/`, `bin/`, `scripts/`, or `test/` changes: `npx vitest run --project cli` or the directly affected test file.
69
+
- Plugin changes under `nemoclaw/src/`: `npx vitest run --project plugin` or the directly affected plugin test file.
70
+
- E2E support changes under `test/e2e-scenario/support-tests/`: `npx vitest run --project e2e-vitest-support`.
71
+
- Installer behavior changes: run the relevant installer integration project only when the local environment supports it.
72
+
73
+
Reserve full `npm test` for broad runtime changes, test harness changes, or cases where targeted coverage is hard to justify.
74
+
Do not run the full test suite for doc-only changes unless the docs change code samples or generated behavior in a way that needs runtime validation.
75
+
76
+
For doc-only changes, run the docs build before opening the PR:
51
77
52
78
```bash
53
-
npx prek run --all-files
54
79
npm run docs
55
80
```
56
81
57
82
If a required check fails, fix the issue before creating the PR.
58
-
When preparing the PR body for a doc-only change, leave the `npm test` verification box unchecked unless you actually ran it.
83
+
When preparing the PR body, check only the verification boxes backed by hooks, manual commands, or CI evidence you actually have.
59
84
60
85
## Step 3: Push the Branch
61
86
@@ -65,7 +90,36 @@ Ensure the branch is pushed to the remote.
65
90
git push -u origin HEAD
66
91
```
67
92
68
-
## Step 4: Determine PR Metadata
93
+
If the push fails because of SSH, authentication, remote access, authorization, or permission problems, follow [Git and GitHub Access Hard Stop](../_shared/git-github-hard-stop.md). Resolve ordinary non-access Git failures, such as merge conflicts or dirty worktrees, in the current workflow.
94
+
95
+
## Step 4: Prepare DCO Declaration and Verify GitHub Commits
96
+
97
+
Before creating the PR, prepare the DCO declaration for the PR body and verify every commit in `main..HEAD`.
98
+
This is a hard contributor self-serve gate.
99
+
Do not run `gh pr create` until the PR body will include the DCO declaration and every commit passes GitHub verification.
100
+
101
+
1.**DCO declaration.** The PR body must include a `Signed-off-by:` declaration for the contributor.
102
+
Use the contributor's configured Git identity unless the contributor provides a different valid identity.
103
+
104
+
```bash
105
+
git config user.name
106
+
git config user.email
107
+
```
108
+
109
+
2.**GitHub verification.** Each pushed commit must appear as verified in GitHub.
110
+
Check the commit SHAs from `main..HEAD` with the GitHub API before opening the PR.
If the PR body would miss the DCO declaration or any commit is missing GitHub verification, stop.
119
+
Tell the contributor to fix the issue before opening a PR.
120
+
If force-push is not allowed and the published branch already contains an unverified commit, require a fresh branch and fresh PR with a clean compliant history.
121
+
122
+
## Step 5: Determine PR Metadata
69
123
70
124
### Title
71
125
@@ -100,14 +154,15 @@ Check the branch name and commit messages for issue references. If an issue exis
100
154
101
155
### DCO Sign-Off
102
156
103
-
The PR body must include a DCO sign-off line. Determine the user's name and email from git config:
157
+
The PR body must include a DCO sign-off line.
158
+
Determine the user's name and email from git config:
104
159
105
160
```bash
106
161
git config user.name
107
162
git config user.email
108
163
```
109
164
110
-
## Step 5: Compose the PR Body
165
+
## Step 6: Compose the PR Body
111
166
112
167
Use the exact template structure below. Fill in each section based on the diff (`git diff main...HEAD`). Check the applicable boxes and leave others unchecked. Do not add, remove, or reorganize sections.
113
168
@@ -129,8 +184,10 @@ Use the exact template structure below. Fill in each section based on the diff (
129
184
130
185
## Verification
131
186
<!-- Check each item you ran and confirmed. Leave unchecked items you skipped. Doc-only changes do not require npm test unless you ran it. -->
132
-
-[ ]`npx prek run --all-files` passes
133
-
-[ ]`npm test` passes
187
+
-[ ] PR description includes the DCO sign-off declaration and every commit appears as `Verified` in GitHub
188
+
-[ ] Git hooks passed during commit and push, or `npx prek run --from-ref main --to-ref HEAD` passes
189
+
-[ ] Targeted tests pass for changed behavior
190
+
-[ ] Full `npm test` passes (broad runtime changes only)
134
191
-[ ] Tests added or updated for new or changed behavior
135
192
-[ ] No secrets, API keys, or credentials committed
136
193
-[ ] Docs updated for user-facing behavior changes
@@ -139,7 +196,7 @@ Use the exact template structure below. Fill in each section based on the diff (
139
196
-[ ] New doc pages include SPDX header and frontmatter (new pages only)
<!-- DCO sign-off is required in this PR description, and every commit must appear as Verified in GitHub. Run: git config user.name && git config user.email -->
143
200
Signed-off-by: {name} <{email}>
144
201
```
145
202
@@ -151,19 +208,20 @@ Follow these rules when filling in the template:
151
208
-**Related Issue:** Include `Fixes #NNN` or `Closes #NNN` if an issue exists. Remove the section entirely if there is no related issue.
152
209
-**Changes:** Bullet list of key changes. Be specific — reference file names, commands, or behaviors that changed.
153
210
-**Type of Change:** Check exactly one box. Use `[x]` for checked, `[ ]` for unchecked.
154
-
-**Verification:** Check only the boxes for steps you actually ran and confirmed passing. Do not check boxes for steps you skipped or did not verify. For doc-only changes, `npm test` is not required; leave it unchecked unless you ran it.
211
+
-**Verification:** Check only the boxes for steps you actually ran and confirmed passing, or for Git hooks that passed during normal commit and push. Do not check boxes for steps you skipped or did not verify. The DCO declaration and GitHub verification checkbox is mandatory before PR creation because Step 4 must pass first. For doc-only changes, `npm test` is not required; leave it unchecked unless you ran it.
155
212
-**DCO Sign-Off:** Replace `{name}` and `{email}` with values from `git config user.name` and `git config user.email`.
156
213
157
-
## Step 6: Create the PR
214
+
## Step 7: Create the PR
158
215
159
216
Use `gh pr create` with the `--assignee @me` flag and a HEREDOC for the body to preserve formatting.
217
+
Only run this step after Step 4 confirms that the PR body includes the DCO declaration and every commit is GitHub-verified.
160
218
161
219
```bash
162
220
gh pr create \
163
221
--title "<type>(<scope>): <description>" \
164
222
--assignee "@me" \
165
223
--body "$(cat <<'EOF'
166
-
<full PR body from Step 5>
224
+
<full PR body from Step 6>
167
225
EOF
168
226
)"
169
227
```
@@ -185,20 +243,31 @@ For work-in-progress that is not ready for review:
After creating the PR, do not stop at the URL. Follow the shared [PR CI and Automated Review Follow-Up](../_shared/pr-follow-up.md) workflow: watch required CI, inspect CodeRabbit and PR Review Advisor feedback, address valid findings, and consult the user when feedback is ambiguous or design-changing.
249
+
250
+
## Step 9: Report the Result
189
251
190
-
After the PR is created, display the PR URL as a clickable markdown link:
252
+
After the PR is created and the initial CI/reviewer follow-up is handled, display the PR URL as a clickable markdown link and summarize the status:
191
253
192
254
```text
193
255
Created PR [#NNN](https://github.com/NVIDIA/NemoClaw/pull/NNN)
256
+
CI: passing/pending/failing
257
+
Automated review: no actionable findings / addressed findings / waiting on user
194
258
```
195
259
196
260
## Common Mistakes to Avoid
197
261
198
-
-**Do not invent your own PR body format.** Use the template from Step 5 exactly.
262
+
-**Do not invent your own PR body format.** Use the template from Step 6 exactly.
199
263
-**Do not omit sections.** Even if a section is not applicable, keep it with the "Skip if..." comment.
200
264
-**Do not check boxes for steps you did not run.** If you did not run `npm run docs`, leave that box unchecked.
201
-
-**Do not run the full test suite for doc-only changes by default.** Run docs and hook checks instead, and leave `npm test` unchecked unless you actually ran it.
202
-
-**Do not forget the DCO sign-off.** CI will reject the PR without it.
265
+
-**Do not rerun hook-covered checks by default.** Normal commit and push hooks are valid verification. Use `npx prek run --from-ref main --to-ref HEAD` as the fallback when hooks were skipped, missing, or uncertain.
266
+
-**Do not run the full test suite for doc-only changes by default.** Run the docs build instead, and leave `npm test` unchecked unless you actually ran it.
267
+
-**Do not forget the DCO sign-off declaration in the PR body.** CI will reject the PR without it.
268
+
-**Do not create PRs with unverified commits.** GitHub must report every PR commit as `Verified` before the PR is opened.
269
+
-**Do not rely on maintainers to repair contributor signature history.** If force-push is not allowed and the branch contains an unverified commit, use a fresh branch and fresh PR.
203
270
-**Do not forget `--assignee @me`.** Every PR must be assigned to its creator.
204
271
-**Do not create PRs from main.** Always use a feature branch.
272
+
-**Do not troubleshoot Git/GitHub access in-agent.** If SSH, `gh`, authentication, remote access, authorization, or push permissions fail, stop and ask the user to fix access. Do resolve ordinary merge conflicts and dirty-worktree state when the workflow calls for it.
273
+
-**Do not abandon the PR immediately after creation.** Watch CI and automated feedback from CodeRabbit and the PR Review Advisor, address valid findings, and consult the user when feedback is ambiguous.
0 commit comments