Publicar pacotes Java com Maven

Você pode usar o Maven para publicar pacotes Java para um registro como parte do seu fluxo de trabalho de integração contínua (CI).

Neste artigo

Note

No momento, não há suporte para executores hospedados no GitHub no GitHub Enterprise Server. Você pode ver mais informações sobre o suporte futuro planejado no GitHub public roadmap.

Introdução

Este guia mostra como criar um fluxo de trabalho que publica pacotes Java no GitHub Packages e no Maven Central Repository. Com um único fluxo de trabalho, você pode publicar pacotes em um único repositório ou em vários repositórios.

Pré-requisitos

Recomendamos que você tenha um entendimento básico dos arquivos de fluxo de trabalho e das opções de configuração. Para saber mais, confira Escrevendo fluxos de trabalho.

Para saber mais sobre como criar um fluxo de trabalho de CI para seu projeto Java com Maven, confira Criar e testar o Java com o Maven.

Você também pode achar útil ter um entendimento básico do seguinte:

Sobre a configuração do pacote

Os campos groupId e artifactId do arquivo pom.xml criam um identificador exclusivo para o pacote que os registros usam para vincular seu pacote a um registro. Para obter mais informações, confira Guia para upload de artefatos no Central Repository na documentação do Apache Maven.

O arquivo pom.xml também contém a configuração dos repositórios de gerenciamento de distribuição nos quais o Maven implantará os pacotes. Cada repositório deve ter um nome e uma URL de implementação. A autenticação para esses repositórios pode ser configurada no arquivo .m2/settings.xml no diretório inicial do usuário que executa o Maven.

Use a ação setup-java para configurar o repositório de implantação, bem como a autenticação para esse repositório. Para obter mais informações, confira setup-java.

Publicar pacotes no Repositório Central do Maven

Cada vez que você criar uma nova versão, você poderá acionar um fluxo de trabalho para publicar o seu pacote. O fluxo de trabalho no exemplo abaixo é executado quando o evento release é disparado com o tipo created. O fluxo de trabalho publica o pacote no Repositório Central Maven se o teste de CI for aprovado. Para saber mais sobre o evento release, confira Eventos que disparam fluxos de trabalho.

Neste fluxo de trabalho, você pode usar a ação setup-java. Essa ação instala a versão fornecida do JDK no PATH, mas também configura um settings.xml do Maven para pacotes de publicação. Por padrão, o arquivo de configurações será definido como GitHub Packages. No entanto, ele pode ser configurado para implementar outro registro de pacote, como, por exemplo, o Repositório Central do Maven. Se você já tiver um repositório de gerenciamento de distribuição configurado no pom.xml, especifique essa id durante a invocação da ação setup-java.

Por exemplo, se você estiver fazendo a implantação no Maven Central Repository por meio do projeto de hospedagem do OSSRH, o pom.xml poderá especificar um repositório de gerenciamento de distribuição com a id igual a ossrh.

XML
<project ...>
  ...
  <distributionManagement>
    <repository>
      <id>ossrh</id>
      <name>Central Repository OSSRH</name>
      <url>https://oss.sonatype.org/service/local/staging/deploy/maven2/</url>
    </repository>
  </distributionManagement>
</project>

Com essa configuração, você pode criar um fluxo de trabalho que publica seu pacote no Maven Central Repository especificando o gerenciamento do repositório id para a ação setup-java. Você também deverá fornecer variáveis de ambiente que contenham o nome de usuário e senha para fazer a autenticação no repositório.

Na etapa de implementação, você deverá definir as variáveis de ambiente para o nome de usuário com o qual deseja fazer a autenticação no repositório e para um segredo que você configurou com a senha ou token para autenticação. Para saber mais, confira Usar segredos em ações do GitHub.

YAML
name: Publish package to the Maven Central Repository
on:
  release:
    types: [created]
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Maven Central Repository
        uses: actions/setup-java@v4
        with:
          java-version: '11'
          distribution: 'temurin'
          server-id: ossrh
          server-username: MAVEN_USERNAME
          server-password: MAVEN_PASSWORD
      - name: Publish package
        run: mvn --batch-mode deploy
        env:
          MAVEN_USERNAME: ${{ secrets.OSSRH_USERNAME }}
          MAVEN_PASSWORD: ${{ secrets.OSSRH_TOKEN }}

Este fluxo de trabalho realiza as etapas a seguir:

  1. Verifica uma cópia do repositório do projeto.

  2. Configura o JDK do Java e o arquivo settings.xml do Maven para adicionar a autenticação ao repositório ossrh usando as variáveis de ambiente MAVEN_USERNAME e MAVEN_PASSWORD.

  3. Executa o comando mvn --batch-mode deploy a ser publicado no repositório ossrh. A variável de ambiente MAVEN_USERNAME será definida com o conteúdo do segredo OSSRH_USERNAME, e a variável de ambiente MAVEN_PASSWORD será definida com o conteúdo do segredo OSSRH_TOKEN.

    Para saber mais sobre como usar segredos em seu fluxo de trabalho, confira Usar segredos em ações do GitHub.

Publicar pacotes em GitHub Packages

Cada vez que você criar uma nova versão, você poderá acionar um fluxo de trabalho para publicar o seu pacote. O fluxo de trabalho no exemplo abaixo é executado quando o evento release é disparado com o tipo created. O fluxo de trabalho publica o pacote em GitHub Packages se o teste de CI for aprovado. Para saber mais sobre o evento release, confira Eventos que disparam fluxos de trabalho.

Neste fluxo de trabalho, você pode usar a ação setup-java. Essa ação instala a versão fornecida do JDK no PATH e configura um settings.xml do Maven para publicar o pacote no GitHub Packages. O settings.xml gerado define a autenticação de um servidor com a id github, usando a variável de ambiente GITHUB_ACTOR como o nome de usuário e a variável de ambiente GITHUB_TOKEN como a senha. A variável de ambiente GITHUB_TOKEN recebe o valor do segredo especial GITHUB_TOKEN.

O segredo GITHUB_TOKEN é definido como um token de acesso para o repositório sempre que um trabalho em um fluxo de trabalho é iniciado. Você deve definir as permissões desse token de acesso no arquivo de fluxo de trabalho para permitir acesso de leitura à permissão contents e acesso de gravação à permissão packages. Para obter mais informações, confira "Autenticação automática de token".

Para um projeto baseado no Maven, você pode usar essas configurações criando um repositório de distribuição no arquivo pom.xml com uma id igual a github que aponta para o ponto de extremidade do GitHub Packages.

Por exemplo, se o nome da sua organização for "octocat" e o nome do repositório for "hello-world", a configuração do GitHub Packages no pom.xml será semelhante ao exemplo abaixo.

XML
<project ...>
  ...
  <distributionManagement>
    <repository>
      <id>github</id>
      <name>GitHub Packages</name>
      <url>https://maven.pkg.github.com/octocat/hello-world</url>
    </repository>
  </distributionManagement>
</project>

Com essa configuração, você pode criar um fluxo de trabalho que publica seu pacote no GitHub Packages usando o settings.xml gerado automaticamente.

YAML
name: Publish package to GitHub Packages
on:
  release:
    types: [created]
jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          java-version: '11'
          distribution: 'temurin'
      - name: Publish package
        run: mvn --batch-mode deploy
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Este fluxo de trabalho realiza as etapas a seguir:

  1. Verifica uma cópia do repositório do projeto.

  2. Configura o JDK do Java e configura automaticamente o arquivo settings.xml do Maven para adicionar autenticação ao repositório github do Maven a fim de usar a variável de ambiente GITHUB_TOKEN.

  3. Executa o comando mvn --batch-mode deploy para publicação no GitHub Packages. A variável de ambiente GITHUB_TOKEN será definida com o conteúdo do segredo GITHUB_TOKEN. A chave permissions especifica o acesso concedido ao GITHUB_TOKEN.

    Para saber mais sobre como usar segredos em seu fluxo de trabalho, confira Usar segredos em ações do GitHub.

Publicar imagens no Repositório Central do Maven e em GitHub Packages

Você pode publicar seus pacotes no Maven Central Repository e no GitHub Packages usando a ação setup-java para cada registro.

Verifique se o arquivo pom.xml inclui um repositório de gerenciamento de distribuição para seu repositório do GitHub e o provedor do Maven Central Repository. Por exemplo, se você fizer a implantação no Central Repository por meio do projeto de hospedagem do OSSRH, o ideal será especificá-lo em um repositório de gerenciamento de distribuição com a id definida como ossrh e especificar o GitHub Packages em um repositório de gerenciamento de distribuição com a id definida com github.

YAML
name: Publish package to the Maven Central Repository and GitHub Packages
on:
  release:
    types: [created]
jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - name: Set up Java for publishing to Maven Central Repository
        uses: actions/setup-java@v4
        with:
          java-version: '11'
          distribution: 'temurin'
          server-id: ossrh
          server-username: MAVEN_USERNAME
          server-password: MAVEN_PASSWORD
      - name: Publish to the Maven Central Repository
        run: mvn --batch-mode deploy
        env:
          MAVEN_USERNAME: ${{ secrets.OSSRH_USERNAME }}
          MAVEN_PASSWORD: ${{ secrets.OSSRH_TOKEN }}
      - name: Set up Java for publishing to GitHub Packages
        uses: actions/setup-java@v4
        with:
          java-version: '11'
          distribution: 'temurin'
      - name: Publish to GitHub Packages
        run: mvn --batch-mode deploy
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Esse fluxo de trabalho chama a ação setup-java duas vezes. Sempre que a ação setup-java for executada, ela substituirá o arquivo settings.xml do Maven para publicação de pacotes. Para autenticação no repositório, o arquivo settings.xml referencia o repositório de gerenciamento de distribuição id, bem como o nome de usuário e a senha.

Este fluxo de trabalho realiza as etapas a seguir:

  1. Verifica uma cópia do repositório do projeto.

  2. Chama setup-java pela primeira vez. Isso configura o arquivo settings.xml do Maven para o repositório ossrh e define as opções de autenticação para variáveis de ambiente definidas na próxima etapa.

  3. Executa o comando mvn --batch-mode deploy a ser publicado no repositório ossrh. A variável de ambiente MAVEN_USERNAME será definida com o conteúdo do segredo OSSRH_USERNAME, e a variável de ambiente MAVEN_PASSWORD será definida com o conteúdo do segredo OSSRH_TOKEN.

  4. Chama setup-java pela segunda vez. Isso configura automaticamente o arquivo settings.xml do Maven para o GitHub Packages.

  5. Executa o comando mvn --batch-mode deploy para publicação no GitHub Packages. A variável de ambiente GITHUB_TOKEN será definida com o conteúdo do segredo GITHUB_TOKEN. A chave permissions especifica o acesso concedido ao GITHUB_TOKEN.

    Para saber mais sobre como usar segredos em seu fluxo de trabalho, confira Usar segredos em ações do GitHub.