Inclua a versão na sua compilação

Os usuários do seu software precisam saber qual versão estão utilizando. O Coroid atribui uma versão e número de compilação para cada lançamento, envia ambos para o pipeline de compilação e verifica posteriormente se o ambiente executa o lançamento que você implantou.

Todas as configurações desta página são definidas por projeto em Lançamentos → Configurações de lançamento → Versionamento.

De onde vem a versão#

Escolha uma fonte por projeto:

• O Coroid define a versão automaticamente. (padrão): o Coroid sugere a próxima versão ao preparar um lançamento. Ele incrementa o último número da versão mais alta já lançada pelo projeto, de modo que 1.4.0 é seguido por 1.4.1. O primeiro lançamento é 0.1.0Digite uma versão diferente sempre que necessário.
• Leia a informação diretamente do repositório: o Coroid lê a versão declarada no seu código no commit de lançamento. Ele procura em VERSION, package.json, app.json (Expo), pubspec.yaml, o arquivo Gradle do Android, Cargo.toml, pyproject.toml e o projeto Xcode, ou apenas no arquivo que você especificar. Se o arquivo ainda contiver uma versão usada em um lançamento anterior, o Coroid pedirá que você a incremente primeiro.
• Meu pipeline define a versão: o seu CI/CD seleciona a versão, por exemplo via semantic-release ou a partir de uma tag, e a reporta junto com a implantação.

Cada lançamento também recebe um número de compilação. Os números de compilação só aumentam e nunca são reutilizados dentro de um projeto, exigência das lojas de aplicativos para iOS. CFBundleVersion e Android versionCode.

O que a compilação recebe#

Quando o Coroid inicia um fluxo de trabalho do GitHub Actions ou um pipeline GitLab CI/CD para um lançamento, ele passa os seguintes valores:

O GitHub rejeita entradas que o fluxo de trabalho não declara. Por isso, o Coroid envia coroid_version, coroid_build_number e coroid_release_name somente para um fluxo de trabalho que os liste. Declare-os como opcionais:

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 }}

O GitLab passa os valores como variáveis, portanto não é necessária nenhuma declaração:

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}"

Um pipeline que roda independentemente pode usar seus próprios valores. Reporte a versão que você implantou, conforme descrito abaixo, para que o lançamento a exiba.

Escreva um manifesto de lançamento#

A abordagem mais simples e compatível com todas as plataformas é criar um pequeno arquivo durante a compilação e lê-lo onde a versão for exibida:

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

Para um aplicativo web ou serviço, disponibilize o arquivo em /version.json. Isso também fornece ao Coroid uma URL para verificação (veja abaixo).

Receitas#

Aplicativos web (Next.js, Vite)#

Os valores necessários para o navegador devem ser definidos quando o pacote for compilado:

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

Exiba process.env.NEXT_PUBLIC_APP_VERSION ou import.meta.env.VITE_APP_VERSION no rodapé ou em uma tela de Sobre, e copie release.json para a pasta pública antes da compilação.

Servidores e APIs#

Leia os valores na inicialização e responda em um endpoint de versão:

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

Imagens do Docker#

Passe os valores como argumentos de compilação e rotule a imagem, para que o container em execução e o registro saibam qual versão está sendo usada:

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#

O Xcode lê a versão exibida na App Store em MARKETING_VERSION e o número de compilação em CURRENT_PROJECT_VERSION:

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

Com o fastlane, use increment_version_number(version_number: ENV["APP_VERSION"]) e increment_build_number(build_number: ENV["APP_BUILD_NUMBER"]).

Android#

Leia os valores em 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 e depois exibe a versão no aplicativo.

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 e React Native#

Leia os valores em 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) },
  },
};

Informe a versão que foi implantada#

Um evento de implantação pode indicar qual versão e build foram implantados. Adicione version e buildNumber ao evento que seu pipeline já envia:

{
  "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"
}

Se o pipeline do projeto atribuir versões, o lançamento usará a versão informada. Caso contrário, a página de lançamento exibirá a versão informada e destacará quando ela divergir do lançamento. Para um projeto hospedado no Coroid, defina repository como o ID do projeto. Eventos de implantação e configuração de CI descreve o restante do evento.

Verifique o que está em execução#

Atribua uma URL de versão a cada ambiente, como https://app.example.com/version.json. Após uma implantação bem-sucedida, o Coroid abre a URL e procura pelo SHA do commit ou pela versão. Um commit informado deve corresponder ao commit do lançamento; caso contrário, a versão deve coincidir. O Coroid continua verificando por dez minutos enquanto o lançamento é concluído e depois exibe Verificado, Versão diferente ou Não acessível em O que está em execução na página de lançamento.

A URL deve usar HTTPS e ser um endereço público. O Coroid não segue redirecionamentos e lê no máximo 64 KB.

Deixe o Coroid configurar tudo#

Configure a marcação de versão na tela de Versão abre um Novo trabalho com uma solicitação redigida para a pilha detectada do projeto. Um agente lê os valores acima durante a compilação, exibe a versão no aplicativo, grava release.json, declara as entradas do fluxo de trabalho e documenta tudo no README. Revise a solicitação e depois prossiga como em qualquer outro trabalho.

Relacionado#

• Configurações de lançamento
• Eventos de implantação e configuração de CI
• Lançamentos