zhongwei/gh-lucacri-claude-gitlab-documentation-gitlab-documentation-skill

Files

Zhongwei Li ce53f43c3e Initial commit

2025-11-30 08:38:11 +08:00

9.3 KiB

Raw Blame History

GitLab Package Registry Reference

Overview

GitLab Package Registry allows you to publish and share packages within your organization. Supports multiple package formats.

Supported Package Types

Maven (Java)
npm (JavaScript/Node.js)
PyPI (Python)
NuGet (.NET)
Composer (PHP)
Conan (C/C++)
Go Modules
Helm Charts (Kubernetes)
Terraform Modules
Generic packages
RubyGems (Ruby)
Debian packages
RPM packages

npm Packages

Publish npm Package

.npmrc:

@scope:registry=https://gitlab.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/
//gitlab.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}

package.json:

{
  "name": "@scope/package-name",
  "version": "1.0.0",
  "publishConfig": {
    "@scope:registry": "https://gitlab.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/"
  }
}

.gitlab-ci.yml:

publish:
  image: node:18
  script:
    - echo "@scope:registry=https://gitlab.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/" > .npmrc
    - echo "//gitlab.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}" >> .npmrc
    - npm publish
  only:
    - tags

Install npm Package

# Configure registry
npm config set @scope:registry https://gitlab.com/api/v4/projects/PROJECT_ID/packages/npm/

# With auth token
npm config set -- '//gitlab.com/api/v4/projects/PROJECT_ID/packages/npm/:_authToken' "TOKEN"

# Install
npm install @scope/package-name

Maven Packages

Publish Maven Package

pom.xml:

<repositories>
  <repository>
    <id>gitlab-maven</id>
    <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url>
  </repository>
</repositories>

<distributionManagement>
  <repository>
    <id>gitlab-maven</id>
    <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url>
  </repository>
  <snapshotRepository>
    <id>gitlab-maven</id>
    <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url>
  </snapshotRepository>
</distributionManagement>

settings.xml:

<settings>
  <servers>
    <server>
      <id>gitlab-maven</id>
      <configuration>
        <httpHeaders>
          <property>
            <name>Job-Token</name>
            <value>${env.CI_JOB_TOKEN}</value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
  </servers>
</settings>

.gitlab-ci.yml:

deploy:
  image: maven:3-openjdk-11
  script:
    - mvn deploy -s ci_settings.xml
  only:
    - tags

PyPI Packages

Publish Python Package

.pypirc:

[distutils]
index-servers =
    gitlab

[gitlab]
repository = https://gitlab.com/api/v4/projects/${CI_PROJECT_ID}/packages/pypi
username = gitlab-ci-token
password = ${CI_JOB_TOKEN}

.gitlab-ci.yml:

publish:
  image: python:3.11
  script:
    - pip install twine build
    - python -m build
    - TWINE_PASSWORD=${CI_JOB_TOKEN} TWINE_USERNAME=gitlab-ci-token python -m twine upload --repository-url https://gitlab.com/api/v4/projects/${CI_PROJECT_ID}/packages/pypi dist/*
  only:
    - tags

Install Python Package

# pip install
pip install --index-url https://__token__:${PERSONAL_ACCESS_TOKEN}@gitlab.com/api/v4/projects/PROJECT_ID/packages/pypi/simple package-name

# requirements.txt
--index-url https://__token__:${PERSONAL_ACCESS_TOKEN}@gitlab.com/api/v4/projects/PROJECT_ID/packages/pypi/simple
package-name==1.0.0

NuGet Packages

Publish NuGet Package

.gitlab-ci.yml:

publish:
  stage: deploy
  image: mcr.microsoft.com/dotnet/sdk:7.0
  script:
    - dotnet pack -c Release
    - dotnet nuget add source "https://gitlab.com/api/v4/projects/${CI_PROJECT_ID}/packages/nuget/index.json" --name gitlab --username gitlab-ci-token --password ${CI_JOB_TOKEN} --store-password-in-clear-text
    - dotnet nuget push "bin/Release/*.nupkg" --source gitlab
  only:
    - tags

Install NuGet Package

# Add source
dotnet nuget add source "https://gitlab.com/api/v4/projects/PROJECT_ID/packages/nuget/index.json" --name gitlab --username USERNAME --password TOKEN

# Install
dotnet add package PackageName

Composer Packages (PHP)

Publish Composer Package

composer.json:

{
  "name": "vendor/package-name",
  "version": "1.0.0",
  "type": "library",
  "repositories": [
    {
      "type": "composer",
      "url": "https://gitlab.com/api/v4/group/GROUP_ID/-/packages/composer/packages.json"
    }
  ]
}

.gitlab-ci.yml:

publish:
  image: curlimages/curl:latest
  script:
    - 'curl --header "Job-Token: ${CI_JOB_TOKEN}" --data tag=${CI_COMMIT_TAG} "https://gitlab.com/api/v4/projects/${CI_PROJECT_ID}/packages/composer"'
  only:
    - tags

Generic Packages

Publish Generic Package

curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" \
  --upload-file path/to/file.zip \
  "https://gitlab.com/api/v4/projects/${CI_PROJECT_ID}/packages/generic/package-name/1.0.0/file.zip"

.gitlab-ci.yml:

upload:
  stage: deploy
  script:
    - 'curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" --upload-file myfile.zip "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/mypackage/1.0.0/myfile.zip"'

Download Generic Package

curl --header "PRIVATE-TOKEN: <token>" \
  "https://gitlab.com/api/v4/projects/PROJECT_ID/packages/generic/package-name/1.0.0/file.zip" \
  -o file.zip

Helm Charts

Publish Helm Chart

.gitlab-ci.yml:

publish:
  image: alpine/helm:latest
  script:
    - helm package chart/
    - 'curl --request POST --user gitlab-ci-token:${CI_JOB_TOKEN} --form "chart=@mychart-1.0.0.tgz" "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/helm/api/stable/charts"'
  only:
    - tags

Install Helm Chart

# Add repo
helm repo add --username <username> --password <token> gitlab https://gitlab.com/api/v4/projects/PROJECT_ID/packages/helm/stable

# Install
helm install myrelease gitlab/mychart

Terraform Modules

Publish Terraform Module

Project structure:

terraform-module/
├── main.tf
├── variables.tf
├── outputs.tf
└── README.md

.gitlab-ci.yml:

upload:
  image: curlimages/curl:latest
  script:
    - tar -czf module.tar.gz *
    - 'curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" --upload-file module.tar.gz "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/terraform/modules/my-module/my-system/1.0.0/file"'
  only:
    - tags

Use Terraform Module

module "example" {
  source = "gitlab.com/group/project//modules/my-module"
  version = "1.0.0"
}

Conan Packages (C/C++)

Publish Conan Package

.gitlab-ci.yml:

publish:
  image: conanio/gcc11
  script:
    - conan remote add gitlab https://gitlab.com/api/v4/projects/${CI_PROJECT_ID}/packages/conan
    - conan user ci_user -r gitlab -p ${CI_JOB_TOKEN}
    - conan create . mycompany/stable
    - conan upload "*" --all -r gitlab --confirm
  only:
    - tags

Go Modules

Publish Go Module

Automatic: Just create a Git tag

git tag v1.0.0
git push origin v1.0.0

Use module:

import "gitlab.com/group/project/module"

go get gitlab.com/group/project/module@v1.0.0

Configure private modules:

git config --global url."https://oauth2:${GITLAB_TOKEN}@gitlab.com".insteadOf "https://gitlab.com"
export GOPRIVATE="gitlab.com/group/*"

Package Management API

List Packages

curl --header "PRIVATE-TOKEN: <token>" \
  "https://gitlab.com/api/v4/projects/PROJECT_ID/packages"

Get Package

curl --header "PRIVATE-TOKEN: <token>" \
  "https://gitlab.com/api/v4/projects/PROJECT_ID/packages/PACKAGE_ID"

Delete Package

curl --request DELETE --header "PRIVATE-TOKEN: <token>" \
  "https://gitlab.com/api/v4/projects/PROJECT_ID/packages/PACKAGE_ID"

List Package Files

curl --header "PRIVATE-TOKEN: <token>" \
  "https://gitlab.com/api/v4/projects/PROJECT_ID/packages/PACKAGE_ID/package_files"

Package Cleanup Policies

Configure Cleanup

curl --request PUT --header "PRIVATE-TOKEN: <token>" \
  "https://gitlab.com/api/v4/projects/PROJECT_ID" \
  --data "packages_cleanup_policy_attributes[keep_n_duplicated_package_files]=10" \
  --data "packages_cleanup_policy_attributes[older_than]=90d"

Best Practices

1. Versioning

Use semantic versioning (SemVer)
Tag releases properly
Maintain changelog
Document breaking changes

2. Security

Use deploy tokens for CI/CD
Rotate tokens regularly
Scan packages for vulnerabilities
Sign packages when possible

3. Organization

Use consistent naming
Group related packages
Document package usage
Maintain package metadata

4. CI/CD Integration

stages:
  - build
  - test
  - publish

build:
  stage: build
  script:
    - npm run build

test:
  stage: test
  script:
    - npm test

publish:
  stage: publish
  script:
    - npm publish
  only:
    - tags
  when: manual

Additional Resources

Package Registry Docs: https://docs.gitlab.com/ee/user/packages/package_registry/
npm Registry: https://docs.gitlab.com/ee/user/packages/npm_registry/
Maven Repository: https://docs.gitlab.com/ee/user/packages/maven_repository/
PyPI Repository: https://docs.gitlab.com/ee/user/packages/pypi_repository/

9.3 KiB Raw Blame History

GitLab Package Registry Reference

Overview

Supported Package Types

npm Packages

Publish npm Package

Install npm Package

Maven Packages

Publish Maven Package

PyPI Packages

Publish Python Package

Install Python Package

NuGet Packages

Publish NuGet Package

Install NuGet Package

Composer Packages (PHP)

Publish Composer Package

Generic Packages

Publish Generic Package

Download Generic Package

Helm Charts

Publish Helm Chart

Install Helm Chart

Terraform Modules

Publish Terraform Module

Use Terraform Module

Conan Packages (C/C++)

Publish Conan Package

Go Modules

Publish Go Module

Package Management API

List Packages

Get Package

Delete Package

List Package Files

Package Cleanup Policies

Configure Cleanup

Best Practices

1. Versioning

2. Security

3. Organization

4. CI/CD Integration

Additional Resources

9.3 KiB

Raw Blame History