Skip to main content

Artifact deployment

Artifact deployment packages your codebase and pushes it to a remote Git repository. This is commonly used for hosting platforms like Acquia that require pre-built code artifacts.

How it works​

When artifact is included in $VORTEX_DEPLOY_TYPES, the deployment script:

  1. Creates a clean code artifact using the Git artifact tool
  2. Applies the .gitignore.artifact rules to control which files are included
  3. Pushes the artifact to the configured remote repository
  4. The hosting platform then deploys from that repository

Configuration​

Environment variables​

VariableRequiredDefaultLocationDescription
VORTEX_DEPLOY_ARTIFACT_GIT_REMOTEYesCI or .envRemote repository URL for the artifact
VORTEX_DEPLOY_ARTIFACT_GIT_USER_EMAILYesCIEmail address of the user committing to the remote repository
VORTEX_DEPLOY_ARTIFACT_GIT_USER_NAMENoDeployment RobotCIName of the user committing to the remote repository
VORTEX_DEPLOY_ARTIFACT_DST_BRANCHNo[branch].envRemote branch to push to; supports tokens
VORTEX_DEPLOY_ARTIFACT_ROOTNoCurrent directoryCIRoot directory the deployment script runs from
VORTEX_DEPLOY_ARTIFACT_SRCNoCISource directory with the built code to package
VORTEX_DEPLOY_ARTIFACT_LOGNo<root>/deployment_log.txt.envDeployment log file path

The pinned git-artifact version and the optional stale-branch cleanup are covered in Git artifact tool; the SSH key selection and the full variable list are in the Variables reference.

Setup​

  1. Add artifact to the VORTEX_DEPLOY_TYPES variable in your .env file:

    .env
    VORTEX_DEPLOY_TYPES=artifact

  2. Configure the artifact remote repository:

    .env
    VORTEX_DEPLOY_ARTIFACT_GIT_REMOTE=git@github.com:your-org/your-project-artifact.git

  3. Add the Git user email to your CI provider's environment variables (and optionally a user name to replace the default Deployment Robot):

    VORTEX_DEPLOY_ARTIFACT_GIT_USER_EMAIL="deploy@example.com"
    VORTEX_DEPLOY_ARTIFACT_GIT_USER_NAME="Deployment Bot"

Git artifact tool​

git-artifact packages and pushes files to remote repositories.

Some hosting providers, like Acquia, restrict certain build operations, making it necessary to develop and build your site elsewhere before deploying it. This tool handles that transfer: it uses a .gitignore.artifact file to control which files get transferred, and overwrites the destination repository's history with each push, while preserving the source history.

Vortex comes with pre-configured .gitignore.artifact file and the deploy-artifact deployment script from the drevops/vortex-tooling Composer package to build the artifact in continuous integration pipeline and push it to the remote repository in Acquia.

This tool is used in continuous integration pipeline and does not require any manual actions.

The git-artifact binary is downloaded from GitHub Releases and verified with a SHA256 checksum before execution.

The version and checksum are controlled by:

  • VORTEX_DEPLOY_ARTIFACT_GIT_ARTIFACT_VERSION: Version to download (default: 1.7.0).
  • VORTEX_DEPLOY_ARTIFACT_GIT_ARTIFACT_SHA256: Expected SHA256 checksum of the binary.

Stale branch cleanup​

Each source branch is deployed to a same-named branch in the destination repository, so over time the destination accumulates branches for source branches that no longer exist. Vortex can prune these stale branches after each successful push.

Cleanup is opt-in and controlled by:

  • VORTEX_DEPLOY_ARTIFACT_CLEANUP_PATTERN: branches eligible for pruning. Setting a non-empty value enables cleanup; leaving it empty (the default) disables it. The value is a comma-separated list of globs (e.g. feature/*,bugfix/*) or a single regex literal (e.g. /^feature\/.+$/). A branch matching any pattern is eligible.
  • VORTEX_DEPLOY_ARTIFACT_CLEANUP_AGE: age in days after which a matching branch is considered stale (default: 7).

The branch that was just pushed and the destination repository's default branch are never deleted, and cleanup never fails a deployment that already succeeded.

Artifact file control​

The .gitignore.artifact file controls which files are included in the deployment artifact. During deployment it replaces the standard .gitignore in the artifact repository, so its rules - not the project's normal ignore rules - decide what reaches the hosting Git repository.

Vortex writes .gitignore.artifact as a deny list: every file is deployed by default, and the file lists only what must be kept out of production. Vortex provides a pre-configured .gitignore.artifact that deploys everything a production Drupal site needs - vendor/, the built webroot (Drupal core, contributed modules and themes, and compiled theme assets), config/, drush/, scripts/, and .env - while excluding:

  • Development, continuous integration, and AI configuration (.ahoy.yml, .circleci, .docker, .github, docker-compose.yml).
  • Documentation and testing configuration (docs, tests, behat.yml, phpunit.xml, phpcs.xml).
  • Dependency manifests and lock files not needed at runtime (composer.lock, package.json, package-lock.json).
  • Credentials, local overrides, caches, and content files (auth.json, .env.local, .data, web/sites/*/files).
  • Theme asset sources, since only the compiled build/ output is deployed.

Customizing the artifact​

Because the file is a deny list, a new file you add to the project is deployed automatically. Edit .gitignore.artifact only to keep an additional file out of the artifact, or to re-include something that a broader rule excludes:

.gitignore.artifact
# Keep an additional development file out of the artifact.
/RELEASE.md

# Re-include theme images that the artifact excludes by default.
!/web/themes/custom/your_site_theme/images

Use cases​

  • Acquia hosting - Acquia requires code artifacts pushed to their Git repository
  • Other Git-based hosting - any platform that deploys from a Git repository it controls

See also​