Creating artifacts¶
Introduction¶
To successfully use the Artifact deployment method, your project must create package releases containing artifacts ready for deployment. This guide explains how to set up your project for this purpose.
Setting up your .gitlab-ci.yml file¶
The Dropsolid Experience Cloud uses GitLab to host projects and checks for any dxp- prefixed packages that contain files to expose as options in the 'Deploy' shortcut popup. When a package contains duplicate assets, only the last asset is shown to deploy.
These packages are created using GitLab pipelines, which require a correctly configured .gitlab-ci.yml file.
While there are no strict requirements for the package or compressed artifact file, the file must be a generic package and should either be a .zip or .gz format.
However, we provide default configurations in our component library to simplify and expedite the process of creating a pipeline compatible with the Artifact deployment method.
The default configurations create and publishes artifacts for following scenarios:
- tags
- commits on protected branches
- commits on branches that have a merge request
- Manually triggered pipelines in the gitlab UI.
Example .gitlab-ci.yml¶
Below is a minimal example for a PHP project that uses composer to manage dependencies (e.g., Drupal, Mautic). In this setup, the project does not commit vendor dependencies to the repository; instead, it builds them during the build stage. The artifact stages then compress all necessary files into an release.tar.gz file and push it to the package registry for deployment.
stages:
- build
- build-artifact
- push-artifact
include:
# Includes a component that runs `composer install` in the
# `build` stage with dev and production dependencies.
# If your project does not require external dependencies (e.g., HTML),
# you can skip or modify this step.
# If your project uses a specialized build method, it is advised to not include
# the provided component, but provide a custom one.
- component: $CI_SERVER_FQDN/resources/dxp-ci-catalog/composer-build@1
inputs:
php_version: '8.2'
# Includes a component to build the artifact.
- component: $CI_SERVER_FQDN/resources/dxp-ci-catalog/create-artifact@1
# Includes a component to push the artifact to the package registry.
- component: $CI_SERVER_FQDN/resources/dxp-ci-catalog/publish-artifact@1
# Ensures the artifact release build job depends on the composer build job
# or any other job you use to gather all external content for a release
# package.
create-artifact-release:build:
dependencies:
- composer-build:composer-install-prod
Example .gitlab-ci.yml for a Node.js project¶
The component library does not yet provide a dedicated build component for Node.js projects. Until it does, install dependencies with a custom job in the build stage instead of an include build component, and point create-artifact-release:build at that job the same way the PHP example points at composer-build.
As with the Composer example, node_modules/ should not be committed to the repository — add it to .gitignore and let this job supply it to the artifact instead.
Pin the image: tag to the same Node.js major version your environment actually runs. A mismatch here (e.g. building on node:20 while the environment runs Node 24) won't fail the pipeline, but can produce a package that behaves differently at runtime than it did in CI. It's also worth adding an engines.node field to package.json so this can't silently drift.
stages:
- build
- build-artifact
- push-artifact
include:
# Includes a component to build the artifact.
- component: $CI_SERVER_FQDN/resources/dxp-ci-catalog/create-artifact@1
# Includes a component to push the artifact to the package registry.
- component: $CI_SERVER_FQDN/resources/dxp-ci-catalog/publish-artifact@1
npm-build:
stage: build
image: node:24-alpine # match the Node.js version your environment runs
script:
- npm ci --omit=dev
artifacts:
paths:
- node_modules/
create-artifact-release:build:
dependencies:
- npm-build
Package naming conventions¶
A package is created per branch, and one package for the tagged commits. For branch packages, the latest version will be overridden with a new package. For packages generated from a tagged commit a new version is created for each tag.