Links in Release Notes kürzen und jeden Download verfolgen

Release Notes werden weiter verbreitet als fast alles, was ein Engineering-Team schreibt. Niemand misst sie. Sie fügen einen Download-Link in den Release-Text ein, jemand kopiert ihn in Slack, das Marketing setzt ihn in den Newsletter, ein Maintainer veröffentlicht ihn auf X. Sechs Monate später zeigen die Hälfte dieser Links auf eine Datei, die nicht mehr existiert, und keiner davon hat Ihnen etwas verraten. Um Links in Release Notes richtig zu kürzen, brauchen Sie drei Dinge: einen stabilen Kurzlink für "latest", den Sie bei jedem Release neu ausrichten, einen separaten markierten Link pro Kanal und Version sowie einen Workflow beim Ereignis release: published, der beides erstellt, damit niemand daran denken muss.

Das ist die ganze Antwort. Im Rest dieses Beitrags geht es darum, wie Sie das sauber verdrahten und was die Klickdaten anschließend aussagen können und was nicht.

Ich habe viele Projekte dabei beobachtet, wie sie GitHub-Links in Release Notes von Hand verwalten, und das Fehlermuster ist immer gleich: Jemand verlinkt ein versioniertes Asset, der Link wird in einem Forenbeitrag oder einer Stack-Overflow-Antwort zitiert, und das nächste Release lässt ihn unbemerkt ins Leere laufen. Wenn Sie Links bereits als Code verwalten, passt der folgende Ansatz neben Kurzlinks mit Terraform verwalten, mit dem Unterschied, dass sich Release-Links nach einem Zeitplan ändern, den Sie nicht von Hand steuern.

Warum Links in Release Notes veralten und ihre Attribution verlieren

Hier verbergen sich zwei getrennte Probleme. Sie brauchen unterschiedliche Lösungen.

Das erste ist Link-Verfall. GitHub stellt stabile URLs für die Release-Seite (/releases/latest) und für Dateien über /releases/latest/download/asset-name bereit. Die zweite Variante funktioniert aber nur, wenn das Asset laut GitHubs eigener Dokumentation zum Verlinken auf Releases in allen Releases denselben Namen behält. Die meisten Build-Pipelines schreiben die Version in den Dateinamen, sodass aus app-2.3.0.dmg app-2.4.0.dmg wird und die letzte Woche noch funktionierende Download-URL für "latest" nun einen 404 zurückgibt. Auch Dokumentationslinks verfallen, wenn eine Dokumentationsseite neu organisiert wird. Die übergreifenden Muster finden Sie in unserer Strategie zur Vermeidung veralteter Links; bei Release Notes schlägt das Problem nur am stärksten zu, weil die Links am weitesten wandern.

Das zweite Problem ist Attribution, und es ist leiser. GitHubs REST API meldet für jedes Release-Asset zwar einen download_count, was mehr ist, als die meisten vermuten. Was sie nicht meldet, ist die Herkunft des Downloads. Ein Anstieg um 4.000 Downloads am Tag nach dem Release könnte vom Newsletter, einem Hacker-News-Thread oder von der CI eines einzelnen Enterprise-Kunden stammen, die das Binärprogramm in einer Schleife abruft. In Slack und Direktnachrichten eingefügte Links entfernen den Referrer vollständig. Das ist das Attributionsproblem von Dark Social im Kleinen.

Ein stabiler Latest-Link, den Sie pro Release neu ausrichten

Erstellen Sie einen Kurzlink, etwa get.example.dev/latest, und behandeln Sie ihn als Zeiger. Jede Dokumentationsseite, jedes README-Badge und jedes Installationsskript verwendet ihn. Bei jedem stabilen Release aktualisieren Sie sein Ziel. Der Slug ändert sich nie, sodass nichts kaputtgeht, was ihn zitiert hat.

In Elido ist dieser Zeiger ein gewöhnlicher Link. Sie erstellen ihn einmal mit POST /v1/workspaces/{workspace_id}/links und übergeben die domain_id Ihrer gebrandeten Domain, den slug und die destination_url. Speichern Sie die id aus der 201-Antwort. Das Neuausrichten erfolgt mit einem PATCH /v1/workspaces/{workspace_id}/links/{link_id} und einer neuen destination_url, sonst nichts; Slug, Tags und Klickverlauf bleiben erhalten.

Belassen Sie es bei einer 302. Elido-Links verwenden standardmäßig 302, und es gibt einen guten Grund, das für diesen Link nicht zu ändern: Eine 301 ist laut RFC 9110 standardmäßig cachebar, sodass ein Browser, der die Weiterleitung vom letzten Monat gesehen hat, möglicherweise nie wieder nachfragt. Ein Zeiger, an den sich Browser für immer erinnern, ist kein Zeiger mehr. Mehr dazu in 301 vs. 302-Weiterleitungen für Kurzlinks.

Entscheiden Sie eine Sache im Voraus. Soll der Latest-Link auf die Datei oder auf die Release-Seite zeigen? Ich würde bei mehr als einem Plattform-Build auf die Release-Seite zeigen und Latest-Links pro Plattform (/latest-mac, /latest-linux) nur beibehalten, wenn Ihre Installationsdokumentation wirklich eine direkte Datei braucht. Weniger bewegliche Zeiger bedeuten weniger Möglichkeiten, beim Neuausrichten einen Fehler zu machen.

Markierung pro Release für Links in GitHub Release Notes

Der Latest-Link beantwortet die Frage "Funktioniert der Link noch?" Er kann nicht beantworten, "welcher Kanal funktioniert hat", weil alle auf denselben Slug klicken. Deshalb erhält jedes Release eine eigene kleine Gruppe von Links, einen pro Kanal, die zum Veröffentlichungszeitpunkt erstellt werden.

Hier lassen die meisten UTM-Anleitungen einen wichtigen Punkt aus. utm_source=slack an eine URL auf github.com anzuhängen, bringt nichts, weil Sie GitHubs Analytics nie sehen werden. UTMs lohnen sich nur, wenn das Ziel eine von Ihnen gemessene Website ist, etwa Ihre Dokumentation oder Ihre eigene Download-Seite. Wenn das Ziel GitHub ist, liefert der separate Kurzlink pro Kanal die Attribution: Der Klick wird bei der Weiterleitung gezählt, bevor GitHub ihn überhaupt sieht.

Markieren Sie jeden Link pro Release mit der Version und dem Kanal (["release", "v2.4.0", "slack"]), denn über Tags rufen Sie die Gruppe später wieder ab: GET .../links?tags=v2.4.0 listet alles für ein Release auf. Halten Sie alle UTM-Werte schlicht und über Releases hinweg identisch. Der Leitfaden zu UTM-Namenskonventionen enthält die Regeln, die ich übernehmen würde.

Links beim Ereignis "Release veröffentlicht" erstellen

Ein verwandter Leitfaden behandelt die allgemeine Erstellung von CI-Links, daher bleibt dieser Abschnitt bei den Release-spezifischen Teilen. Der Trigger ist release mit dem Aktivitätstyp published. Laut GitHubs Liste der Workflow-Ereignisse wird published sowohl für stabile Releases als auch für Pre-Releases ausgelöst, einschließlich aus einem Entwurf veröffentlichter Pre-Releases. Genau deshalb prüft der folgende Neuausrichtungsschritt das prerelease-Flag.

name: release-links
on:
  release:
    types: [published]

jobs:
  links:
    runs-on: ubuntu-latest
    env:
      API: https://api.elido.app/v1/workspaces/${{ vars.ELIDO_WORKSPACE_ID }}
      DOMAIN_ID: ${{ vars.ELIDO_DOMAIN_ID }}
      TAG: ${{ github.event.release.tag_name }}
      PAGE: ${{ github.event.release.html_url }}
      ELIDO_TOKEN: ${{ secrets.ELIDO_TOKEN }}
    steps:
      - name: Create one link per channel
        run: |
          v=$(echo "$TAG" | tr '.' '-')
          for ch in slack social news; do
            body=$(jq -n --argjson d "$DOMAIN_ID" --arg s "$v-$ch" \
              --arg u "$PAGE" --arg t "$TAG" --arg c "$ch" \
              '{domain_id:$d, slug:$s, destination_url:$u, tags:["release",$t,$c]}')
            code=$(curl -s -o /dev/null -w '%{http_code}' -X POST "$API/links" \
              -H "Authorization: Bearer $ELIDO_TOKEN" \
              -H "Content-Type: application/json" -d "$body")
            case "$code" in 201|409) ;; *) echo "create $ch failed: $code"; exit 1;; esac
            echo "- $ch: https://get.example.dev/$v-$ch" >> "$GITHUB_STEP_SUMMARY"
          done

      - name: Repoint the latest link
        if: ${{ !github.event.release.prerelease }}
        run: |
          curl -sf -X PATCH "$API/links/${{ vars.ELIDO_LATEST_LINK_ID }}" \
            -H "Authorization: Bearer $ELIDO_TOKEN" \
            -H "Content-Type: application/json" \
            -d "$(jq -n --arg u "$PAGE" '{destination_url:$u}')"

Die Job-Zusammenfassung liefert der Person, die die Ankündigung veröffentlicht, eine fertige Linkliste. Ein 409 bei einer erneuten Ausführung bedeutet, dass der Slug bereits existiert, sodass ein wiederholter Workflow weder fehlschlägt noch etwas dupliziert. Der Newsletter-Link würde mit UTMs im Ziel auf Ihre Dokumentation zeigen; hier habe ich ihn auf der Release-Seite belassen, um das Beispiel kurz zu halten.

Drei Fallstricke, die mich einen Nachmittag gekostet haben

Der erste ist lautlos. Wenn Ihre Release-Pipeline das Release mit dem standardmäßigen GITHUB_TOKEN veröffentlicht, läuft dieser Workflow nie, weil mit GITHUB_TOKEN erstellte Ereignisse keine neuen Workflow-Läufe auslösen. Kein Fehler, kein übersprungener Job, nichts. Veröffentlichen Sie stattdessen mit einem GitHub-App-Token.

Zweitens: Punkte. Ich wandle v2.4.0 für den Slug in v2-4-0 um, weil Versionszeichenfolgen mit Punkten in Chat-Vorschauen wie Dateiendungen aussehen und manche Clients sie auf ungewöhnliche Weise automatisch verlinken.

Drittens: Lassen Sie den Workflow den Release-Text nicht bearbeiten, sofern es nicht nötig ist. Es funktioniert (gh release edit --notes-file), aber der Text, den ein Mensch gerade freigegeben hat, wird neu geschrieben, und es werden edited-Ereignisse ausgelöst, auf die andere Automatisierungen reagieren können. Die Schrittzusammenfassung ist weniger raffiniert und deutlich sicherer. Wiederholungen haben ihren eigenen Beitrag: API-Ratenlimits und Idempotenz.

Wenn Sie Release-Links weiterhin von Hand einfügen, dauert die Einrichtung des obigen Workflows etwa zwanzig Minuten. Starten Sie einen kostenlosen Elido-Workspace, richten Sie eine gebrandete Domain darauf und lassen Sie das nächste Tag seine eigenen Links erstellen.

Klicks auf Release Notes nach Kanal verfolgen

Nach zwei oder drei Releases beginnt die Datenlage Fragen zu beantworten, die GitHubs Zähler nicht beantworten kann.

Der Vergleich pro Kanal ist der einfache Teil. Rufen Sie die mit einer Version markierten Links ab und lesen Sie anschließend die nach link_id eingegrenzte Klickzusammenfassung jedes Links. Wenn v2-4-0-news bei drei Releases hintereinander v2-4-0-social im Verhältnis fünf zu eins übertrifft, wissen Sie, wo Ihre Nutzer tatsächlich sind, und das ist selten der Ort, den das Team vermutet hat. Die Ankündigung mit den meisten Likes ist oft nicht diejenige, die Personen zum Download führt. Rechnen Sie daher mit Widerstand, wenn Sie die Zahlen zum ersten Mal zeigen, und warten Sie das dritte Release in Folge ab, bevor jemand den Launch-Plan darauf abstellt.

Der Latest-Link hat einen weniger offensichtlichen Kniff. Jeder Klick speichert das Ziel, zu dem er in diesem Moment aufgelöst wurde. Dadurch teilt die nach Ziel aufgeschlüsselte Analytics, eingegrenzt auf den Latest-Link, seinen Traffic nach Version auf. Nach dem Neuausrichten können Sie beobachten, wie der Anteil des alten Ziels zurückgeht und wie lange Nachzügler noch über zwischengespeicherte Seiten und alte Lesezeichen eintreffen. Das ist Ihre echte Upgrade-Kurve, gemessen am oberen Ende des Funnels.

Zwei ehrliche Grenzen. Klicks sind keine Downloads: Jemand kann zur Release-Seite klicken und sie wieder verlassen, und GitHubs download_count bleibt die Quelle der Wahrheit für abgeschlossene Abrufe. Außerdem klicken Bots auf Release-Links, insbesondere Link-Vorschau-Abrufe in Chat-Apps. Lesen Sie daher Trends über mehrere Releases hinweg, statt einem einzelnen Tag zu vertrauen. Die Analytics-Funktionsseite listet auf, welche Aufschlüsselungen in jedem Tarif verfügbar sind.

Alte Release-Links aktiv halten

Links pro Release ändern sich nie. v2-3-0-slack zeigt im März auf den Tag v2.3.0 und in fünf Jahren noch immer dorthin, was jemand erwartet, der einen alten Forenbeitrag liest. Nur der Latest-Link ändert sich, und auch das nur bei stabilen Releases.

Der einzige Fall, in dem Sie einen alten Link anfassen sollten, ist ein zurückgezogenes Release. Wenn v2.4.0 mit einem Fehler auf den Markt kommt, der Datenverlust verursacht, löschen Sie seine Links nicht. Richten Sie jeden v2-4-0-*-Link mit demselben PATCH-Aufruf auf v2.4.1 neu aus und fügen Sie dem Release-Text eine kurze Notiz hinzu. Durch das Löschen erhalten Personen, die den Link gespeichert haben, genau in dem Moment eine Sackgasse, in dem sie den Fix am dringendsten brauchen. Eine neuere Version ist immer besser als ein 404.

Für Projekte, die alte Release-Links außerdem in READMEs, Installationsskripten und Metadaten von Paketmanagern aufbewahren, zeigt der entwicklerorientierte Leitfaden zu URL-Shortenern, wo Kurzlinks sich noch lohnen. Die vollständige REST-Oberfläche finden Sie auf der Seite zu API und SDKs.

Lesen Sie den Cornerstone-Beitrag → Ihre Kurzlinks mit Terraform verwalten

Verwandte Beiträge im Blog

• Strategie zur Vermeidung veralteter Links - der umfassendere Leitfaden für Links, die die Seite überdauern müssen, auf die sie zeigen.
• Schnelleinführung in die URL-Shortener-API - Authentifizierung, SDKs und der im Workflow verwendete Erstellungsaufruf.
• URL-Shortener-CLI - dieselben Vorgänge vom Terminal aus, für einzelne Releases.
• Slack-Bot zum Kürzen von URLs - Links dort kürzen, wo die Release-Ankündigung tatsächlich ankommt.
• 301 vs. 302-Weiterleitungen - warum ein neu ausrichtbarer Link temporär bleiben muss.
• Kurzlinks aus GitHub Actions - der allgemeine Erstellungs- oder Aktualisierungsschritt für jeden Workflow.