Guia: Enviar Dados de Deploy Usando a API do DevStats

O DevStats fornece uma API para enviar dados sobre deploys. Este tutorial foca em enviar dados de deploy via API do DevStats para permitir rastreamento de deploy mais preciso para a métrica de Deploy e o snapshot de DORA metrics.

Dica: Integre a API de Deploys do DevStats com seu pipeline de deploy CI/CD para enviar métricas de deploy diretamente ao DevStats.

☑️ Pré-requisitos

Antes de começar, certifique-se de ter:

• Um token de API para autenticar requisições. Gerencie seu token em Settings → Deploys → Send via the API.
• Um repositório existente em um workspace do DevStats do qual você participa. Proprietários ou administradores do workspace podem alterar a fonte de deploy.
• Uma ferramenta como Postman (UI) ou cURL (CLI) para enviar requisições de API.

Passo 1: Criar um Novo Deploy

Para criar um novo deploy, envie uma requisição POST com os seguintes detalhes:

Campos

• Repository (repository, obrigatório): O nome completo de um repositório existente no seu workspace, no formato organization/repository.
• Deployed At (deployed_at, obrigatório): A data do deploy no formato ISO 8601 (ex: 2024-07-20T15:30:00+00:00).
• Commit SHA (commit_sha, opcional): O SHA do commit do deploy, com 7–40 caracteres hexadecimais.

Configuração da Requisição

• Endpoint: https://service.devstats.com/api/v1/deploys
• Headers: Accept: application/json e Content-Type: application/json
• Authorization: Bearer SEU_TOKEN_DE_API (Substitua este valor pelo seu token de API)

Este é um exemplo de corpo de requisição POST. Substitua organization/repository pelo nome completo do seu repositório:

{
    "repository": "organization/repository",
    "deployed_at": "2024-12-09T15:30:00-03:00"
}

Resposta de Sucesso

Uma requisição bem-sucedida retorna 201 Created, com data.type igual a deploy. O UUID, a data do deploy e o SHA opcional do commit são retornados em data.attributes.uuid, data.attributes.deployed_at e data.attributes.commit_sha.

Exemplo no Postman usando dados locais de demonstração. A variável base_url aponta para a URL da API.

Passo 2: Selecionar a API como Fonte de Deploy

Para usar os deploys enviados pela API nas métricas de Deploy e DORA:

1. Como proprietário ou administrador do workspace, abra Settings → Deploys.
2. Selecione Send via the API em Deploy Settings.

3. Clique em Save Settings.

Essa ação seleciona a fonte de deploy do workspace. A página também oferece gerenciamento do token da API, exemplos de cURL, GitHub Actions e GitLab CI e os campos aceitos no payload. Consulte Configurações de Deploys para mais detalhes.

Passo 3: Verificar o Deploy

Volte ao report Deploy ou DORA e selecione um período que inclua a data informada em deployed_at. Confira se os filtros de repositório e squad incluem o repositório usado na requisição.

O processamento do deploy e a atualização do cache dos reports ocorrem em segundo plano. A resposta 201 Created confirma a criação; aguarde o processamento antes de conferir as métricas. Se o deploy não aparecer, confirme que Send via the API foi salvo como fonte de deploy.