Maintainer

Wenn du ein Open-Source-Projekt pflegst, können Leute es ausprobieren, ohne etwas zu installieren. Ein „Run on Setup“-Link öffnet Setup mit deinem Repository schon eingefügt. Setup findet heraus, wie das Projekt läuft, und wer klickt, bekommt für etwa eine Stunde eine laufende Kopie in einer Sandbox.

Das „Runs on Setup“-Badge zeigt, ob das wirklich klappt. Es wird grün, sobald ein echter Runner dein Projekt gestartet hat und alle Checks bestanden sind, und wird wieder grau, wenn der letzte erfolgreiche Lauf älter als 30 Tage ist. Legst du eine setup.json in dein Repository, nimmt Setup dein Rezept, statt zu raten.

Für Link und Badge brauchst du kein Konto. Der Generator auf der Seite für Maintainer schreibt dir beides.

Der „Run on Setup“-Link

Der Link lautet /run?source=<url>:

https://setup.run/run?source=github.com/louislam/uptime-kuma

source nimmt alles, was auch das Feld auf Start nimmt, meistens eine Repository-URL. Wer angemeldet ist, landet direkt in der Analyse. Alle anderen melden sich an oder erstellen ein Konto und kommen danach bei derselben Analyse an. Dort lesen sie das Rezept und starten einen Test.

Snippets für Badge und Button

Der Generator auf der Seite für Maintainer nimmt owner/repo oder eine GitHub-URL und erzeugt diese beiden Snippets. Beide verlinken das Badge mit dem „Run on Setup“-Link.

Markdown:

[![Runs on Setup](https://setup.run/api/badge/uptime-kuma)](https://setup.run/run?source=github.com/louislam/uptime-kuma)

HTML:

<a href="https://setup.run/run?source=github.com/louislam/uptime-kuma"
  ><img src="https://setup.run/api/badge/uptime-kuma" alt="Runs on Setup"
/></a>

Die Katalogseite deines Projekts unter /catalog/<slug> hat einen Abschnitt Für Maintainer mit demselben Badge und dem „Run on Setup“-Button, einem dunklen Button-Bild von /api/badge/<slug>/button:

[![Run on Setup](https://setup.run/api/badge/uptime-kuma/button)](https://setup.run/run?source=https%3A%2F%2Fgithub.com%2Flouislam%2Fuptime-kuma)

Die Snippets in deinem Setup zeigen dessen eigene Adresse. setup.run dient hier nur als Beispiel.

Den Slug prüfen

Die Badge-URL endet mit dem Slug des Projekts. Der Generator leitet ihn aus dem Repository-Namen ab, aus louislam/uptime-kuma wird uptime-kuma. Das passt für Projekte im kuratierten Katalog. Ein Projekt, das Setup bei einer Analyse angelegt hat, trägt meist den Owner im Slug, etwa louislam-uptime-kuma, und bekommt ein kurzes zufälliges Suffix, wenn der Name schon vergeben war.

Die Snippets im Abschnitt Für Maintainer der Katalogseite haben immer den richtigen Slug. Im Zweifel kopierst du sie von dort.

Was das Badge zeigt

Links steht auf dem Badge setup, rechts der Zustand.

Ein Lauf auf Setup hat Vorrang vor einer CI-Meldung. Die Antwort enthält den Zustand (runs, ci, unverified oder unknown) auch im Header X-Setup-Badge, praktisch für Skripte. Badge-Bilder werden etwa fünf Minuten zwischengespeichert, eine Änderung braucht also einen Moment.

Öffentliche, nicht gelistete und private Projekte

Badges antworten nur für öffentliche und nicht gelistete Projekte. Projekte im kuratierten Katalog sind öffentlich. Ein Projekt, das Setup bei einer Analyse angelegt hat, ist zuerst privat und gehört dem Workspace, der es zuerst analysiert hat. Sein Badge zeigt unknown, bis es öffentlich oder nicht gelistet ist. Nicht gelistete Projekte kann jeder mit dem Link öffnen, sie erscheinen aber nicht im Katalog.

Im Dashboard gibt es dafür noch keinen Schalter. Mitglieder des Workspaces, dem das Projekt gehört, ändern es mit einem API-Schlüssel. GET /api/projects/<slug> liefert das Projekt mit seiner id:

curl -X PATCH https://setup.run/api/projects/<project-id> \
  -H "Authorization: Bearer $SETUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"visibility":"unlisted"}'

visibility ist private, unlisted oder public. Hat der Workspace von jemand anderem dein Repository zuerst analysiert und gehört ihm das Projekt, schreib uns.

Eine setup.json ins Repository legen

Leg eine setup.json ins Wurzelverzeichnis deines Repositorys. Zeigt dein Link auf ein Unterverzeichnis (/tree/<ref>/<dir>), gehört sie in dessen Wurzel. Am einfachsten bekommst du eine mit setup.json herunterladen im Abschnitt Für Maintainer auf der Katalogseite deines Projekts: Das ist das Rezept, das Setup ausführt, ohne die Standardwerte. Das Format beschreibt die Seite Rezepte. Eine kleine sieht so aus:

{
  "version": 1,
  "slug": "uptime-kuma",
  "name": "Uptime Kuma",
  "category": "homelab",
  "source": {
    "kind": "github",
    "url": "https://github.com/louislam/uptime-kuma"
  },
  "services": {
    "app": {
      "image": "louislam/uptime-kuma:1.23.16",
      "ports": [{ "container": 3001 }],
      "volumes": [{ "name": "data", "path": "/app/data" }]
    }
  },
  "expose": { "service": "app", "port": 3001 },
  "checks": { "http": { "path": "/" } }
}

Was Setup damit macht:

• Sie hat Vorrang. Eine gültige setup.json schlägt Setups eigene Erkennung. Die Analyse zeigt dann „Recipe maintained in the repository (setup.json)“.
• Die Quelle bleibt deine. Setup baut das Repository, das eingefügt wurde, und zwar den analysierten Commit. Das Feld source aus deiner Datei ersetzt Setup dabei. Zeigt source.git.url auf ein anderes Repository, ignoriert Setup das und zeigt eine Warnung. Auch ein Service, der aus einem fremden Repository baut, bekommt eine Warnung.
• Eine kaputte Datei wird übersprungen. Ungültiges JSON oder ein Rezept, das seine Prüfungen nicht besteht, ignoriert Setup mit einer Warnung und erkennt das Projekt dann selbst.
• Änderungen werden Revisionen. Jede Analyse liest die Datei im analysierten Commit. Hat sich der Inhalt geändert, legt Setup eine neue Revision des Rezepts an.

Steht dein Projekt auch im kuratierten Katalog von Setup, zeigt die Katalogseite weiter das kuratierte Rezept.

Willst du ein Rezept ausprobieren, bevor du es committest, füg den Inhalt der Datei in das Feld auf Start ein und starte einen Test. Du siehst dieselben Checks wie alle anderen. Mit installiertem Runner prüft setup-runner validate setup.json die Datei offline nach denselben Regeln wie Setup und zeigt die Zeile jedes Problems.

setup.json in der CI prüfen

Die GitHub Action von Setup prüft deine setup.json bei jedem Pull Request und meldet Läufe für Releases an Setup. Der Tab GitHub Action im Abschnitt Für Maintainer schreibt einen Workflow für dein Projekt. Er sieht so aus:

on:
  pull_request:
    paths: [setup.json]
  push:
    tags: ["v*"]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: setup-run/verify-action@v1
        with:
          api-key: ${{ startsWith(github.ref, 'refs/tags/') && secrets.SETUP_API_KEY || '' }}

Bei jedem Lauf prüft die Action die Datei und markiert Probleme direkt im Pull Request. Dann startet sie dein Rezept in einer Wegwerf-Sandbox auf dem Docker des GitHub-Runners, führt die Checks aus und räumt die Sandbox wieder ab. Der Bericht landet als Artefakt am Lauf und als Zusammenfassung darüber.

Damit Läufe gemeldet werden, erstellst du unter Maintainer-Tokens auf der Katalogseite deines Projekts ein Maintainer-Token (das sehen nur die Eigentümer des Projekts) und speicherst es in deinem Repository als Secret SETUP_API_KEY. Ein Maintainer-Token gehört zu genau einem Projekt und kann nur Läufe dafür melden. Es wird einmal angezeigt, kann ein Ablaufdatum bekommen und lässt sich jederzeit widerrufen.

Läufe, die deine CI meldet, heißen Von CI gemeldet. Setup hat sie nicht gesehen, deshalb gelten sie nie als von Setup verifiziert: Sie ergeben das blaue Badge ci passed, Läufe auf Runnern von Setup das grüne. Beide Arten, bestandene wie fehlgeschlagene, stehen im Verifizierungsverlauf auf der Katalogseite, mit Tag oder Branch, Commit und einem Link zum CI-Lauf.

Wie die Verifizierung funktioniert

Ein Lauf verifiziert ein Rezept, wenn der Runner seine Checks meldet und jeder davon besteht, zum Beispiel Images geladen, Services gestartet, Health-Checks gesund und der HTTP-Check über die öffentliche Adresse der App beantwortet. Was Health- und HTTP-Check prüfen, bestimmt dein Rezept (siehe Rezepte).

Zwei Arten von Läufen zählen:

• Läufe von Nutzern. Jeder Test und jede behaltene App, die jemand aus deinem Projekt startet oder aktualisiert und die ihre Checks besteht, ergibt eine Verifizierung. Ein fehlgeschlagener Lauf eines Besuchers zählt nicht gegen dein Rezept.
• Verifizierungsläufe. Setup führt außerdem eigene Verifizierungsjobs aus, zum Beispiel für jeden Katalogeintrag. Diese halten Erfolg und Fehlschlag fest.

Zu jeder Verifizierung speichert Setup die Revision des Rezepts, den Commit der Quelle, Isolation und Architektur des Runners, die einzelnen Checks und die Dauer. Die Katalogseite zeigt die letzte davon unter Verifizierung und jeden Lauf, auch die von deiner CI gemeldeten, im Verifizierungsverlauf.

Wie die Verifizierung wiederholt wird

Einen festen Zeitplan pro Projekt gibt es nicht. Das Badge folgt dem letzten bestandenen Lauf:

• Es bleibt nach einem bestandenen Lauf 30 Tage grün und zeigt danach unverified, bis der nächste besteht.
• Behält jemand eine App aus einem Git-Repository, prüft Setup dein Repository höchstens einmal am Tag auf ein neues Release, oder auf einen neuen Commit, wenn es keine Releases gibt. Hat sich etwas getan, analysiert Setup neu und legt eine Revision an, wenn sich das Rezept geändert hat. Behaltene Apps mit automatischen Updates wechseln auf diese Revision, und ein bestandenes Update zählt als Verifizierung.
• Jeder Klick auf „Run on Setup“ analysiert dein Repository neu. Neue Tests nehmen also deine aktuelle setup.json.

Hinweis. Geplant ist eine GitHub App, die einen Pull Request mit einer verifizierten setup.json öffnet und sie bei jedem Release erneut auf Runnern von Setup prüft. Sie gibt es noch nicht; die GitHub Action oben prüft Releases in deiner CI.