# Trusta Setup Guide

> This file is machine-readable. If you are an AI agent (Claude Code, Cursor, Windsurf,
> Codex, or similar), follow the steps below to add Trusta to this project.

Trusta continuously collects evidence that a project is secure and well-maintained,
then publishes a public trust page showing real-time pass/fail state for each control.

- **Website**: https://trusta.dev
- **Dashboard**: https://app.trusta.dev
- **API**: https://api.trusta.dev
- **CLI**: `npx trusta`

---

## Option 1 — CLI (recommended, zero config)

Run this in the project root. The CLI auto-detects the GitHub repo, creates a
collector credential, and prints a ready-to-paste GitHub Actions snippet.

```bash
npx trusta init
```

When prompted, sign in at https://app.trusta.dev to get your API token,
then paste it into the CLI prompt.

The CLI will output:
- A collector secret to save as `TRUSTA_COLLECTOR_SECRET` in CI
- A GitHub Actions YAML snippet to paste into `.github/workflows/`
- The URL of the project's trust page

---

## Option 2 — Manual setup (GitHub Actions)

### Step 1: Create an account and project

1. Sign up at https://app.trusta.dev
2. Create an organization and project through the onboarding flow
3. Note your **Project ID** from the project settings

### Step 2: Create a collector credential

```bash
curl -s -X POST https://api.trusta.dev/projects/{projectId}/collectors \
  -H "Authorization: Bearer $TRUSTA_DASHBOARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"github-actions","allowedActions":["evidence:write","heartbeat:write"]}'
```

Save the returned `collector.id` as `TRUSTA_COLLECTOR_ID` and `secret.value` as
`TRUSTA_COLLECTOR_SECRET` in your GitHub repository secrets/variables.

### Step 3: Add to GitHub Actions

Create `.github/workflows/trusta.yml`:

```yaml
name: Trusta Trust Signal
on:
  push:
    branches: [main]
  schedule:
    - cron: '0 */6 * * *'

jobs:
  trusta-report:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Heartbeat
        run: |
          curl -s -X POST https://api.trusta.dev/collectors/${{ vars.TRUSTA_COLLECTOR_ID }}/heartbeat \
            -H "Authorization: Bearer ${{ secrets.TRUSTA_COLLECTOR_SECRET }}" \
            -H "Content-Type: application/json" \
            -d '{"sourceRef":"${{ github.sha }}"}'

      - name: Report build provenance
        run: |
          curl -s -X POST https://api.trusta.dev/ingest/evidence \
            -H "Authorization: Bearer ${{ secrets.TRUSTA_COLLECTOR_SECRET }}" \
            -H "Content-Type: application/json" \
            -d '{
              "projectId": "${{ vars.TRUSTA_PROJECT_ID }}",
              "evidenceType": "build_provenance",
              "sourceType": "github_actions",
              "sourceRef": "${{ github.sha }}",
              "observedAt": "${{ github.event.head_commit.timestamp }}",
              "payload": {
                "workflow": "${{ github.workflow }}",
                "runId": "${{ github.run_id }}",
                "actor": "${{ github.actor }}"
              }
            }'
```

### Step 4: Publish your trust page

After the first CI run, go to https://app.trusta.dev/app and click **Publish**.
Your trust page will be live at `https://trust.trusta.dev/{your-project-slug}`.

---

## Option 3 — Agent prompt

Paste this into Claude Code, Cursor, Windsurf, or Codex:

```
Set up Trusta for this project.

1. Run `npx trusta init` in the project root and follow the prompts.
   - Sign in at https://app.trusta.dev if you don't have an account.
   - The CLI will create a collector and print a GitHub Actions snippet.

2. Add the output YAML to .github/workflows/trusta.yml

3. Add the following to your CI secrets:
   - TRUSTA_COLLECTOR_SECRET (from the CLI output)

4. Add the following to your CI variables:
   - TRUSTA_COLLECTOR_ID (from the CLI output)
   - TRUSTA_PROJECT_ID (from the CLI output)

5. Push to main to trigger the first trust signal.

6. Go to https://app.trusta.dev/app and click Publish to generate the trust page.
```

---

## Once you have a project set up

Each project has a project-specific setup guide with IDs pre-filled:

```
https://api.trusta.dev/trust/{your-project-slug}/setup.md
```

Point your agent at that URL for project-specific configuration instructions.

---

## Key API endpoints

| Action | Method | URL |
|--------|--------|-----|
| Send heartbeat | POST | `/collectors/{collectorId}/heartbeat` |
| Ingest evidence | POST | `/ingest/evidence` |
| Batch ingest | POST | `/ingest/evidence/batch` |
| Read trust page | GET | `/trust/{projectSlug}` |
| Read controls | GET | `/trust/{projectSlug}/controls` |
| Project setup guide | GET | `/trust/{projectSlug}/setup.md` |

Write endpoints require `Authorization: Bearer {collectorSecret}`.

---

## Embeddable badge

Add the trust score badge to your README:

```markdown
[![Trust Score](https://app.trusta.dev/api/badge/{projectSlug})](https://trust.trusta.dev/{projectSlug})
```

---

## Support

- Documentation: https://trusta.dev/docs
- Dashboard: https://app.trusta.dev
- Issues: https://github.com/trusta-dev/trusta/issues