Die Versionsnummer im Build integrieren

Die Nutzer Ihrer Software müssen erkennen können, welche Version sie nutzen. Coroid weist jedem Release eine Versionsnummer und eine Build-Nummer zu, übergibt beides an die Pipeline, die den Build durchführt, und verifiziert anschließend, ob die Umgebung das bereitgestellte Release 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 sie zu. (die Standardeinstellung): Coroid schlägt bei der Vorbereitung eines Releases die nächste Versionsnummer vor. Dabei wird die letzte Zahl der höchsten bisher für das Projekt veröffentlichten Version 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.
• Aus dem Repository auslesen: Coroid liest die Versionsnummer aus, die Ihr Code beim Release-Commit angibt. Dabei wird in VERSION, package.json, app.json (Expo), pubspec.yaml, der Android-Gradle-Datei, Cargo.toml, pyproject.toml sowie dem Xcode-Projekt – oder nur in der von Ihnen angegebenen Datei. Falls die Datei noch eine von einem früheren Release verwendete Versionsnummer enthält, fordert Coroid Sie auf, diese zunächst 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#

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

GitHub lehnt Eingaben ab, die vom Workflow nicht deklariert wurden. 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.jsonzur Verfügung. Dadurch erhält Coroid auch 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"
}

Wenn die Pipeline des Projekts Versionen zuweist, übernimmt die Release-Seite die gemeldete Version. Andernfalls zeigt die Release-Seite die gemeldete Version an und weist darauf hin, wenn sie von der Release-Version abweicht. Für ein auf Coroid gehostetes 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 einer erfolgreichen Bereitstellung öffnet Coroid die URL und sucht nach dem Commit-SHA oder der Version. Ein gemeldeter Commit muss mit dem Release-Commit übereinstimmen; andernfalls muss die Version übereinstimmen. Coroid prüft zehn Minuten lang weiter, bis der Rollout abgeschlossen ist, und zeigt anschließend Verifiziert, Abweichende Version oder Nicht erreichbar unter Was läuft gerade? auf der Release-Seite.

Die URL muss HTTPS und eine öffentliche Adresse verwenden. Coroid folgt keinen Weiterleitungen und liest maximal 64 KB.

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.

Verwandt#

• Release-Einstellungen
• Bereitstellungsereignisse und CI-Einrichtung
• Releases