Dokumentation

Die Versionsnummer im Build integrieren

Weisen Sie jedem Release eine Versionsnummer und Build-Nummer zu, übergeben Sie diese an den Build-Prozess und lassen Sie CoRoid prüfen, welche Version in welcher Umgebung läuft.

Die Nutzer Ihrer Software müssen erkennen können, welche Version sie verwenden. CoRoid weist jedem Release eine Versionsnummer und eine Build-Nummer zu, übermittelt beide an die dafür zuständige Pipeline und überprüft anschließend, ob die Umgebung tatsächlich das bereitgestellte Release ausführt.

1. CoRoid benennt es

Release

1.4.1

Build 12

Von CoRoid, aus einer Datei in Ihrem Repository oder aus Ihrer Pipeline.

2. Ihre Pipeline erstellt es

Ihr CI/CD

COROID_VERSION=1.4.1

COROID_BUILD_NUMBER=12

COROID_COMMIT_SHA=3da015d…

Die Werte werden als Variablen oder Workflow-Eingaben übergeben.

3. Die Nutzer sehen es

Über uns

Version 1.4.1 (12)

In der Anwendung angezeigt und in release.json geschrieben.

4. CoRoid bestätigt es

GET /version.json

Verifiziert

Die Pipeline meldete 1.4.1, Build 12.

Nach einer Bereitstellung liest CoRoid die Versions-URL aus.

Die Version reist mit dem Release in Ihren Build, und CoRoid überprüft, was die Umgebung tatsächlich ausführt.

Alle Einstellungen auf dieser Seite werden pro Projekt in festgelegt. Releases → Release-Einstellungen → Versionierung.

Herkunft der Versionsnummer

Wählen Sie pro Projekt eine Quelle aus:

  • CoRoid weist diese zu. (Standardeinstellung): CoRoid schlägt bei der Vorbereitung eines Releases die nächste Versionsnummer vor. Dabei wird die letzte Ziffer der höchsten bisher veröffentlichten Version um eins erhöht, sodass 1.4.0 von 1.4.1gefolgt wird. Das erste Release ist 0.1.0. Geben Sie bei Bedarf eine andere Versionsnummer ein. Ein Deployment, das nicht von CoRoid initiiert wurde – etwa ein manuelles Deployment, das an CoRoid gemeldet wird – erhält ebenfalls die nächste Versionsnummer, sofern die zugehörige Pipeline keine eigene Nummer angibt.
  • Aus dem Repository auslesen: CoRoid liest die vom Code bei dem Release-Commit angegebene Versionsnummer aus. Dabei wird in VERSION, package.json, app.json (Expo), pubspec.yaml, der Android-Gradle-Datei, Cargo.toml, pyproject.toml sowie im Xcode-Projekt nachgesehen – oder nur in der von Ihnen angegebenen Datei. Falls die Datei noch eine für ein früheres Release verwendete Versionsnummer enthält, fordert CoRoid Sie auf, diese zuerst zu erhöhen.
  • Meine Pipeline weist sie zu: Ihr CI/CD bestimmt die Versionsnummer – beispielsweise über semantic-release oder einen Tag – und gibt sie beim Deployment weiter.

Jedes Release erhält außerdem eine Build-Nummer. Build-Nummern werden innerhalb eines Projekts kontinuierlich erhöht und nie wiederverwendet – wie es die App-Stores für iOS CFBundleVersion und Android versionCode.

Was der Build erhält

Wenn CoRoid einen GitHub Actions-Workflow oder eine GitLab CI/CD-Pipeline für ein Release startet, übermittelt es folgende Werte:

GitLab-VariableGitHub-EingabeWert
COROID_VERSIONcoroid_versionDie Release-Versionsnummer
COROID_BUILD_NUMBERcoroid_build_numberDie Build-Nummer
COROID_RELEASE_NAMEcoroid_release_nameDer Release-Name
COROID_COMMIT_SHAcoroid_commit_shaDer vollständige Commit-SHA
COROID_ENVIRONMENTcoroid_environmentDer Umgebungs-Schlüssel
COROID_RELEASE_IDcoroid_release_idDie Release-ID von CoRoid
COROID_ATTEMPT_IDcoroid_attempt_idDer Deployment-Versuch

GitHub lehnt Eingaben ab, die vom Workflow nicht vorgesehen sind. Deshalb sendet CoRoid coroid_version, coroid_build_number und coroid_release_name nur an einen Workflow, der sie auflistet. Deklarieren Sie sie als optional:

on:
  workflow_dispatch:
    inputs:
      coroid_release_id: { required: true }
      coroid_attempt_id: { required: true }
      coroid_commit_sha: { required: true }
      coroid_environment: { required: true }
      coroid_version: { required: false }
      coroid_build_number: { required: false }
      coroid_release_name: { required: false }

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      APP_VERSION: ${{ inputs.coroid_version || '0.0.0-dev' }}
      APP_BUILD_NUMBER: ${{ inputs.coroid_build_number || '0' }}
      APP_COMMIT: ${{ inputs.coroid_commit_sha || github.sha }}

GitLab übermittelt die Werte als Variablen – eine explizite Deklaration ist daher nicht nötig.

deploy:
  script:
    - export APP_VERSION="${COROID_VERSION:-0.0.0-dev}"
    - export APP_BUILD_NUMBER="${COROID_BUILD_NUMBER:-0}"
    - export APP_COMMIT="${COROID_COMMIT_SHA:-$CI_COMMIT_SHA}"

Eine eigenständig laufende Pipeline kann ihre eigenen Werte verwenden. Melden Sie die bereitgestellte Versionsnummer wie unten beschrieben, damit das Release diese anzeigt.

Ein Release-Manifest erstellen

Der einfachste Ansatz, der auf allen Plattformen funktioniert, besteht darin, während des Builds eine kleine Datei zu erstellen und diese überall dort auszulesen, wo die Versionsnummer angezeigt wird:

cat > release.json <<EOF
{
  "version": "$APP_VERSION",
  "buildNumber": "$APP_BUILD_NUMBER",
  "commitSha": "$APP_COMMIT",
  "releaseName": "${COROID_RELEASE_NAME:-}",
  "environment": "${COROID_ENVIRONMENT:-local}"
}
EOF

Für eine Web-Anwendung oder einen Service stellen Sie die Datei unter /version.json. Dadurch erhält CoRoid außerdem eine URL zur Überprüfung (siehe unten).

Beispiele

Web-Anwendungen (Next.js, Vite)

Die für den Browser benötigten Werte müssen zum Zeitpunkt des Bundle-Builds festgelegt werden:

NEXT_PUBLIC_APP_VERSION="$APP_VERSION" NEXT_PUBLIC_APP_COMMIT="$APP_COMMIT" npm run build
VITE_APP_VERSION="$APP_VERSION" npm run build

Zeigen Sie process.env.NEXT_PUBLIC_APP_VERSION oder import.meta.env.VITE_APP_VERSION im Fußbereich oder auf einer Überblicksseite an und kopieren Sie release.json vor dem Build in den öffentlichen Ordner.

Server und APIs

Lesen Sie die Werte beim Start aus und geben Sie sie über einen Versions-Endpunkt zurück:

app.get('/version.json', (_request, response) => {
  response.json({
    version: process.env.APP_VERSION,
    buildNumber: process.env.APP_BUILD_NUMBER,
    commitSha: process.env.APP_COMMIT,
  });
});

Docker-Images

Übergeben Sie die Werte als Build-Argumente und kennzeichnen Sie das Image, damit sowohl der laufende Container als auch das Registry-System die Versionsnummer kennen.

ARG APP_VERSION=0.0.0-dev
ARG APP_COMMIT=unknown
ENV APP_VERSION=$APP_VERSION APP_COMMIT=$APP_COMMIT
LABEL org.opencontainers.image.version=$APP_VERSION \
      org.opencontainers.image.revision=$APP_COMMIT
docker build --build-arg APP_VERSION="$APP_VERSION" --build-arg APP_COMMIT="$APP_COMMIT" .

iOS

Xcode liest die im App Store angezeigte Versionsnummer aus MARKETING_VERSION und die Build-Nummer aus CURRENT_PROJECT_VERSION:

xcodebuild -scheme App -configuration Release archive \
  MARKETING_VERSION="$APP_VERSION" \
  CURRENT_PROJECT_VERSION="$APP_BUILD_NUMBER"

Mit fastlane verwenden Sie increment_version_number(version_number: ENV["APP_VERSION"]) und increment_build_number(build_number: ENV["APP_BUILD_NUMBER"]).

Android

Die Werte in app/build.gradle.kts:

android {
    defaultConfig {
        versionName = System.getenv("APP_VERSION") ?: "0.0.0-dev"
        versionCode = (System.getenv("APP_BUILD_NUMBER") ?: "1").toInt()
    }
}

BuildConfig.VERSION_NAME anschließend wird die Version in der App angezeigt.

Flutter

flutter build appbundle --build-name="$APP_VERSION" --build-number="$APP_BUILD_NUMBER"
flutter build ipa --build-name="$APP_VERSION" --build-number="$APP_BUILD_NUMBER"

Expo und React Native

Die Werte in app.config.js:

export default {
  expo: {
    version: process.env.APP_VERSION ?? '0.0.0-dev',
    ios: { buildNumber: process.env.APP_BUILD_NUMBER ?? '1' },
    android: { versionCode: Number(process.env.APP_BUILD_NUMBER ?? 1) },
  },
};

Die eingesetzte Version melden

Ein Bereitstellungsereignis kann angeben, welche Version und welcher Build eingesetzt wurden. Fügen Sie version und buildNumber dem Ereignis hinzu, das Ihr Pipeline bereits sendet:

{
  "schemaVersion": 1,
  "eventId": "ci:run-812:production:succeeded",
  "providerRunId": "run-812",
  "projectId": "<project-uuid>",
  "environmentKey": "production",
  "repository": "owner/repository",
  "commitSha": "0123456789abcdef0123456789abcdef01234567",
  "status": "succeeded",
  "occurredAt": "2026-09-28T12:00:00Z",
  "version": "1.4.0",
  "buildNumber": "42"
}

Falls die Pipeline des Projekts die Versionsnummern selbst zuweist, übernimmt das Release diese gemeldete Nummer. Andernfalls zeigt die Release-Seite die gemeldete Versionsnummer an und weist darauf hin, falls sie von der tatsächlichen Release-Version abweicht. Bei einem auf CoRoid gehosteten Projekt müssen Sie repository mit der Projekt-ID ausfüllen. Bereitstellungsereignisse und CI-Einrichtung beschreibt den Rest des Ereignisses.

Überprüfen, was gerade läuft

Weisen Sie jedem Umfeld eine Versions-URL zu, zum Beispiel https://app.example.com/version.json. Nach erfolgreichem Deployment öffnet CoRoid die angegebene URL und sucht nach dem Commit-SHA oder der Versionsnummer. Der gemeldete Commit muss mit dem Release-Commit übereinstimmen; andernfalls muss die Versionsnummer passen. CoRoid prüft dies bis zu zehn Minuten lang während des Ausrollens und zeigt anschließend Verifiziert, Abweichende Version oder Nicht erreichbar unter Was läuft gerade? auf der Release-Seite.

Die URL muss das HTTPS-Protokoll nutzen und eine öffentliche Adresse sein. CoRoid folgt keinen Redirects und liest maximal 64 KB aus.

Lassen Sie CoRoid die Einrichtung übernehmen.

Versions-Stempelung einrichten auf dem Bildschirm „Versionierung“ öffnet Neue Aufgaben mit einer für den erkannten Stack des Projekts verfassten Anfrage. Ein Agent liest die oben genannten Werte zur Build-Zeit, zeigt die Version in der App an, schreibt release.json, deklariert die Workflow-Eingaben und dokumentiert dies in der README. Überprüfen Sie die Anfrage und arbeiten Sie anschließend wie gewohnt damit.