Download the PHP package drevops/git-artifact without Composer

Package and push files to a remote repository

🌟 With Git Artifact, you can:

📦 Assemble a code artifact locally or in CI
🧹 Exclude any unwanted files using a deployment .gitignore
📤 Transfer the final artifact to a destination Git repository for deployment
🔁 Choose between force-push or branch modes to fit your workflow

See example of deployed artifact in Artifact branches.

🔀 Workflow

1️⃣ 🧑‍💻 Develop in the source repository
2️⃣ 📦 CI installs dependencies and runs git-artifact to package and push code to destination repository
3️⃣ 🚀 Hosting receives the code artifact and triggers a deployment

🎚️ Modes

force-push mode (default)

Push the packaged artifact to the same branch in the destination repository. This will carry over the branch history from the source repository and will overwrite the existing branch history in the destination repository.

Use case

Forwarding all changes in the source repository to the destination repository as-is for every branch: for example, a commit in the source repository branch feature/123 would create a commit in the destination repository branch feature/123. The next commit to the source repository branch feature/123 would update the destination repository branch feature/123 with the changes, but would overwrite the last "artifact commit".

branch mode

Push the packaged artifact to the new branch in the destination repository. This will carry over the branch history from the source repository to a dedicated branch in the destination repository. The follow-up pushes to the branch in the destination repository will be blocked.

Use case

Creating a new branch in the destination repository for every tag created in the source repository: for example, a tag 1.2.3 in the source repository would create a branch deployment/1.2.3 in the destination repository. The addition of the new tags would create new unique branches in the destination repository.

Cleanup of stale branches

In branch mode the destination repository accumulates a new branch for every deployment. Enable --cleanup-stale to remove old ones automatically after a successful push:

Each --cleanup-pattern value is either a comma-separated list of shell globs (e.g. feature/*,bugfix/*) or a single regular expression wrapped in slashes (e.g. /^feature\/[^\/]+$/). The option is also repeatable, so patterns can be supplied across several flags or straight from an environment variable. A branch in the destination repository is deleted when it matches any of the patterns and its last commit is older than --cleanup-age days. The branch that was just pushed and the destination repository's default branch are never deleted. --cleanup-pattern is required - it is the only way to identify the branches created by your deployments. Add --dry-run to preview deletions without performing them.

Because deletion uses standard Git, this works with any remote (GitHub, GitLab, Bitbucket, self-hosted), not only GitHub.

📥 Installation

As a standalone binary

This tool is intended to be used as a standalone binary. You will need to have PHP installed on your system to run the binary.

Download the latest release from the GitHub releases page.

As a Docker container

The tool is also published as a multi-architecture (linux/amd64, linux/arm64) Docker image at drevops/git-artifact, with git and an SSH client bundled in - no local PHP required. Mount your source repository at /app and pass the same arguments you would pass to the binary:

The GIT_AUTHOR_* and GIT_COMMITTER_* variables set the identity for the deployment commit. To push to an SSH remote, also mount your SSH credentials read-only:

Image tags

Cross-platform (linux/amd64, linux/arm64) images are built by GitHub Actions and pushed to Docker Hub:

• <version> (e.g. 1.2.3) - published when a release tag is created on GitHub.
• latest - published when a release tag is created on GitHub.
• canary - published on every push to the main branch (latest unreleased changes).

Pin to a specific <version> tag for reproducible deployments and use canary only to try out unreleased changes.

As a Composer dependency

You may also install this tool globally using Composer:

📌 Version constraint

When using git-artifact in CI/CD scripts, we recommend using Tilde Version Range Operator to ensure stability. The tilde constraint allows patch updates (e.g., 1.0.0 → 1.1.1) but blocks minor version updates (e.g., 1.1.0 → 1.2.0).

This ensures that:

• Security fixes and bug patches are automatically applied
• CI/CD pipelines remain stable - no unexpected breaking changes
• Minor version updates are blocked - these may introduce behavioral changes that could affect deployments

This is especially important in CI/CD environments where deployment reliability is critical and changes should be tested before adoption.

▶️ Usage

This will create an artifact from current directory and will send it to the specified remote repository into the same branch as a current one.

Avoid including development dependencies in your artifacts. Instead, configure your CI to install production-only dependencies, export the resulting code, and use that as the artifact source. See our CI examples below.

Call from the CI configuration or deployment script:

CI providers may report branches differently when packaging is triggered by tags. We encourage you to explore our continuously and automatically tested examples:

• GitHub Actions
• CircleCI

See extended and fully-configured example in the Vortex project.

🎛️ Options

🧹 Modifying artifact content

--gitignore option allows to specify the path to the artifact's .gitignore file that replaces existing .gitignore (if any) during packaging. Any files no longer ignored by the replaced artifact's .gitignore are added into the deployment commit. If there are no no-longer-excluded files, the deployment commit is still created, to make sure that the deployment timestamp is captured.

🏷️ Token support

Tokens are pre-defined strings surrounded by [ and ] and may contain optional formatter. For example, [timestamp:Y-m-d] is replaced with the current timestamp in format Y-m-d (token formatter), which is PHP date() expected format.

Both --branch and --message option values support token replacement.

Available tokens:

• [timestamp:FORMAT] - current time with a PHP date()-compatible FORMAT.
• [branch] - current branch in the source repository.
• [safebranch] - current branch in the source repository with with all non-alphanumeric characters replaced with - and lowercased.
• [tags:DELIMITER] - tags from the latest commit in the source repository separated by a DELIMITER.

Maintenance

🧪 Testing

Packaging and deployment of artifacts is a mission-critical process, so we maintain a set of unit, functional and integration tests to make sure that everything works as expected.

You can see examples of the branches created by the Git Artifact in the example destination repository.

Lint and fix code

Run tests

Repository created using https://getscaffold.dev/ project scaffold template