README

Helps generating artifacts for Drupal by wrapping all code into an artifact, and pushing it to the artifact remote repository.

Table of contents

• Installation
• Usage
• CI integration
• Upgrade from 1.x to 2.x
• Upgrade from 2.x to 3.x

Installation

composer require metadrop/drupal-artifact-builder

Configuration

Drupal artifact builder allow using a configuration file to create the artifact. Artifacts usually are executed using always the same parameters. So, a configuration file saves time adding those parameters every time the command is run.

Configuration file is placed at root (it can be changed through command line parameters). You cam copy the template to have an starting point:

cp vendor/metadrop/drupal-artifact-builder/.drupal-artifact-builder.yml.dist .drupal-artifact-builder.yml

Configuration properties

• commands: Commands to run inside the artifact folder before packaging.

  Example:

  commands:
      - composer install --no-dev
      - cd web/themes/custom/foo/ && npm install && npm run production

• repository: Repository URL (git SSH / git HTTP URL).

  Example:

  repository: git@github.com:example/example-artifact.git

• include: Extra files or folders to include into the artifact.

  Example:

  include:
    - oauth
    - solr

• author: It will be the author used in git commits.

  Example:

  author: John Doe <passionate.developer@example.com>

• branches_map: Key value map to git push source artifact branches to different artifact branches.

  Example:

  branches_map:
    develop:develop-build

This example will make push the artifacts coming from develop source branch to the develop-build artifact branch.

Usage

Important: Please note that Drupal Artifact Builder does not download Composer libraries or compile CSS assets. These tasks must be completed prior to running the command.

Builds the artifact and push the changes to git:

drupal-artifact-builder

Generate the artifact:

drupal-artifact-builder create

Push the created artifact to git:

drupal-artifact-builder git

Parameters

• branch: Branch to create the artifact from / to. Required.

• config: Allow setting the configuration file. Defaults to .drupal-artifact-builder.yml

  drupal-artifact-builder git  folder/.drupal-artifact-builder.custom.yml
  

• repository: Selects the repository where the artifacts will be pushed.

  Examples:

  For the complete command (create + git):

  drupal-artifact-builder --repository git@example.com:example/example.git
  

  For the git command:

  drupal-artifact-builder git --repository git@example.com:example/example.git
  

• include: Allow adding more paths to the artifact.

  drupal-artifact-builder --repository git@example.com:example/example.git --include=oauth.json,mycustomapp
  

CI integration

GitHub Actions

A ready-to-use workflow is available at examples/github-actions.yml. Copy it into your Drupal project at .github/workflows/deploy-artifact.yml and follow these steps:

1. Generate an SSH key pair for the artifact repository:

   ssh-keygen -t ed25519 -C "artifact-deploy" -f artifact_deploy_key -N ""

2. Add the public key (artifact_deploy_key.pub) as a deploy key with write access in the artifact repository settings (Settings > Deploy keys).

3. Add the private key (artifact_deploy_key) as a repository secret named ARTIFACT_DEPLOY_KEY in the source Drupal repository (Settings > Secrets and variables > Actions).

4. Adjust the workflow to your needs:

   • Update the branches list under on.push to match the branches you want to deploy.
   • Change the Docker image tag (php8.3-node20) to match your PHP and Node versions. Available tags are listed in the drupal-artifact-builder-docker repository.

Prerequisites: Before running the workflow, make sure .drupal-artifact-builder.yml is correctly configured in your project root as described in the Configuration section. At minimum, the repository key must point to the artifact repository.

The workflow runs inside the ghcr.io/metadrop/drupal-artifact-builder-docker image, which provides PHP, Composer, Node, and Git out of the box. You can replace this image with any other, as long as it includes PHP, Composer, and Git.

Upgrade from 1.x to 2.x

2.0.0 release brings breaking changes and the way to use drupal-artifact-builder changes.

These steps must be followed in order to upgrade to the 2.0.0 version:

1. Copy and configure .drupal-artifact-builder.yml:

   cp vendor/metadrop/drupal-artifact-builder/.drupal-artifact-builder.yml.dist .drupal-artifact-builder.yml
   

2. Change --extra-paths parameters to --include

   Before:

   drupal-artifact-builder --extra-paths solr

   Now:

   drupal-artifact-builder --include solr

3. Stop using GIT_BRANCH environment variable, now it is --branch

   Before:

   GIT_BRANCH=develop drupal-artifact-builder

   Now:

   drupal-artifact-builder --branch develop

Upgrade from 2.x to 3.x

To be able to bring composer libraries and compile the custom theme, configure commands in .drupal-artifact-builder.yml.

Example:
```yaml
commands:
    - composer install --no-dev
    - cd web/themes/custom/foo/ && npm install && npm run production
```