Skip to content

kempdec/AutoRelease

BranchesTags

Repository files navigation

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.

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

Índice

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". Botão "Create new file" no GitHub

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

Campo "Name your file..." no GitHub

Ficará semelhante a imagem abaixo:

Campo "Name your file..." com o caminho ".github/workflows/main.yml" no GitHub

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

Botão "Commit changes" no GitHub

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

Janela "Commit changes" no GitHub

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.

Opção "--help" na CLI do Auto Release

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

Exemplo: autorelease create --help.

Opção "--help" para o comando "create" na CLI do Auto Release

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

Licença

MIT

About

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

Topics

github release release-automation

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

1 star

Watchers

1 watching

Forks

0 forks
Report repository

Releases 18

Auto Release v1.0.0 (2024-05-09) Latest
May 9, 2024
+ 17 releases

Packages

 
 
 

Languages