Composer API

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Use this API to interact with the Composer package manager client.

This API is used by the Composer package manager client and is generally not meant for manual consumption.

These endpoints do not adhere to the standard API authentication methods. See the Composer package registry documentation for details on which headers and token types are supported. Undocumented authentication methods might be removed in the future.

Retrieve repository URL templates

Retrieves the repository URL templates for requesting individual packages for a group.

GET group/:id/-/packages/composer/packages

Attribute	Type	Required	Description
`id`	string	yes	The ID or full path of the group.

curl --user <username>:<personal_access_token> \
  --url "https://gitlab.example.com/api/v4/group/1/-/packages/composer/packages"

Example response:

{
  "packages": [],
  "metadata-url": "/api/v4/group/1/-/packages/composer/p2/%package%.json",
  "provider-includes": {
    "p/%hash%.json": {
      "sha256": "082df4a5035f8725a12a4a3d2da5e6aaa966d06843d0a5c6d499313810427bd6"
    }
  },
  "providers-url": "/api/v4/group/1/-/packages/composer/%package%$%hash%.json"
}

This endpoint is used by Composer V1 and V2. To see the V2-specific response, include the Composer User-Agent header. Using Composer V2 is recommended over V1.

curl --user <username>:<personal_access_token> \
     --header "User-Agent: Composer/2" \
     --url "https://gitlab.example.com/api/v4/group/1/-/packages/composer/packages"

Example response:

{
  "packages": [],
  "metadata-url": "/api/v4/group/1/-/packages/composer/p2/%package%.json"
}

V1 packages list

Retrieves a list of packages in the repository for a group, given the V1 provider SHA. Using Composer V2 is recommended over V1.

GET group/:id/-/packages/composer/p/:sha

Attribute	Type	Required	Description
`id`	string	yes	The ID or full path of the group.
`sha`	string	yes	The provider SHA, provided by the Composer base request.

curl --user <username>:<personal_access_token> \
  --url "https://gitlab.example.com/api/v4/group/1/-/packages/composer/p/082df4a5035f8725a12a4a3d2da5e6aaa966d06843d0a5c6d499313810427bd6"

Example response:

{
  "providers": {
    "my-org/my-composer-package": {
      "sha256": "5c873497cdaa82eda35af5de24b789be92dfb6510baf117c42f03899c166b6e7"
    }
  }
}

Retrieve V1 package metadata

Retrieves the list of versions and metadata for a specified package for a group. Using Composer V2 is recommended over V1.

GET group/:id/-/packages/composer/:package_name$:sha

Note the $ symbol in the URL. When making requests, you may need the URL-encoded version of the symbol %24. Refer to the example after the table:

Attribute	Type	Required	Description
`id`	string	yes	The ID or full path of the group.
`package_name`	string	yes	The name of the package.
`sha`	string	yes	The SHA digest of the package, provided by the V1 packages list.

curl --user <username>:<personal_access_token> \
  --url "https://gitlab.example.com/api/v4/group/1/-/packages/composer/my-org/my-composer-package%245c873497cdaa82eda35af5de24b789be92dfb6510baf117c42f03899c166b6e7"

Example response:

{
  "packages": {
    "my-org/my-composer-package": {
      "1.0.0": {
        "name": "my-org/my-composer-package",
        "type": "library",
        "license": "GPL-3.0-only",
        "version": "1.0.0",
        "dist": {
          "type": "zip",
          "url": "https://gitlab.example.com/api/v4/projects/1/packages/composer/archives/my-org/my-composer-package.zip?sha=673594f85a55fe3c0eb45df7bd2fa9d95a1601ab",
          "reference": "673594f85a55fe3c0eb45df7bd2fa9d95a1601ab",
          "shasum": ""
        },
        "source": {
          "type": "git",
          "url": "https://gitlab.example.com/my-org/my-composer-package.git",
          "reference": "673594f85a55fe3c0eb45df7bd2fa9d95a1601ab"
        },
        "uid": 1234567
      },
      "2.0.0": {
        "name": "my-org/my-composer-package",
        "type": "library",
        "license": "GPL-3.0-only",
        "version": "2.0.0",
        "dist": {
          "type": "zip",
          "url": "https://gitlab.example.com/api/v4/projects/1/packages/composer/archives/my-org/my-composer-package.zip?sha=445394f85a55fe3c0eb45df7bd2fa9d95a1601ab",
          "reference": "445394f85a55fe3c0eb45df7bd2fa9d95a1601ab",
          "shasum": ""
        },
        "source": {
          "type": "git",
          "url": "https://gitlab.example.com/my-org/my-composer-package.git",
          "reference": "445394f85a55fe3c0eb45df7bd2fa9d95a1601ab"
        },
        "uid": 1234567
      }
    }
  }
}

Retrieve V2 package metadata

Retrieves the list of versions and metadata for a specified package for a group.

GET group/:id/-/packages/composer/p2/:package_name

Attribute	Type	Required	Description
`id`	string	yes	The ID or full path of the group.
`package_name`	string	yes	The name of the package.

curl --user <username>:<personal_access_token> \
  --url "https://gitlab.example.com/api/v4/group/1/-/packages/composer/p2/my-org/my-composer-package"

Example response:

{
  "packages": {
    "my-org/my-composer-package": {
      "1.0.0": {
        "name": "my-org/my-composer-package",
        "type": "library",
        "license": "GPL-3.0-only",
        "version": "1.0.0",
        "dist": {
          "type": "zip",
          "url": "https://gitlab.example.com/api/v4/projects/1/packages/composer/archives/my-org/my-composer-package.zip?sha=673594f85a55fe3c0eb45df7bd2fa9d95a1601ab",
          "reference": "673594f85a55fe3c0eb45df7bd2fa9d95a1601ab",
          "shasum": ""
        },
        "source": {
          "type": "git",
          "url": "https://gitlab.example.com/my-org/my-composer-package.git",
          "reference": "673594f85a55fe3c0eb45df7bd2fa9d95a1601ab"
        },
        "uid": 1234567
      },
      "2.0.0": {
        "name": "my-org/my-composer-package",
        "type": "library",
        "license": "GPL-3.0-only",
        "version": "2.0.0",
        "dist": {
          "type": "zip",
          "url": "https://gitlab.example.com/api/v4/projects/1/packages/composer/archives/my-org/my-composer-package.zip?sha=445394f85a55fe3c0eb45df7bd2fa9d95a1601ab",
          "reference": "445394f85a55fe3c0eb45df7bd2fa9d95a1601ab",
          "shasum": ""
        },
        "source": {
          "type": "git",
          "url": "https://gitlab.example.com/my-org/my-composer-package.git",
          "reference": "445394f85a55fe3c0eb45df7bd2fa9d95a1601ab"
        },
        "uid": 1234567
      }
    }
  }
}

Create a package

Creates a Composer package from a specified Git tag or branch for a project.

POST projects/:id/packages/composer

Attribute	Type	Required	Description
`id`	string	yes	The ID or full path of the group.
`tag`	string	no	The name of the tag to target for the package.
`branch`	string	no	The name of the branch to target for the package.

curl --request POST --user <username>:<personal_access_token> \
     --data tag=v1.0.0 \
     --url "https://gitlab.example.com/api/v4/projects/1/packages/composer"

Example response:

{
  "message": "201 Created"
}

Download a package archive

Downloads a specified Composer package archive for a project. This URL is provided in the v1 or v2 package metadata response. A .zip file extension must be in the request.

GET projects/:id/packages/composer/archives/:package_name

Attribute	Type	Required	Description
`id`	string	yes	The ID or full path of the group.
`package_name`	string	yes	The name of the package.
`sha`	string	yes	The target SHA of the requested package version.

curl --user <username>:<personal_access_token> \
  --url "https://gitlab.example.com/api/v4/projects/1/packages/composer/archives/my-org/my-composer-package.zip?sha=673594f85a55fe3c0eb45df7bd2fa9d95a1601ab"

Write the output to file:

curl --user <username>:<personal_access_token> \
  --url "https://gitlab.example.com/api/v4/projects/1/packages/composer/archives/my-org/my-composer-package.zip?sha=673594f85a55fe3c0eb45df7bd2fa9d95a1601ab" >> package.zip

This writes the downloaded file to package.zip in the current directory.