{"id":49528,"date":"2025-05-28T03:25:32","date_gmt":"2025-05-28T03:25:32","guid":{"rendered":"https:\/\/www.devopsschool.com\/blog\/?p=49528"},"modified":"2025-05-28T03:26:23","modified_gmt":"2025-05-28T03:26:23","slug":"gitlab-package-registry-a-complete-guide","status":"publish","type":"post","link":"https:\/\/www.devopsschool.com\/blog\/gitlab-package-registry-a-complete-guide\/","title":{"rendered":"GitLab Deploy – Package Registry – A Complete Guide"},"content":{"rendered":"\n

<\/p>\n\n\n\n

\n\n\n\n

\ud83c\udfd7\ufe0f 1. Ensure Your GitLab Project Is Maven-Ready<\/strong><\/h2>\n\n\n\n

To store your Java packages (JAR\/WAR)<\/strong> into the GitLab Package Registry<\/strong> using GitLab CI\/CD (SaaS, version 18.x), you can use GitLab\u2019s built-in Maven repository<\/strong> support.<\/p>\n\n\n\n

Here\u2019s a step-by-step guide to:<\/p>\n\n\n\n

\u2705 Build your Java project
\u2705 Upload the .jar<\/code> or .war<\/code> to GitLab\u2019s Maven Package Registry<\/strong>
\u2705 Do this all through your .gitlab-ci.yml<\/code> pipeline<\/strong><\/p>\n\n\n\n

In your project root:<\/h3>\n\n\n\n

Ensure pom.xml<\/code> (for Maven) is set up with:<\/p>\n\n\n

<project<\/span>><\/span>\n  ...\n  <groupId<\/span>><\/span>com.example<\/groupId<\/span>><\/span>\n  <artifactId<\/span>><\/span>my-app<\/artifactId<\/span>><\/span>\n  <version<\/span>><\/span>1.0.0<\/version<\/span>><\/span>\n  ...\n<\/project<\/span>><\/span>\n<\/code><\/span>Code language:<\/span> HTML, XML<\/span> (<\/span>xml<\/span>)<\/span><\/small><\/pre>\n\n\n
\n\n\n\n
\ud83e\uddea 2. GitLab Package Registry URL<\/strong><\/h2>\n\n\n\n
GitLab SaaS Maven registry endpoint:<\/p>\n\n\n
https:\/\/gitlab.com\/api\/v4\/projects\/<PROJECT_ID<\/span>><\/span>\/packages\/maven\n<\/code><\/span>Code language:<\/span> HTML, XML<\/span> (<\/span>xml<\/span>)<\/span><\/small><\/pre>\n\n\n
You can find <PROJECT_ID><\/code> in your GitLab project settings or by using:<\/p>\n\n\n
https:\/\/gitlab.com\/<namespace<\/span>><\/span>\/<project_name<\/span>><\/span>\n<\/code><\/span>Code language:<\/span> HTML, XML<\/span> (<\/span>xml<\/span>)<\/span><\/small><\/pre>\n\n\n
\n\n\n\n
\ud83d\udd10 3. Create a CI\/CD Job to Publish Artifact<\/strong><\/h2>\n\n\n\n
.gitlab-ci.yml<\/code> example for Maven:<\/h3>\n\n\n
stages:\n  - build\n  - publish\n\nvariables:\n  MAVEN_CLI_OPTS: \"-B -DskipTests\"<\/span>\n\nbuild-job:\n  stage: build\n  image: maven:3.8<\/span>.7<\/span>-jdk-11<\/span>\n  script:\n    - mvn $MAVEN_CLI_OPTS clean package\n  artifacts:\n    paths:\n      - target\/*.jar\n      - target\/*.war\n\npublish-job:\n  stage: publish\n  image: maven:3.8.7-jdk-11\n  script:\n    - mvn deploy -s settings.xml\n  only:\n    - main\n<\/span><\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
\n\n\n\n
\u2699\ufe0f 4. Add settings.xml<\/code> for GitLab Auth<\/strong><\/h2>\n\n\n\n
In the root of your repo (or dynamically generate in CI):<\/p>\n\n\n
<settings<\/span>><\/span>\n  <servers<\/span>><\/span>\n    <server<\/span>><\/span>\n      <id<\/span>><\/span>gitlab<\/id<\/span>><\/span>\n      <username<\/span>><\/span>gitlab-ci-token<\/username<\/span>><\/span>\n      <password<\/span>><\/span>${env.CI_JOB_TOKEN}<\/password<\/span>><\/span>\n    <\/server<\/span>><\/span>\n  <\/servers<\/span>><\/span>\n<\/settings<\/span>><\/span>\n<\/code><\/span>Code language:<\/span> HTML, XML<\/span> (<\/span>xml<\/span>)<\/span><\/small><\/pre>\n\n\n
Ensure your pom.xml<\/code> contains:<\/p>\n\n\n
<distributionManagement<\/span>><\/span>\n  <repository<\/span>><\/span>\n    <id<\/span>><\/span>gitlab<\/id<\/span>><\/span>\n    <url<\/span>><\/span>https:\/\/gitlab.com\/api\/v4\/projects\/<PROJECT_ID<\/span>><\/span>\/packages\/maven<\/url<\/span>><\/span>\n  <\/repository<\/span>><\/span>\n<\/distributionManagement<\/span>><\/span>\n<\/code><\/span>Code language:<\/span> HTML, XML<\/span> (<\/span>xml<\/span>)<\/span><\/small><\/pre>\n\n\n
\n\n\n\n
\ud83d\udee1\ufe0f 5. Use the CI_JOB_TOKEN<\/code> Securely<\/strong><\/h2>\n\n\n\n
    \n
  • gitlab-ci-token<\/code> is a special user<\/strong> recognized by GitLab\u2019s package registry.<\/li>\n\n\n\n
  • CI_JOB_TOKEN<\/code> is auto-injected<\/strong> in GitLab CI\/CD and scoped to your project.<\/li>\n<\/ul>\n\n\n\n
    \n\n\n\n
    \ud83d\udce6 6. Check Published Packages<\/strong><\/h2>\n\n\n\n
    After the pipeline completes:<\/p>\n\n\n\n
      \n
    1. Go to your GitLab project<\/li>\n\n\n\n
    2. Click on Packages & Registries \u2192 Package Registry<\/strong><\/li>\n\n\n\n
    3. You\u2019ll see your .jar<\/code> or .war<\/code> listed<\/li>\n<\/ol>\n\n\n\n
      \n\n\n\n
      \ud83e\udde0 Bonus: Clean Up or Promote Packages<\/h2>\n\n\n\n
      You can add manual jobs to:<\/p>\n\n\n\n
        \n
      • Promote packages to another environment<\/li>\n\n\n\n
      • Delete old versions via API<\/li>\n\n\n\n
      • Install them in another Java project using Maven:<\/li>\n<\/ul>\n\n\n
        <dependency<\/span>><\/span>\n  <groupId<\/span>><\/span>com.example<\/groupId<\/span>><\/span>\n  <artifactId<\/span>><\/span>my-app<\/artifactId<\/span>><\/span>\n  <version<\/span>><\/span>1.0.0<\/version<\/span>><\/span>\n<\/dependency<\/span>><\/span>\n<\/code><\/span>Code language:<\/span> HTML, XML<\/span> (<\/span>xml<\/span>)<\/span><\/small><\/pre>\n\n\n
        \n\n\n\n
        \u2705 Summary<\/h2>\n\n\n\n
        Step<\/th>Description<\/th><\/tr><\/thead>
        Build Artifact<\/td>Use mvn package<\/code> in CI job<\/td><\/tr>
        Upload to GitLab<\/td>Use mvn deploy<\/code> with GitLab Maven repo<\/td><\/tr>
        Auth<\/td>Use CI_JOB_TOKEN<\/code> with gitlab-ci-token<\/code><\/td><\/tr>
        View<\/td>Packages tab in GitLab UI<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
        \n\n\n\n
        <\/p>\n\n\n\n
        How to use Package registry using Gradle<\/h2>\n\n\n\n
        Here is a step-by-step guide<\/strong> to publish JAR\/WAR packages from a Gradle-based Java project<\/strong> to GitLab\u2019s Maven Package Registry<\/strong>, using GitLab SaaS 18.x<\/strong>.<\/p>\n\n\n\n
        \n\n\n\n
        \u2705 Overview<\/h2>\n\n\n\n
          \n
        • You\u2019ll use GitLab\u2019s Maven-compatible Package Registry<\/strong><\/li>\n\n\n\n
        • You\u2019ll configure Gradle to use GitLab as a Maven repo<\/li>\n\n\n\n
        • You\u2019ll automate it using .gitlab-ci.yml<\/code> and CI_JOB_TOKEN<\/code><\/li>\n<\/ul>\n\n\n\n
          \n\n\n\n
          \ud83d\udcc1 1. Setup Your Gradle Project<\/strong><\/h2>\n\n\n\n
          In your build.gradle<\/code> file:<\/p>\n\n\n
          plugins {\n    id 'java'<\/span>\n    id 'maven-publish'<\/span>\n}\n\ngroup = 'com.example'<\/span>\nversion = '1.0.0'<\/span>\n\npublishing {\n    publications {\n        mavenJava(MavenPublication) {\n            from<\/span> components.java\n        }\n    }\n    repositories {\n        maven {\n            name = \"GitLab\"<\/span>\n            url = uri(\"https:\/\/gitlab.com\/api\/v4\/projects\/<PROJECT_ID>\/packages\/maven\"<\/span>)\n            credentials {\n                username = project.findProperty(\"gitlabUser\"<\/span>) ?: System.getenv(\"CI_JOB_TOKEN\"<\/span>)\n                password = project.findProperty(\"gitlabToken\"<\/span>) ?: System.getenv(\"CI_JOB_TOKEN\"<\/span>)\n            }\n        }\n    }\n}\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
          \n
          Replace <PROJECT_ID><\/code> with your GitLab project ID. You can find it on the project homepage (e.g., gitlab.com\/api\/v4\/projects\/1234567<\/code>).<\/p>\n<\/blockquote>\n\n\n\n
          \n\n\n\n
          \ud83d\udd10 2. No Hardcoded Credentials<\/strong><\/h2>\n\n\n\n
          Do not<\/strong> store username\/token in code.<\/p>\n\n\n\n
          In CI\/CD, GitLab will inject CI_JOB_TOKEN<\/code> automatically. For local testing, you can override via gradle.properties<\/code> or CLI:<\/p>\n\n\n
          gitlabUser=gitlab-ci-token\ngitlabToken=<your<\/span> personal<\/span> access<\/span> token<\/span>><\/span>\n<\/code><\/span>Code language:<\/span> HTML, XML<\/span> (<\/span>xml<\/span>)<\/span><\/small><\/pre>\n\n\n
          \n\n\n\n
          \ud83e\uddea 3. Test Locally (Optional)<\/strong><\/h2>\n\n\n
          .\/gradlew publish \\\n  -PgitlabUser=gitlab-ci-token \\\n  -PgitlabToken=<your<\/span> GitLab<\/span> personal<\/span> access<\/span> token<\/span>><\/span>\n<\/code><\/span>Code language:<\/span> HTML, XML<\/span> (<\/span>xml<\/span>)<\/span><\/small><\/pre>\n\n\n
          \n\n\n\n
          \u2699\ufe0f 4. Create .gitlab-ci.yml<\/code><\/strong><\/h2>\n\n\n
          stages:\n  - build\n  - publish\n\nvariables<\/span>:\n  GRADLE_USER_HOME: \"$CI_PROJECT_DIR\/.gradle\"<\/span>\n\nbuild-job:\n  stage: build\n  image<\/span>: gradle:8.2<\/span>.1<\/span>-jdk17\n  script<\/span>:\n    - gradle build\n\npublish-job:\n  stage: publish\n  image<\/span>: gradle:8.2<\/span>.1<\/span>-jdk17\n  script<\/span>:\n    - gradle publish\n  only<\/span>:\n    - main\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
          \n
          This will publish the JAR\/WAR file to GitLab Package Registry on main<\/code> branch only<\/strong>.<\/p>\n<\/blockquote>\n\n\n\n
          \n\n\n\n
          \ud83d\udce6 5. Where to View Packages<\/strong><\/h2>\n\n\n\n
          After successful pipeline execution:<\/p>\n\n\n\n
            \n
          • Navigate to Your Project \u2192 Packages & Registries \u2192 Package Registry<\/strong><\/li>\n\n\n\n
          • You\u2019ll see the .jar<\/code> or .war<\/code> under your published Maven group.<\/li>\n<\/ul>\n\n\n\n
            \n\n\n\n
            \ud83d\udd01 6. How to Use in Other Projects<\/strong><\/h2>\n\n\n\n
            In another Gradle project, consume the published package:<\/p>\n\n\n
            repositories {\n    maven {\n        url = uri(\"https:\/\/gitlab.com\/api\/v4\/projects\/<PROJECT_ID>\/packages\/maven\"<\/span>)\n        credentials {\n            username = 'gitlab-ci-token'<\/span>\n            password = System.getenv(\"CI_JOB_TOKEN\"<\/span>) \/\/ or use .env or gradle.properties<\/span>\n        }\n    }\n}\n\ndependencies {\n    implementation 'com.example:your-artifact:1.0.0'<\/span>\n}\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
            \n\n\n\n
            \u2705 Summary Table<\/h2>\n\n\n\n
            Step<\/th>Action<\/th><\/tr><\/thead>
            build.gradle<\/code><\/td>Add maven-publish<\/code>, configure GitLab Maven repo<\/td><\/tr>
            Credentials<\/td>Use CI_JOB_TOKEN<\/code> with gitlab-ci-token<\/code><\/td><\/tr>
            .gitlab-ci.yml<\/code><\/td>Run gradle publish<\/code> from CI\/CD<\/td><\/tr>
            Registry URL<\/td>https:\/\/gitlab.com\/api\/v4\/projects\/<PROJECT_ID>\/packages\/maven<\/code><\/td><\/tr>
            View Packages<\/td>Project \u2192 Packages & Registries \u2192 Package Registry<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
            \n\n\n\n
            <\/p>\n","protected":false},"excerpt":{"rendered":"
            \ud83c\udfd7\ufe0f 1. Ensure Your GitLab Project Is Maven-Ready To store your Java packages (JAR\/WAR) into the GitLab Package Registry using GitLab CI\/CD (SaaS, version 18.x), you can use GitLab\u2019s built-in… <\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"","sticky":false,"template":"","format":"standard","meta":{"_joinchat":[],"footnotes":""},"categories":[2],"tags":[],"class_list":["post-49528","post","type-post","status-publish","format-standard","hentry","category-uncategorised"],"_links":{"self":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/49528","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/comments?post=49528"}],"version-history":[{"count":3,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/49528\/revisions"}],"predecessor-version":[{"id":49531,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/49528\/revisions\/49531"}],"wp:attachment":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/media?parent=49528"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/categories?post=49528"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/tags?post=49528"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}