Onboard a new repository to Safeguard, step by step

To onboard a repository to Safeguard, connect it from Integrations in the web app with a read-only token, or scan it from your own machine with the Safeguard CLI, or let safeguard ci scan import it on the first pipeline run. Then read the first SBOM and findings, keep new commits scanned, and add a policy gate.

You keep the tools you already pay for. Bring the Claude, ChatGPT or Codex plan you already pay for and use it inside the Safeguard CLI. Safeguard adds no extra charge for that usage; your plan's own usage limits and terms still apply. You can also connect Claude or ChatGPT to the Safeguard MCP server and ask about the new project from the chat you already use.

This guide uses one example throughout, a Node service called payments-api, but the steps are the same for Python, Java, Go and other ecosystems. It covers the three ways in, the first results, ongoing scans, gates, and how to bring the rest of the team along.

What you will have at the end

• A repository connected with the least access that does the job, or scanned locally with no repository access granted at all.
• A Safeguard project for it, with a first SBOM and findings sorted by severity and reachability.
• New commits scanned automatically, from the platform or from your pipeline.
• A first policy linked to a gate, with a CI step that fails when the gate fails.
• The same project visible in the web app, the desktop app and on your phone, and an assistant that can fix findings with your approval.

Pick your path

There are three ways to bring a repository in. You can mix them later, so pick the one that fits today.

The Local Runner docs put the CLI path plainly: use it for "private repositories you don't want to give a cloud service OAuth access to", for restricted networks that allow only outbound HTTPS, and when you want the assistant to fix code you have not pushed yet.

Step 1: create a token with the least access

Skip this step for public repositories and for the CLI path. For a private repository connected through Integrations, Safeguard needs a token, and you decide how much it can reach.

GitHub

GitHub recommends fine-grained personal access tokens over classic ones where possible, and so does Safeguard's GitHub integration guide.

1. In GitHub, open your profile picture, then Settings, then Developer settings.
2. Under Personal access tokens, choose Fine-grained tokens, then Generate new token.
3. Name it after its job, for example "Safeguard Integration", and set an expiration date.
4. Under repository access, choose Only select repositories and pick payments-api.
5. Set Metadata to Read-only and Contents to Read-only. These are the two required permissions: Metadata for listing repositories and reading details and tags, Contents for listing branches, reading files and cloning for the scan.
6. Generate the token and copy it straight away. GitHub shows it once.

Leave the optional write permissions off for now. Safeguard's guide lists them for later features: Contents read and write plus Pull requests read and write for fix pull requests, and Commit statuses read and write for a quality gate status on pull requests. You can issue a new token with those when you turn remediation on.

If your organization requires approval for fine-grained tokens, the new token stays pending and can only read public resources until an administrator approves it. Ask for approval before you try to connect.

A classic token works too, but GitHub has no read-only classic scope for private repositories, so repo reaches every private repository its owner can access. Safeguard's guide notes that read:org, admin:repo_hook, write:repo_hook and workflow are not needed.

GitLab

1. Open your profile picture, then Edit profile, then Access Tokens, then Add new token. On self-hosted GitLab, use User Settings, then Access Tokens.
2. Name the token and set an expiration date.
3. Select read_api and read_repository.
4. Create it and copy it immediately.

Bitbucket

The private Bitbucket flow asks for your Username and an Access Token or App Password.

Step 2: connect the repository in the web app

1. Sign in at app.safeguard.sh and select Integrations in the sidebar.
2. Use the filter buttons to show Source Code (SCM). You will see cards for Bitbucket, Git (a generic URL), GitHub and GitLab.
3. Click Connect on your provider's card.
4. For a public repository, choose the Public tab, enter a Name and an optional Description, paste the repository URL, click Add, check the Added URLs table, and click Next.
5. For a private repository, choose the Private tab, enter a Name and optional Description, paste the token, and click Verify Credentials. For self-hosted GitLab, also enter the full GitLab URL including https://. Then click Next and browse to the repository.
6. Tick payments-api and set the options for it:
   • Branch/Tag: the branch you ship from, usually main.
   • Project Name: defaults to the repository name. Keep it unless you have a naming scheme.
   • Version: defaults to 1.0.0. The SBOM docs note it can be auto-detected from git tags.
7. Click Connect.

The SBOM generation docs list two more options worth deciding on: Include Dev Dependencies, which covers build and test tooling too, and Deep Analysis, which enables Griffin AI deep analysis.

The new configuration appears in the Project Configurations table on the Integrations page, and the repository appears on the Projects page with columns for Project Name, Version, Status, Organizations, Findings (summary counts by severity) and Vulnerabilities.

How long the first scan takes

Safeguard's estimate depends on the number of dependencies: under a minute below 100, two to five minutes for 100 to 500, and five to fifteen minutes above 500. Under the hood, the scanner makes a shallow clone into a temporary folder and deletes it when the scan ends. Source code is not stored.

Or onboard from your own machine with the CLI

If you would rather grant no repository access at all, scan from a checkout on your own machine. The source never leaves it; only SBOMs and findings are uploaded.

1. Install the CLI. On macOS and Linux:

curl -fsSL https://cli.safeguard.sh/install | bash

On Windows PowerShell:

irm https://cli.safeguard.sh/install.ps1 | iex

The installer verifies a checksum before it puts anything on your PATH. For a full Linux walkthrough see installing the Safeguard CLI on Linux.

2. Go to the repository and open the interactive terminal:

cd ~/code/payments-api
safeguard
/login
/scan .

/login opens your browser to approve the session. When signed in, an interactive scan uploads the SBOM and findings to the platform, and the project appears in the web app like any other.

3. For a scripted scan, use the command form. It builds an SBOM, matches it against vulnerability databases and writes JSON under ./output, including vuln.json and license.json:

safeguard scan --dir . --org-namespace @yourcompany

--org-namespace tells Safeguard which package namespaces are your own private packages, so they are not mistaken for public ones.

4. Two commands help when you want to look before you share anything:

safeguard sbom --dir . --output payments-api-sbom.json
safeguard findings sca --dir .

safeguard sbom writes an SPDX-JSON SBOM and stops there. safeguard findings runs one scanner locally and prints its findings in one normalized list. Nothing leaves the machine: no project is registered and nothing is uploaded, even when the CLI is signed in.

5. If the platform should route future scans to this machine, keep the runner going:

safeguard runner start --workspace ~/code/payments-api
safeguard runner status

The runner opens all connections itself over outbound HTTPS; nothing connects in to it.

Your first fix, with approvals

Once the first findings are in, the assistant can work on them in the same terminal. This recorded session shows it on payments-api: install with the curl command (checksum verified), safeguard --version, then safeguard opens the interactive terminal. You ask "fix the lodash CVE in this repo", the assistant reads the finding, files and advisory, then asks before each command (press y or n). It edits package.json to lodash 4.17.21, runs npm install and npm test with approval, prints a summary with a suggested commit message and pushes nothing. Then it shows /permissions, /model and /scan ..

Click through it at your own pace, or open it full screen.

Step 3: read the first results

A new project often arrives with a long list. Sort it before you act on it.

1. Open the project from the Projects page and look at the severity counts.
2. Press / to search and narrow with filters. A good first query:

severity:critical AND reachable:true AND project:payments-api

3. Look at the Reachability and Priority columns. Reachability analysis classifies findings as reachable, conditionally reachable, unreachable or unknown, and unknown is treated as potentially reachable rather than hidden. It is GA for static and dynamic analysis on JavaScript and TypeScript, Python, Java, Kotlin and Scala, Go, Rust, C and C++, and C# and .NET.
4. Open the top finding, follow it to the component and the dependency path that brings it in, and note the fixed version.
5. Ask in plain language if you prefer. In the CLI, "how many critical vulns do we have" works as written.
6. Preview what an automated dependency fix would change, without touching a file:

safeguard fix --dry-run --severity high

Step 4: keep new commits scanned

A repository is only onboarded once new code gets scanned without anyone remembering to do it.

From the platform

The GitHub integration scans each selected repository when you connect it and has no webhooks to set up. To pick up new commits, add a schedule under Integrations, then Scheduled, or choose Rescan from the connection's menu. The Integrations docs also describe daily continuous scanning, with optional On Push, Scheduled and On Release triggers. Which triggers you see depends on the provider, so check the connection after you create it.

From your pipeline

If you want every push scanned no matter which provider you use, add safeguard ci scan. A repository that is not imported yet is imported on its first run, under the connected GitHub, GitLab, Bitbucket or Azure DevOps integration that covers it. A public repository on github.com, gitlab.com or bitbucket.org needs no integration at all.

1. Create a Safeguard secret key with the scans:trigger and scans:read scopes in your account's developer settings.
2. In GitHub, open the repository's Settings, then Secrets and variables, then Actions, click New repository secret, and save it as SAFEGUARD_API_KEY.
3. Add a workflow. This is a sketch based on the template in the Safeguard CI docs; copy the current template from the docs for production use:

name: Safeguard
on: [push, pull_request]
jobs:
  safeguard:
    runs-on: ubuntu-latest
    env:
      SAFEGUARD_API_KEY: ${{ secrets.SAFEGUARD_API_KEY }}
      SAFEGUARD_INSTALL_DIR: ${{ runner.temp }}/safeguard-bin
    steps:
      - name: Safeguard scan
        run: |
          set -eu
          curl -fsSL https://cli.safeguard.sh/install | bash
          "$SAFEGUARD_INSTALL_DIR/safeguard" ci scan --wait --fail-on critical

The default mode needs no checkout step, because the scan clones the repository on Safeguard. Each scan is recorded as a version named after the branch and the short commit SHA.

On GitLab, include the job template and extend it:

include:
  - remote: https://registry.safeguard.sh/ci/safeguard.gitlab-ci.yml

safeguard:
  extends: .safeguard-scan
  variables:
    SAFEGUARD_FAIL_ON: critical

Keep the source on the CI runner

With --local, the scan runs on the CI runner over the checkout and uploads only the results. It needs no integration and works for private and self-hosted repositories. It scans dependencies (SBOM and vulnerabilities). Because it scans the files on the runner, keep your usual checkout step before it:

safeguard ci scan --local --wait --fail-on high

On GitLab, set SAFEGUARD_LOCAL: "true" for the same effect. Pin the CLI with SAFEGUARD_VERSION so a new release does not change a build without you noticing.

For assistant work in pipelines, such as a written summary of new critical findings, see running the Safeguard CLI in CI with safeguard exec.

Step 5: add a policy and a gate

Policies decide what counts as acceptable. Gates collect policies and give one answer. Both are evaluated in the platform, not by the CLI.

1. Go to Settings, then Policies, and click Create Policy.
2. Define the condition with the visual builder or YAML, or start from a template. The templates include No Critical Vulnerabilities, License Compliance and No Abandoned Packages.
3. Set the action: Block fails the gate, Warn passes it with a warning naming the policy, Notify passes it and sends a notification.
4. Save and enable the policy, then link it to a gate.

For a new repository, start with one Block policy, such as no critical vulnerabilities, and a Warn policy for licences. Tighten later, once the backlog is under control.

A gate that has never been evaluated shows Not evaluated, never Passed, and an Error is never counted as a pass. The Outcome column under Policies, Gates is turned on per workspace by Safeguard, so ask your Safeguard contact if you do not see it.

With policy outcomes enabled, make the pipeline respect the gate:

safeguard ci scan --wait --fail-on-gate Release

The step fails when the gate is Failed, Error or Not evaluated, and passes on Passed or Warning. When a finding needs an exception, use Request Exception, give a business justification and an expiry date, and the approver's decision is recorded in the audit trail.

Step 6: bring the team in

The project is now in the platform, so everyone sees the same data on whatever surface they use: the web app, the desktop app for Windows, macOS and Linux, and the iOS and Android apps. A CLI session is live too. It shows in the web app, the desktop app and the phone app, and other devices can send work to it.

That helps on day two, when someone else picks up the fixes. This recorded Android session shows the same conversations on the phone. "Work on my computer" picks a computer running the CLI and a folder, the command waits for Allow once, Allow for turn or Deny on the phone, and the answer shows the tests passed.

Click through it at your own pace, or open it full screen.

Teammates who live in a chat assistant can connect it instead. See connect ChatGPT to the Safeguard MCP server; the Claude route works the same way.

When you are ready for automated fixes, autonomous remediation with fix pull requests is generally available and off by default. It needs a token with write access, as described in Step 1, so plan the token change and the switch together.

Do the work properly with the Safeguard CLI

The Safeguard CLI scans code, container images and SBOMs on your own machine, sends only the results to the platform, and includes an assistant that can fix what it finds. It writes code, not only scans it, which makes it the natural place to work through a new project's backlog. For the wider picture, read the Safeguard CLI as a security-aware coding assistant.

Install and first session

One static binary with no Node, Python or JVM needed, for macOS, Linux and Windows, on x86_64 or arm64 (Windows x86_64 only). Install with the commands above, run safeguard, then /login and /scan ..

Writing and fixing code

The assistant has tools for your local files and your Safeguard data. With your approval it can edit code, write files and run commands, so "fix the lodash CVE in this repo" goes from the finding to an edited manifest to passing tests in one session. @ attaches a file from the folder you started in, and /resume picks up the last session there. Before you push, safeguard review --base main reviews your changes for correctness and security. Our guide to reviewing AI-generated code before merge goes further.

Using your Claude, ChatGPT or Codex plan

Bring the Claude, ChatGPT or Codex plan you already pay for and use it inside the Safeguard CLI. Safeguard adds no extra charge for that usage; your plan's own usage limits and terms still apply. /model shows or switches the model; see the CLI docs for connecting one.

Approvals

/permissions offers Ask (reads run; edits and commands ask first), Accept edits (edits in this folder and read-only commands run; other commands ask), Plan (read and plan only), Auto (read-only commands and what the policy allows run; anything else asks; the default) and Strict (pre-approved actions only, for CI). A --yolo flag approves everything and belongs in throwaway sandboxes only. On a repository you have just onboarded, Ask or Plan is a sensible start.

CI with safeguard exec

safeguard exec "summarise the critical findings in this repository"

It runs one non-interactive assistant turn and defaults to strict permissions, so anything not pre-approved is denied.

Troubleshooting

Verify Credentials fails

Check the token's permissions: Contents and Metadata read-only for a GitHub fine-grained token, repo for a classic one, read_api and read_repository for GitLab. A fine-grained token waiting for organization approval can only read public resources.

The repository is missing from the list

A fine-grained token limited to selected repositories only shows those. Edit the token's repository access or create a new one.

Self-hosted GitLab will not connect

Use the full URL including the protocol, and make sure the instance is reachable from Safeguard over HTTPS on port 443. For self-signed certificates, contact support.

The CI step fails on pull requests from forks

GitHub does not pass secrets to workflows run from forks, so SAFEGUARD_API_KEY is empty there.

safeguard scan exits with 2

Results were written but the vulnerability scan did not run. Run safeguard doctor, which checks the environment, sign-in and tools and changes nothing. The CI docs note that safeguard scan uses syft and grype, so a fresh runner needs them on the PATH or TOOLS_DIR pointing to them.

The project never appears

An unconnected repository does not show in search or the asset graph. Check the Project Configurations table, then the Projects page Status column.

Common mistakes

• Granting a classic repo token when a fine-grained read-only token limited to one repository would do.
• Adding write permissions on day one, before anyone has decided to turn on fix pull requests.
• Scanning a feature branch first. Start with the branch you ship.
• Leaving Include Dev Dependencies on or off without deciding. Pick on purpose and tell the team.
• Expecting an Integrations connection to rescan on every push without checking its triggers. Add a schedule or safeguard ci scan.
• Starting with ten Block policies. One Block policy and a couple of Warn policies are easier to live with.
• Reading the raw critical count and panicking. Filter by reachable:true first.

FAQ

Do I have to give Safeguard access to my repository?

No. Scan from your own checkout with the CLI, or use safeguard ci scan --local in CI. In both cases the source stays where it is and only SBOMs and findings are uploaded.

What permissions does the GitHub token need?

For scanning, Metadata and Contents read-only on a fine-grained token, limited to the repositories you choose. Write permissions are only for fix pull requests and commit statuses.

Is my source code stored by Safeguard?

When the platform scans a connected repository, it makes a shallow clone into a temporary folder and deletes it when the scan ends. Source code is not stored.

Can I keep using my Claude, ChatGPT or Codex plan?

Yes. Bring the Claude, ChatGPT or Codex plan you already pay for and use it inside the Safeguard CLI. Safeguard adds no extra charge for that usage; your plan's own usage limits and terms still apply. You can also connect Claude or ChatGPT to the Safeguard MCP server.

How do new commits get scanned?

Use a schedule or Rescan on the connection, the triggers your provider offers, or safeguard ci scan in your pipeline, which scans every run.

Will Safeguard open pull requests on its own?

Not unless you turn it on. Autonomous remediation with fix pull requests is off by default and needs a token with write access.

Can I onboard a repository that is not on GitHub, GitLab or Bitbucket?

Yes. The Integrations page has a generic Git card, and the CLI scans any local folder.

Where are policies checked?

In the platform. The CLI scans and reports; --fail-on-gate asks the platform for the gate's result.

Try it yourself

If you are taking the CLI path, this walkthrough shows the setup: set up the runner on your own machine, pick the platform, start it, approve it with its device code, then use the same CLI to scan from the terminal.

Click through it at your own pace, or open it full screen.

Get the CLI or the apps at safeguard.sh/download, and keep the Safeguard CLI docs open while you onboard.

Quick check

Sources

• Safeguard download page
• Safeguard CLI documentation
• Safeguard Local Runner docs
• Safeguard integrations docs
• Safeguard: generate an SBOM
• Safeguard GitHub integration (source code)
• Safeguard GitHub integration permissions
• Safeguard GitLab integration
• Safeguard CI/CD integration
• Safeguard policies and gates
• Safeguard policy outcomes and actions
• Safeguard reachability analysis
• GitHub Docs: managing your personal access tokens
• GitHub Docs: using secrets in GitHub Actions

Last reviewed: 21 October 2026.