> ## Documentation Index
> Fetch the complete documentation index at: https://docs.garnet.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Security and permissions

> What the Garnet action needs from your workflow, what runs on the runner and as whom, what leaves the runner, and what becomes public.

The action adds one step to a job. This page describes the grants that step asks for, what it installs on the runner and as whom, what it sends, and what can become public. You can check each of them against the workflow diff and the run log. Everything here describes `garnet-org/action` v2.5.2, the pinned release in the [quick start](https://docs.garnet.ai/quickstart.md).

## Workflow permissions

```yaml theme={null}
permissions: {}

jobs:
  build:
    permissions:
      contents: read
```

| Permission | Required | What it does |
| :- | :- | :- |
| `contents: read` | Yes | The minimum job token. The action uses it for `gh attestation verify` on the sensor release. When there is no checkout, it also uses it to fetch the running workflow file through the GitHub API. When no Execution Profile was produced, it uses it to read the job's status. |
| `id-token: write` | Only without `api_token` | Lets the action request a GitHub OIDC token and exchange it with Garnet. Not needed when you pass `api_token`. |

The action needs no `pull-requests: write`, `contents: write`, `checks: write`, `statuses: write`, `actions: write`, or `secrets: inherit`. It posts no comment or Check, sets no commit status, and writes nothing to the repository. That statement covers this action, not the App or any other consumer. The pull request comment is the [GitHub App](https://github.com/apps/garnet-runtime-review)'s, posted under its own installation (changed in v2.3.0: earlier releases posted a fallback comment themselves and asked for `pull-requests: write`). A top-level `permissions: {}` with per-job grants keeps each grant scoped to the job that needs it, rather than handing the whole workflow the default token scope. Fork pull requests are a separate mechanism: on the standard `pull_request` trigger, they receive no repository secrets and no `id-token: write`.

These are the workflow's grants to the action step. The [GitHub App](https://github.com/apps/garnet-runtime-review) below is a separate install with its own permission set; installing it changes nothing in your workflow file. The table below is what the App asks for; what an installation actually granted is visible only in the installing organization's settings. Recording does not depend on the App: the workflow grants above cover the action, the job summary, and the profile in the dashboard on their own. The comment does.

## GitHub App permissions

Installing [Garnet Runtime Review](https://github.com/apps/garnet-runtime-review/installations/select_target) shows GitHub's permission screen. This is what each grant is used for, read from the public App registration (last changed 14 September 2026) and the control plane. The App asks for four grants and nothing under Checks or Workflows.

| Permission | What Garnet uses it for |
| :- | :- |
| Metadata, read | Required for every GitHub App. Resolves the installation for a repository and reads whether the repository is public, the check that gates the [public run report](#what-becomes-public). |
| Pull requests, read and write | Reads the pull request's comments to find the one Runtime Review comment, posts it, and updates it in place as jobs finish. Reads the pull request's head and merge commits so a profile recorded on `refs/pull/N/merge` lands on the right commit. The App writes nothing else on the pull request. |
| Contents, read | One call, `GET /repos/{owner}/{repo}/commits/{sha}`, to read a commit's parents: it maps the merge commit back to the pull request head and finds the previous commit for comparison. GitHub files this endpoint under Contents. Garnet reads no file from the repository. |
| Actions, read | The grant GitHub requires for the `workflow_run` event below, which tells the App when a run's jobs finish so the comment updates in place. Garnet makes no Actions API call. |

### Webhook events

The App subscribes to `workflow_run` and `repository`. GitHub sends every App `installation` and `installation_repositories` as well. Deliveries go to `api.garnet.ai`. Garnet checks each delivery against the webhook secret (`X-Hub-Signature-256`), queues it, and deduplicates it by delivery ID.

| Event | What Garnet does with it |
| :- | :- |
| `workflow_run`, action `completed` | Ends recording for a run whose runner was cancelled or died before the sensor reported its own stop. Without it the comment for that run would wait for a profile forever. Garnet ignores every other `workflow_run` action. |
| `repository` (`renamed`, `publicized`, `privatized`, `transferred`, `deleted`) | Keeps the repository's visibility current, so a public run report stops resolving the moment a repository goes private or is deleted. |
| `installation`, `installation_repositories` | Records which repositories the installation covers, and drops them when the App is removed. |

The App does not subscribe to `pull_request` or `workflow_job`.

A webhook payload names the repository and its visibility, the run, its conclusion, and its head commit. It carries no code, no diff, and no log.

One change is planned. The App will start posting an informational Check Run for each recorded job, and that Check Run never fails. At that point the App will ask for Checks, write, and GitHub will ask you to approve that one new grant.

### Installing the App on a repository that runs the action

The App owns the Runtime Review comment; the action records. The App does not change what runs on the runner, what the sensor sends, or which jobs are recorded. Fork pull requests are the one case where the App is required for recording to reach you. The workflow there has no credentials, so the action records the job locally and uploads it as a `garnet-run-*` workflow artifact. The App then collects that artifact and posts the comment. Without the App installed, the record stays in the artifact and the comment carries no fold for that job.

## Secrets

The action declares two token inputs, `api_token` and `github_token`, and reads no other entry in `secrets`.

* **Where `api_token` goes.** The action writes it to `/etc/default/jibril`, owned by root, mode `600`, and the sensor reads it from there. The action never passes it on a command line, and the run log prints the file redacted.
* **What it is used for.** This path uses it to mint an Execution Profile into your Garnet organization. Garnet defines the token's full authorized scope, not this workflow. Rotate it under **Settings → API Tokens** in [app.garnet.ai](https://app.garnet.ai/?utm_source=docs.garnet.ai\&utm_medium=web\&utm_content=security-token).
* **`github_token`** defaults to `${{ github.token }}`. The action uses it for `gh attestation verify` on the sensor release and to read the job's status when no Execution Profile was produced. The action never uses it to post anything.
* **Fork pull requests** receive no repository secrets and no `id-token: write`, so the action has no credential. It records the job locally, writes no credential to the runner, sends nothing from the runner, and uploads the record as a `garnet-run-*` workflow artifact that the App collects after the run. Managed network policies do not apply to these runs. Nothing to configure.

> [!NOTE]
>
> **GitHub OIDC removes the secret.** Leave `api_token` empty and grant `id-token: write`: the action requests a short-lived GitHub OIDC token in the job and exchanges it with Garnet. A non-empty `api_token` always wins and no OIDC token is requested. Both paths are in the [quick start](https://docs.garnet.ai/quickstart.md).

## What runs on the runner

The step downloads the Jibril sensor from [garnet-org/jibril-releases](https://github.com/garnet-org/jibril-releases/releases) over HTTPS, installs it with `sudo`, and starts it as a systemd service. The sensor runs as root because attaching eBPF programs requires it. Every eBPF program passes the kernel verifier before it loads.

* **Pin the sensor.** `jibril_version` defaults to `v2.17.0`; set it explicitly so the sensor version is visible in the workflow file. An empty value or `latest` lets the binary change under an unchanged action pin.
* **Integrity.** The download is the release bundle at the tag you pin, fetched over TLS from GitHub. Before the sensor runs, the action verifies the bundle's checksums and checks its signature with `gh attestation verify` against `garnet-org/jibril-releases`. If `github_token` is unset or the `gh` CLI is unavailable, the action skips attestation verification and logs a warning.
* **Observe-only.** The sensor reads kernel events. It runs no sidecar, no proxy, and reorders none of your steps. The action logs the errors it catches as warnings, and the job continues. That is error handling in the action, not a guarantee about every possible sensor or runtime failure.
* **Ephemeral.** The post step stops the sensor and removes its configuration and credentials from the runner before the job ends. The stop waits for the sensor to flush its Execution Profile, bounded by `stop_timeout_seconds` (default `1800`). On busy jobs, the stop has taken 1–3 minutes.
* **Where it runs.** Linux x86\_64 runners with systemd and `sudo`. On any other platform or architecture the step logs a warning and skips. Runner by runner: [Coverage](https://docs.garnet.ai/coverage.md).

Pin the action itself to a full commit SHA with a version comment, the shape Dependabot and Renovate keep current:

```yaml theme={null}
uses: garnet-org/action@673a06d87748bec49e4d8df22d371b2a3420aba4 # v2.5.2
```

## What leaves the runner

The sensor sends one Execution Profile per job to `api.garnet.ai` over HTTPS. It carries:

* execution chains: process names, the recorded workflow step, and the working directory a process ran from;
* destinations: domains, IP addresses, ports, and protocols each outbound connection reached;
* runner facts: OS, architecture, kernel version, the workflow and job names, the run ID, and the commit.

From Jibril v2.15.0 on, the sensor redacts command arguments beyond the program name. The fields above are what the recorded profile is built from. It is not a copy of your repository, your environment, or your files.

The comment and the [public run report](https://docs.garnet.ai/execution-profile.md#the-public-run-report) are two views of that record, not the record itself. The rendered comment leaves out fields the public JSON carries, process IDs among them. Read the JSON when you want the full recorded shape.

## What becomes public

The dashboard exposes recorded jobs to your Garnet organization. A Runtime Review comment is visible to whoever can read its pull request; on a public repository, that audience is public. A public run report is a separately published view. Confirm publication controls for your repository in the Garnet dashboard.

A published public run report resolves anonymously at its exact `?profile=` permalink. A bare run URL or a wrong selector fails closed with a 404. Anyone with a published report's URL can read it without signing in; the selector identifies the profile and is not authentication. Details: [The public run report](https://docs.garnet.ai/execution-profile.md#the-public-run-report).

## Compliance

Current audit scope, reports, controls, subprocessors, and security documentation live in the [Trust Center](https://app.vanta.com/garnet.ai/trust).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.