Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,3 +13,23 @@ Verify syntax against the actual Typer command, not the stale README positional
Preserve existing Logseq block structure, Unicode text, dates, section selection, and user content. Treat capture, interactive entry, and file-lock behavior as write surfaces. Use isolated graph/config paths for smoke checks and inspect the intended target before any authorized real capture. Do not rewrite an entire journal to append one item or discard existing content on parse errors.

Read the established Logseq operating procedure before touching the user's actual graph. Avoid logging private note contents or copying them into fixtures. MSI publishing and elevated per-machine installation are distinct release/host operations. A source-only change or isolated writer test does not establish correct writes in the user's live synchronized graph.

## Secret gate before publication

Before publishing the current PR branch, commit the complete candidate and run
`python3 -I scripts/secret_gate.py --base refs/remotes/origin/main` (native Windows: `python -I`). Require exit 0;
missing tooling/authentication, scan errors and skipped scans block publication.
Then run the existing repository gates. Repeat after changing outgoing commits.
Push exactly the scanned HEAD. This PR scan covers the current branch against its
fetched intended base; other refs, multi-ref pushes and rewritten history require
`--pre-push` with Git's complete ref-update stream. Stop if any pushed ref is
uncovered. See [secret scanning](SECRET-SCANNING.md) for base selection, new branches,
pre-push input and prerequisites. Preserve GitGuardian App, CI and Gitleaks checks.

For a non-default PR target, fetch its destination and pass that exact ref to
`--base`; the remote default is not a substitute for a release/maintenance base.

The secret gate requires Python 3.11+ and approved ggshield >=1.56.1,<2.

Explicit bases require fully qualified refs such as `refs/remotes/origin/main`
or full commit SHAs; ambiguous short names block with exit 20.
124 changes: 124 additions & 0 deletions SECRET-SCANNING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
# Secret checks before publication

Before publishing the **current PR branch**, commit the complete candidate and
run the local secret gate against the fetched, intended PR base, followed by this
repository's normal validation. Push exactly the scanned HEAD.
A change to any outgoing commit requires a fresh scan. This gate scans committed
history; it does not certify uncommitted files. It performs no push or PR write.

```sh
python3 -I scripts/secret_gate.py
# Explicit non-default PR target or destination tip (fetch it first):
python3 -I scripts/secret_gate.py --base refs/remotes/origin/release
# Initial publication, empty remote or orphan history, explicitly:
python3 -I scripts/secret_gate.py --all-history
# Offline regression checks (no GitGuardian calls):
python3 -I scripts/test_secret_gate.py -q
```

Use `python` instead of `python3` on native Windows. Python 3.11+, Git, and
ggshield on PATH are required. Require ggshield **>=1.56.1,<2**; this gate was tested with **1.56.1**.
Install ggshield through the approved development-tool environment. Use existing
native ggshield authentication or an approved process-injected
`GITGUARDIAN_API_KEY`; never put credentials in the repository. For a private
GitGuardian instance, explicitly set its approved `GITGUARDIAN_INSTANCE`.
The gate never logs in, creates a key, or requests additional access.

By default the gate queries the configured `origin` remote's **current default
HEAD**, resolves that commit locally, and scans `base..HEAD`. It does not assume
`main`/`master`, use a feature branch's already-pushed upstream as the PR base,
or infer a base from `HEAD~1`. Use `--remote NAME` for a different configured
remote. If the remote tip isn't available locally, fetch it and rerun. A missing
base, failed remote lookup, grafted history or shallow clone blocks; fetch complete history first.
An explicit `--base` trusts the selected locally available ref; fetch it before use.

A PR scan certifies only commits outside its selected base that are reachable
from the current HEAD. It does not certify other branches or tags. Before pushing
other refs, multiple refs, or rewritten history, use `--pre-push` with the complete
Git update stream, normally through a composed pre-push hook. If the intended
publication is not covered by the scan, stop; do not reuse its clean result.

`--pre-push` reads Git's standard four-column ref updates from stdin, validates
all updates, then scans each `old..new` range. Force pushes include all commits
unique to the new tip. A new ref scans **all reachable history**, including root
commits; it can cost more API quota. Multiple updates and lightweight commit tags are supported. Annotated tags are
blocked with exit 20 because commit-range scanning does not cover annotation
text. Rerunning this gate still exits 20, even after an external annotation scan.
This gate does not offer a bypass. Unknown tips and non-commit tags block. Deletes have no content.
No hooks or Git configuration are installed automatically; compose existing hooks
rather than replacing them. Agent instructions require the gate even without hooks.

All commits in the selected range reach `ggshield secret scan commit-range`,
including merged side history and content subsequently removed. There is no hook
commit-count cap. Native ggshield detector/file limits still apply (including
binary/oversize content); this is not an attestation that every byte was scanned.
See the official [commit-range](https://docs.gitguardian.com/ggshield-docs/reference/secret/scan/commit-range)
and [configuration](https://docs.gitguardian.com/ggshield-docs/configuration) references.

Only exit **0 / CLEAN** means a successful scanner run. Other outcomes block:

| Exit | Outcome |
| --- | --- |
| 1 | Findings; remediate before publication |
| 2 | Invalid gate arguments |
| 3 | Authentication failed/unavailable; owner must restore approved native auth |
| 4 | Scan/transport/server/timeout error, or HEAD changed during the scan |
| 10 | Skipped: empty range or deletion-only input; no clean scan claimed |
| 20 | Invalid/unavailable base, Git operation, history or hook input |
| 21 | Required executable unavailable |

No skip or fail-open switch is provided. Strict temporary scanner configuration
ignores local/global exclusions and exit-zero settings; dotenv loading and scanner
log files are disabled, and all secrets are requested. Credentials stay in their
native storage/process environment. Raw findings and diagnostics are suppressed,
including source context; investigate findings locally in an approved private
terminal. Do not paste secret values into chat, tickets or logs.

GitGuardian App/server-side checks, CI secret scans, Gitleaks, branch protection,
and existing approval controls remain required and unchanged. Local scanning adds
an earlier gate; it does not replace them. Existing offline CI entry points remain
offline; agent guidance requires this additional gate. Use the local wrapper where
one is documented; otherwise invoke the Python command explicitly.

Tool executables must resolve outside the checkout through absolute PATH entries.
The gate rejects checkout-owned tools and Windows implicit current-directory
lookup; use an approved user-managed tool environment outside the repository.
Follow this repository's higher Python minimum when applicable.


Always invoke the gate with Python isolated mode (`-I`); an unisolated CLI
returns exit 21 before importing the rest of the gate. Ambient Git location
overrides and Python import/home overrides are removed. Scanner processes run
from a temporary directory with Git explicitly pinned to the intended worktree.
Tool lookup excludes this repository and its linked worktrees, while approved
external installations may be Git-managed. Standard `.git`, submodule and linked-worktree
layouts are supported; unsupported metadata layouts block with exit 20.
For an unsupported ref spelling, resolve and pass its full commit SHA.


For submodules, tool lookup also excludes the enclosing checkout that owns its
Git metadata. The scan remains pinned to the submodule worktree and commits.


Metadata reads are bounded and confined to Git administrative directories;
symlinks escaping those directories block. PR mode rechecks its selected base
after scanning. This narrows the race window; rerun against the exact current
destination before publication, with server checks as the backstop.


Inherited `GIT_EXEC_PATH` is removed from Git and scanner children so it cannot
select a checkout-owned transport helper. Native `pre-push` targets, where
present, consume the complete four-column Git ref-update stream on standard
input. No input returns SKIPPED (exit 10) and blocks publication.

Relative worktree registration pointers resolve against their own directory.
Tool exclusion includes linked worktrees of the enclosing metadata owner for
submodules. Metadata symlink loops return BASE_ERROR (exit 20). Git and scanner
children discard GIT_EXEC_PATH, GIT_SSH and GIT_SSH_COMMAND overrides and Python
startup variables; native SSH agent/config authentication is retained.


Explicit `--base` accepts only a fully qualified ref (for example,
`refs/remotes/origin/main`) or a full commit SHA. Short names such as
`origin/main` block with exit 20 because a local branch can shadow them.
Unsupported metadata path encodings also block with BASE_ERROR (exit 20).
Loading
Loading