Publishing resources

everr apply publishes the resources in your everr/ directory — from your machine, from CI, or as a shareable preview on a pull request. Folders come from directories; isolation comes from metadata.project; multi-repo ownership comes from the repoid in everr.yaml.

If you want folders

Declarations live in an everr/ directory at your repo root, flat and named by kind (*.dashboard.yaml). The index shows a folder tree derived from each file's directory, relative to the directory you applied — you don't define folders. Subdirectories are optional. Segments join into the folder path with /; underscores and hyphens render as spaces (team_payments → team payments). Move a file and re-apply to move the resource between folders — there are no folder objects to create, rename, or delete.

everr/
  everr.yaml                          -> manifest (declares the repoid)
  overview.dashboard.yaml             -> root
  platform/
    api-latency.dashboard.yaml        -> folder "platform"
    db_health.dashboard.yaml          -> folder "platform"
  team_payments/
    checkout/
      funnel.dashboard.yaml           -> folder "team payments / checkout"

If you share one org across teams

Every resource may declare metadata.project (defaults to default), independent of the repoid. A project is an identifier you choose per team (platform, team-payments). It namespaces identity: full identity is project + slug, URL is /dashboards/<project>/<slug>, so two projects can each have an overview dashboard without colliding. It's optional and doesn't need to appear in the manifest.

If you apply from more than one repo

The everr/ directory must contain an everr.yaml (or .yml) at its root declaring a stable repoid — the only key the manifest accepts. The repoid is the apply ownership boundary: everr apply reconciles exactly what was previously applied under this id, nothing else. Use one id per repo (a UUID is a good default) and never reuse it across unrelated repos. Never change the repoid on an existing setup — that orphans everything applied under the old id, leaving the old resources live but unmanaged.

Give each repo its own repoid and applies never collide — everr apply can never touch another repo's (or org's) resources. The platform repo — everr/everr.yaml:

repoid: "0b6c1f4e-8a21-4d3b-9f17-2c5e7a9d6b04"
# api-latency.dashboard.yaml -> metadata.project: platform

The payments repo — everr/everr.yaml:

repoid: "9d2a77c3-1e54-4f8a-b6d0-3a8c1f2e5b97"
# checkout-funnel.dashboard.yaml -> metadata.project: team-payments

Apply each repo independently with everr apply ./everr — once in the platform repo, once in the payments repo, entirely separately.

If you apply from CI

Install the CLI with everr-action (CI runners don't include it), then set EVERR_API_KEY to an org API key with the apply scope — the same ek_ keys you mint for ingest; the Capabilities column shows what each key can do (the legacy EVERR_API_TOKEN is still accepted). Outside CI, everr apply uses your everr cloud login session and prints the destination org before writing; if EVERR_API_URL isn't set, the base URL falls back to the one saved by that login.

# .github/workflows/dashboards.yml
name: Apply dashboards
on: { push: { branches: [main], paths: ["everr/**"] } }
jobs:
  apply:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: everr-labs/everr-action@v0
        with: { install-cli: "true", resource-usage: "false" }
      - run: everr apply ./everr --yes
        env:
          EVERR_API_KEY: ${{ secrets.EVERR_API_KEY }}
          EVERR_API_URL: ${{ vars.EVERR_API_URL }}

--yes (or -y) skips the confirmation prompt apply shows before writing — required in non-interactive contexts like CI or piped scripts; use --preview instead to stage changes without writing — a preview is a full staged copy under a name, explained in the next section — and previews never prompt. Gate the apply on your default branch so resources change only after review. To preview in a pull request, apply with an explicit preview name (PR checkouts are detached, so the branch can't be inferred) and post the printed link on the PR:

everr apply ./everr --preview "pr-${{ github.event.number }}"

Merging triggers the main-branch workflow above, shipping the changes live.

If you want to preview before it ships

Apply is a full sync of files to live state within the repoid: new files create resources, changed files update them, removed files delete them — no separate prune step; moving a file relocates its resource, emptying the tree removes its last one (see Observability as code for the full apply model). Always stage into a preview first:

$ everr apply ./everr --preview
Destination org: «Acme Corp»
Dashboard: 4 created, 0 updated, 0 deleted
  + db-health
  + api-latency
  + overview
  + payments
Preview: https://app.everr.dev/dashboards?preview=my-branch

The preview is a full copy of the tree under a name (your git branch by default), deployed without touching live resources. Open the link: each resource is badged added, changed, removed, or unchanged against live state, and the link is shareable with anyone in the org. Previews expire on their own 7 days after their last apply.

Full flag and environment list: everr apply CLI reference.