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_REMOTEYes.envRemote repository URL for the artifact
VORTEX_DEPLOY_ARTIFACT_ROOTNoCurrent directory.envRoot directory for artifact creation
VORTEX_DEPLOY_ARTIFACT_SRCNoCurrent directory.envSource directory to package
VORTEX_DEPLOY_ARTIFACT_DSTNo.artifact.envDestination directory for artifact
VORTEX_DEPLOY_ARTIFACT_GIT_USER_NAMEYesCIGit user name for commits
VORTEX_DEPLOY_ARTIFACT_GIT_USER_EMAILYesCIGit user email for commits
VORTEX_DEPLOY_ARTIFACT_LOGNo.envLog file path

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 Git user credentials to your CI provider's environment variables:

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

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
  • Pantheon hosting - Similar artifact-based deployment model
  • Custom hosting - Any platform that deploys from a Git repository

See also​