Auto Release

Gere automaticamente releases do seu projeto no GitHub usando o Auto Release.

Começando

Use o sumário abaixo para escolher como quer aprender a usar o Auto Release.

• GitHub Actions - Automatize a criação dos seus releases com o CI/CD do GitHub.
• CLI (Interface de Linha de Comando) - Crie os seus releases a partir do seu terminal.

Depois, veja como escrever as suas mensagens de commit para usar todo o potencial do Auto Release clicando aqui.

Índice

• Auto Release
  • Começando
  • Índice
  • GitHub Actions
    • Criando um fluxo de trabalho simples no GitHub Actions
    • Personalizando o fluxo de trabalho
  • CLI (Interface de Linha de Comando)
    • Instalação
  • Escrevendo commits
  • Configurações
    • Arquivo de configuração
    • Variáveis de ambiente
    • Propriedades de configuração
      • CreateComand
      • CreateComand e NoteCommand
      • CreateComand e VersionCommand
  • Autores
  • Licença

GitHub Actions

Para começar a usar o Auto Release no GitHub Actions é muito fácil, siga os passos abaixo e diga adeus a escrever releases manualmente.

Criando um fluxo de trabalho simples no GitHub Actions

Acesse o seu repositório no GitHub e no menu suspenso "Add file", vá em "Create new file".

---

Em "Name your file..." digite o seguinte: .github/workflows/main.yml.

---

Ficará semelhante a imagem abaixo:

---

Copie o código abaixo e cole no corpo do arquivo no GitHub.

# .github/workflows/main.yml

name: Criar Release

on:
  push:
    branches:
      - main

jobs:
  create-release:
    name: Criar Release
    runs-on: ubuntu-latest
    permissions: write-all

    steps:
      - name: Criar Release
        uses: kempdec/autorelease-action@v2
        env:
          AutoRelease_Token: ${{ secrets.GITHUB_TOKEN }} # Este token é fornecido pelo GitHub Actions, você não precisa criar seu próprio token.

---

Clique no botão "Commit changes".

---

Escreva a sua mensagem de commit e clique mais uma vez em "Commit changes".

Pronto! Isso já é o suficiente para que o Auto Release comece a gerar automaticamente os releases do seu repositório no GitHub. Toda vez que um push for feito para o branch main, um release será criado.

Veja como configurar e costumizar o Auto Release para que atenda melhor as suas necessidades e da sua equipe clicando aqui.

Personalizando o fluxo de trabalho

Caso você queira disparar a ação de criação da release manualmente, troque o conteúdo de on: push para on: workflow_dispatch.

# .github/workflows/main.yml

name: Criar Release

on:
  workflow_dispatch:

jobs:
  create-release:
    name: Criar Release
    runs-on: ubuntu-latest
    permissions: write-all

    steps:
      - name: Criar Release
        uses: kempdec/autorelease-action@v2
        env:
          AutoRelease_Token: ${{ secrets.GITHUB_TOKEN }} # Este token é fornecido pelo GitHub Actions, você não precisa criar seu próprio token.

Ou se preferir, o release pode ser criado quando você fizer o push de uma tag de versão para o repositório. Nesse caso troque o conteúdo de on: push: branches para on: push: tags e adicione a variável de ambiente AutoRelease_Version.

# .github/workflows/main.yml

name: Criar Release

on:
  push:
    tags:
      - "v*" # Tags que iniciarem com v, como v1.0.0, v2.3.5-beta.1.

jobs:
  create-release:
    name: Criar Release
    runs-on: ubuntu-latest
    permissions: write-all

    steps:
      - name: Criar Release
        uses: kempdec/autorelease-action@v2
        env:
          AutoRelease_Token: ${{ secrets.GITHUB_TOKEN }} # Este token é fornecido pelo GitHub Actions, você não precisa criar seu próprio token.
          AutoRelease_Version: ${{ github.ref_name }}

CLI (Interface de Linha de Comando)

Instalação

Instale a ferramenta a partir do SDK do .NET.

dotnet tool install -g autorelease

Digite o comando autorelease --help em seu Terminal para que seja impresso a ajuda.

Para imprimir a ajuda de algum comando, informe ele e em seguida a opção --help.

Exemplo: autorelease create --help.

A CLI também funciona com um arquivo de configuração do Auto Release. Nos exemplos acima, o arquivo deveria estar em C:\Users\ceo, que é o caminho em que o terminal se encontra.

Veja como usar um arquivo de configuração clicando aqui.

Escrevendo commits

Conventional Commits

O Auto Release usa o padrão do Conventional Commits (com poucas diferenças) para ler os commits e gerar o release automaticamente.

Ou seja, a mensagem do commit deve ser estruturada da seguinte forma:

Obs.: O Auto Release ainda não oferece suporte a escopos, mas em breve será adicionado o recurso.

<tipo>: <descrição>

[corpo opcional]

[rodapé(s) opcional(is)]

Os tipos feat e fix e o operador ! funcionam como está descrito em Conventional Commits, com as seguintes diferenças:

• Caso a propriedade Types (arquivo) ou types (CLI) seja especificada, o primeiro tipo terá o funcionamento de feat, de incrementar a versão minor e todos os demais tipos incrementarão a versão patch.

• O texto BREAKING CHANGE: não é utilizado como sinalizador para quebra de compatbilidade, somente o operador !, mas você pode usar os 2 em conjunto.

  Exemplo da mensagem de commit:

  fix: Corrigir a criação de artigos.
  
  Corrigido um problema em que quando a data de publicação era inferior a data de criação, o artigo não era criado.
  
  Obs.: Somente de exemplo.
  

  As notas geradas serão semelhantes a abaixo:

  # My Project v1.0.0 (2024-01-01)
  
  # Correções
  
  - Corrigido um problema em que quando a data de publicação era inferior a data de criação, o artigo não era criado.
    
    Obs.: Somente de exemplo.
  

Operadores

Você pode utilizar operadores para que o Auto Release trate as suas mensagens de commit de maneira diferente. Atualmente é possível utilizar somente um operador por vez.

Para utilizar um operador, coloque-o no final do tipo da mensagem de commit e antes do separador : (dois pontos).

Exemplo com o operador ^:

feat^: Essa descrição será ignorada.

Somente esse corpo será adicionado as notas do release.

Os operadores disponíveis são:

Operador	Descrição
!	A mensagem de commit traz uma quebra de compatibilidade e a versão major deve ser incrementada.
#	A mensagem de commit deve ser ignorada e não deve ser adicionada as notas do release.
^	A mensagem de commit deve ter somente o seu corpo adicionado as notas de release, ou seja, a sua descrição deve ser ignorada.

Configurações

Arquivo de configuração

Uma das maneiras de configurar o Auto Release, é adicionando um arquivo com o nome autorelease.config.json na raiz do seu projeto.

Exemplo: Se o seu projeto está em D:/MeuProjeto, é nela que o arquivo deverá ser criado.

Um modelo atualizado com todas as opções do autorelease.config.json pode ser encontrado clicando aqui.

Observações:

• Todas as propriedades de configuração são OPCIONAIS.
• A configuração abaixo é apenas um exemplo e NÃO deve ser usada em seu projeto, a menos que entenda o que está fazendo.
• Caso você esteja utilizando o Auto Release no GitHub Actions, as propriedades NoteCommand e VersionCommand devem ser ignoradas.

// autorelease.config.json

{
  // O token para acesso ao repositório no GitHub.
  "Token": "ghp_1DF8350tVc1Ry0IBuWH3uh8cTRpofs0FY0Iv",
  // O repositório que contém os commits no GitHub.
  "Repo": "kempdec/MyRepository",
  // O branch do repositório no GitHub.
  "Branch": "main",

  // As configurações do subcomando de criação automática de um release.
  "CreateCommand": {
    // A versão do release.
    // No exemplo abaixo, o release seria criado na v1.3.0. O uso dela é recomendado somente de forma dinâmica, como em
    // uma variável de ambiente definida pelo GitHub Actions.
    "Version": "v1.3.0",
    // O nome do projeto.
    // Ele pode ser utilizado em alguns lugares, como parte do título do release.
    "ProjectName": "Meu Repositório",
    // Um sinalizador indicando se o release é um rascunho.
    "Draft": false,
    // Um sinalizador indicando se o release é um pre-release.
    "PreRelease": false,
    // O tipo de saída da criação automática do release.
    // Algumas opções são: Id, UploadUrl e Version.
    "OutputType": "Id",

    // Os tipos das mensagens de commit.
    "Types": [
      "feat=Novidades desta versão",
      "fix=Principais correções desta versão",
      "chore=Notas técnicas"
    ],
    // As substituições do início das mensagens de commit.
    "Replaces": {
      "Adicionar": "Foi adicionado",
      "Adicionar o ": "Foi adicionado o ",
      "Adicionar a ": "Foi adicionada a ",
      "Corrigir": "Corrigido um problema em que"
    },
    // Os inícios das mensagens de commit que serão ignoradas.
    "Ignores": [
      "Refatorar."
    ],

    // A primeira versão do repositório.
    "FirstVersion": "0.1.0",
    // O prefixo das versões do repositório.
    "VersionPrefix": "v"
  },

  // As configurações do subcomando de geração automática das notas do release.
  "NoteCommand": {
    // Os tipos das mensagens de commit.
    "Types": [
      "feat=Novidades desta versão",
      "fix=Principais correções desta versão"
    ],
    // As substituições do início das mensagens de commit.
    "Replaces": null,
    // Os inícios das mensagens de commit que serão ignoradas.
    "Ignores": [
      "Refatorar."
    ]
  },

  // As configurações do subcomando de geração automática da versão do release.
  "VersionCommand": {
    // A primeira versão do repositório.
    "FirstVersion": "0.1.0",
    // O prefixo das versões do repositório.
    "VersionPrefix": null
  }
}

Variáveis de ambiente

Você pode definir variáveis de ambiente com o prefixo AutoRelease_ para configurar o Auto Release.

Para configurar o repositório, por exemplo, o nome da variável de ambiente seria AutoRelease_Repo.

// Essa variável de ambiente:
AutoRelease_Repo="kempdec/MyRepository"

// É equivalente a essa propriedade no arquivo de configuração:
{
  "Repo": "kempdec/MyRepository"
}

Use __ (dois _) no nome da variável de ambiente para definir uma propriedade de um objeto.

// Essa variável de ambiente:
AutoRelease_CreateCommand__Types="feat=\"Novidades\" fix=\"Correções\" chore=\"Notas técnicas\""

// É equivalente a essa propriedade no arquivo de configuração:
{
  "CreateCommand": {
    "Types": [
        "types=Novidades",
        "fix=Correções",
        "chore=Notas técnicas"
    ]
  }
}

Propriedades de configuração

Arquivo	CLI	Tipo	Padrão	Sumário
Token	token	string	null!	[OBRIGATÓRIA NO CLI] O token para acesso ao repositório no GitHub. Exemplo: ghp_1DF8350tVc1Ry0IBuWH3uh8cTRpofs0FY0Iv.
Repo	repo	string	null!	[OBRIGATÓRIA NO CLI] O repositório que contém os commits no GitHub. Exemplo: kempdec/MyRepository.
Branch	branch	string?	null	O branch do repositório no GitHub. Exemplo: main.

CreateComand

Arquivo	CLI	Tipo	Padrão	Sumário
Version	version	string?	null	A versão do release (SemVer 2.0). Quando especificada, a versão do release não será gerada automaticamente. O uso dessa propriedade é recomendado somente de forma dinâmica, como em uma variável de ambiente definida através do GitHub Actions. Exemplo: 1.3.0.
ProjectName	project-name	string?	null	O nome do projeto. Ele pode ser utilizado em alguns lugares, como parte do título do release. Exemplo: Meu Repositório.
Draft	draft	boolean	false	Um sinalizador indicando se o release é um rascunho. Exemplo: false.
PreRelease	pre-release	boolean	false	Um sinalizador indicando se o release é um pre-release. Exemplo: false.
OutputType	output-type	string	Id	O tipo de saída da criação automática do release. Os valores aceitos são: Id, UploadUrl ou Version

NoteCommand

Arquivo	CLI	Tipo	Padrão	Sumário
Version	version	string?	null	A versão do release (SemVer 2.0). Quando especificado, as notas do release serão geradas com base nas mensagens de commit desde a versão anterior da versão especificada. Exemplo: 1.3.0.

CreateComand e NoteCommand

Arquivo	CLI	Tipo	Padrão	Sumário
Version	version	string?	null	A versão do release (SemVer 2.0). Quando especificada, a versão do release não será gerada automaticamente. O uso dessa propriedade é recomendado somente de forma dinâmica, como em uma variável de ambiente definida através do GitHub Actions. Exemplo: 1.3.0.
Types	types	string[]	null	Os tipos das mensagens de commit. Exemplo arquivo: ["feat=Novidades", "fix=Correções", "chore=Notas técnicas"]. Exemplo CLI: feat="Novidades" fix="Correções" chore="Notas técnicas". A ordem dos tipos definirá também a ordem que são escritos nas notas do release. Neste exemplo, as Novidades serão listadas primeiro.
Replaces	replaces	object	null	As substituições do início das mensagens de commit. Exemplo arquivo: {"Adicionar a ": "Foi adicionada a ", "Corrigir": "Foi corrigido"}. Exemplo CLI: "Adicionar a "="Foi adicionada a " "Corrigir"="Foi corrigido". Usando a seguinte mensagem de commit como exemplo: feat: Adicionar a página de cadastro de usuários. Na geração das notas do release, ela seria substituída por: Foi adicionada a página de cadastro de usuários.
Ignores	ignores	string[]	null	Os inícios das mensagens de commit que serão ignoradas. Exemplo arquivo: ["Refatorar.", "Atualizar a versão"]. Exemplo CLI: "Refatorar" "Atualizar a versão". Usando a seguinte mensagem de commit como exemplo: chore: Atualizar a versão do pacote. Ela seria ignorada, por começar com Atualizar a versão. Você também pode ignorar uma mensagem de commit usando o operador #. No exemplo abaixo, a mensagem de commit será ignorada, independente de estar ou não em Ignores: chore#: Atualizar a versão do pacote.
ShowAuthor	show-author	boolean	false	Um sinalizador indicando se o autor deve ser exibido no final das mensagens de commit. Exemplo: false.

CreateComand e VersionCommand

Arquivo	CLI	Tipo	Padrão	Sumário
FirstVersion	first-version	string	1.0.0	A primeira versão do repositório (SemVer 2.0). Essa propriedade é utilizada na criação do primeiro release. Exemplo: 0.1.0.
VersionPrefix	version-prefix	string	v	O prefixo das versões do repositório. Exemplo: v.

Autores

• KempDec - Mantedora do projeto de código aberto.
• Vinícius Lima - Desenvolvedor .NET C#.

Licença

MIT