Converting your Git reference project to the artifact deployment method

Introduction

This guide explains how to convert your project structure from the Git reference deployment method to the Artifact deployment method. This transition will help you manage your project more efficiently using artifacts in GitLab.

Prerequisites

Before you begin, ensure you have the following:

• Familiarity with GitLab pipelines.
• Your project managed by a package manager (e.g., Composer for Drupal projects).
• Access to your .gitignore file and GitLab project settings.

Step 1: Update your .gitignore file

In the Artifact deployment method, not all files need to be committed to the repository. You can exclude certain directories from version control. Start by updating your .gitignore file to ignore files and directories that are managed by your package manager.

Example for a Drupal project

Add the following lines to your .gitignore file:

/docroot/core
/vendor/
/docroot/libraries
/docroot/modules/contrib
/docroot/profiles/contrib
/docroot/themes/contrib

Next, delete the contents of these directories from your local repository.

Step 2: Set up a release pipeline

To deploy using the Artifact method, you need to create an artifact of your project using GitLab pipelines. Follow the instructions in the Creating artifacts guide to set up your pipeline.

Example for a Drupal project

Here is an example .gitlab-ci.yml configuration:

stages:
  - build
  - build-artifact
  - push-artifact

include:
  - component: $CI_SERVER_FQDN/resources/dxp-ci-catalog/composer-build@~latest
    inputs:
      php_version: '8.2'
  - component: $CI_SERVER_FQDN/resources/dxp-ci-catalog/create-artifact-release@~latest

create-artifact-release:build:
dependencies:
  - composer-build:composer-install-prod

Step 3: Commit and push your changes

Warning

Create a test branch for your changes before merging them into other branches. This helps ensure everything works as expected.

Pushing your changes will trigger the pipeline, which runs automatically with each push. You can monitor the status of your pipelines in your GitLab project.

Viewing pipeline results

If the pipeline succeeds, you will see a new package release.

• Where to view pipelines

  ---

  

• Where to view package releases

  ---

  

Download the artifact file from the package release to verify it includes all necessary components.

Step 4: Change the deployment method

Once the pipeline and artifact are correctly set up, follow the instructions on the Switching the deployment method page to update your environment’s deployment method.

Step 5: Verify that everything works as expected

Trigger the Deploy action in a non-production test environment. Select your newly created artifact, submit the form, and confirm that everything functions correctly.