Pushgate.dev documentation

Connect a repository, approve your agent, send a signed push, then choose your code checks.

Pushgate is a checkpoint between your coding agent and GitHub. You choose the requirements; your agent runs the checks and sends signed results. Start with one repository and a signed push, then choose any additional code checks.

Set up your first repository

1. You connect your repository. Open repository setup, sign in with your TestifySec account, and choose the GitHub repository where your code belongs. GitHub may ask you or your organization to authorize access. A repository is a project stored on GitHub; a push sends changes to it.
2. You approve your agent. Give the generated instructions to your agent. It installs or checks CI/lock 4.5.0 or later and starts enrollment scoped to that repository. Review the requested access and approve it with your platform passkey. Use the explicit new-tab option if the approval popup cannot open. The agent completes its technical setup and checks its signing status.
3. Your agent makes the first signed push. With the new-repository defaults, it records Git metadata and agent observations for the exact commit, signs the push, and waits for delivery to GitHub. No test command is required by that metadata-only baseline.
4. You choose ongoing checks. After delivery, your agent gives you the repository’s policy-page link. The next distinct push waits for your choice: activate additional checks or explicitly choose Keep default protection. Your agent may prepare and explain a policy, but it cannot approve or dismiss this choice for you.

Check the first signed push

Copy the instructions from repository setup. They contain the correct repository-specific remote and enrollment command. Do not put credentials in chat or construct a broader credential. After enrollment, the agent must confirm that its own signing identity is usable:

cilock agent status

For a new repository using default protection, CI/lock 4.5.0 or later can record metadata without running a test command:

cilock attest --step push-metadata -a git -a alps-evidence

This creates one signed evidence collection containing both the Git record and agent observations for the current commit. It does not run tests or scan the code. Agent observations do not authenticate an agent’s model or prove its isolation. If the commit changes, produce fresh evidence.

After following setup’s Git configuration, an ordinary push through origin goes through Pushgate. Check delivery for that same remote and current commit:

git push origin HEAD
cilock pushgate status --remote origin --wait

Accepted or queued is not delivered. Wait for the delivery result before calling the first push complete. A refused push gives the agent a missing requirement and next action. Follow that response; do not replace repository requirements just to get through.

Existing repositories keep their current requirements. They do not receive a free push or lose an enforced code check. For additional requirements, use setup’s generated command and evidence step instead of assuming the metadata-only example applies.

Choose and activate your checks

A policy is the list of requirements for your repository. The check library offers built-in secret scanning, alongside custom policies for commands your team already runs. Go vulnerability checks and other dependency scanners need a custom command policy whose command fails on the findings you want to block. Tests, coverage thresholds, lint, type checks, architecture rules, infrastructure validation and accessibility checks also need the appropriate project command and passing condition.

Your agent can run a configured command through cilock run, prepare a draft and explain its limits. You review the exact requirements and approve their activation in Pushgate. Publishing a custom policy does not activate it: signing and publication are followed by a separate repository assignment approval. Select Block for requirements that must prevent a push; Warn records failures without blocking them.

Keep default protection retains signed pushes, Git metadata and agent observations. It does not add code tests or security scans. A delivered signed push and passing code checks are different milestones; the quality of your configured checks still matters.

Prevent a route around the gate

Read the trust model

The rest of this section follows one push through the system. Start with the trust path, then use the evidence and policy pages as embedded contracts when you integrate another attestor, CI workflow, or verifier.

flowchart LR
    A[Agent workspace] -->|runs the work| C[CI/lock witness]
    C -->|signed in-toto / DSSE| T[TestifySec platform]
    T -->|signed policy decision| P[Pushgate edge]
    P -->|accepted update| G[GitHub]

Core terms

Attestation

A signed in-toto Statement describing an observed command, result, subject, or material.

Policy

A signed document describing which evidence and identities are required.

VSA

A signed verification summary that binds a policy outcome to the exact push context.

gitoid

A content identifier computed from the exact bytes of a stored envelope.