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 Git Artifact
  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 SSH key selection, the pinned git-artifact version, and the optional stale-branch cleanup are covered in Git Artifact; the full variable list is 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"

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, yarn.lock).
  • 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​