https://github.com/drevops/git-artifact
📦 Assemble a code artifact from your codebase, remove unnecessary files, and push it into a separate Git repository.
https://github.com/drevops/git-artifact
acquia artefact artifact composer devops git package
Last synced: 16 days ago
JSON representation
📦 Assemble a code artifact from your codebase, remove unnecessary files, and push it into a separate Git repository.
- Host: GitHub
- URL: https://github.com/drevops/git-artifact
- Owner: drevops
- License: gpl-3.0
- Created: 2017-09-04T12:10:57.000Z (over 7 years ago)
- Default Branch: main
- Last Pushed: 2025-04-08T12:52:48.000Z (17 days ago)
- Last Synced: 2025-04-09T22:18:17.828Z (16 days ago)
- Topics: acquia, artefact, artifact, composer, devops, git, package
- Language: PHP
- Homepage:
- Size: 363 KB
- Stars: 20
- Watchers: 4
- Forks: 2
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
Package and push files to a remote repository
[](https://github.com/drevops/git-artifact/issues)
[](https://github.com/drevops/git-artifact/pulls)
[](https://codecov.io/gh/drevops/git-artifact)
[](https://packagist.org/packages/drevops/git-artifact)
[](https://github.com/drevops/git-artifact/actions/workflows/test-php.yml)
[](https://circleci.com/gh/drevops/git-artifact)
---
## 🌟 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](https://github.com/drevops/git-artifact-destination/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️⃣ 🚀 Deployment triggered whan code received
## 🎚️ 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.
```
==================================================
🏃 Run 1
==================================================
Local repo Remote repo
+------------------+
| Artifact commit | 💥 New commit
+------------------+
+-----------+ +------------------+
| Commit 2 | | Commit 2 | \
+-----------+ == 📦 ==> +------------------+ ) 👍 Source commit
| Commit 1 | | Commit 1 | / history preserved
+-----------+ +------------------+
`mybranch` `mybranch`
👆
Branch name identical to source
==================================================
🏃 Run 2
==================================================
Local repo Remote repo
+------------------+
| Artifact commit | 💥 New commit
+------------------+
+-----------+ +------------------+
| Commit 4 | | Commit 4 | \
+-----------+ +------------------+ \
| Commit 3 | | Commit 3 | \
+-----------+ == 📦 ==> +------------------+ ) 👍 Source commit
| Commit 2 | | Commit 2 | / history preserved
+-----------+ +------------------+ /
| Commit 1 | | Commit 1 | /
+-----------+ +------------------+
`mybranch` `mybranch`
👆
Branch name identical to source
```
#### 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.
```
==================================================
🏃 Run 1
==================================================
Local repo Remote repo
+------------------+
| Artifact commit | 💥 New commit
+------------------+
+-----------+ +------------------+
| Commit 2 | | Commit 2 | \
+-----------+ == 📦 ==> +------------------+ ) 👍 Source commit
| Commit 1 | | Commit 1 | / history preserved
+-----------+ +------------------+
`mybranch` `deployment/1.2.3`
tagged with
`1.2.3`
👆 👆
Tagged branch New branch based on tag
==================================================
🏃 Run 2
==================================================
Local repo Remote repo
+------------------+
| Artifact commit | 💥 New commit
+------------------+
+-----------+ +------------------+
| Commit 4 | | Commit 4 | \
+-----------+ +------------------+ \
| Commit 3 | | Commit 3 | \
+-----------+ == 📦 ==> +------------------+ ) 👍 Source commit
| Commit 2 | | Commit 2 | / history preserved
+-----------+ +------------------+ /
| Commit 1 | | Commit 1 | /
+-----------+ +------------------+
`mybranch` `deployment/1.2.4`
tagged with
`1.2.4` 👈 New tag 1.2.4
👆 👆
Tagged branch New branch based on a new tag
with a new tag
```
#### 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.
## 📥 Installation
This package 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](https://github.com/drevops/git-artifact/releases/latest).
You may also install the package globally using Composer:
```shell
composer global require --dev drevops/git-artifact
```
## ▶️ Usage
```shell
./git-artifact [email protected]:yourorg/your-repo-destination.git
```
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 build with 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:
```shell
export DEPLOY_BRANCH=
./git-artifact [email protected]:yourorg/your-repo-destination.git \
--branch="${DEPLOY_BRANCH}" \
--push
```
CI providers may report branches differently when running builds triggered by tags.
We encourage you to explore our continuously and automatically tested examples:
- [GitHub Actions](.github/workflows/test-php.yml)
- [CircleCI](.circleci/config.yml)
See extended and
fully-configured [example in the Vortex project](https://github.com/drevops/vortex/blob/develop/scripts/vortex/deploy-artifact.sh).
## 🎛️ Options
| Name | Default value | Description |
|------------------------|---------------------|------------------------------------------------------------------------------------------------|
| `--mode` | `force-push` | Mode of artifact build: `branch`, `force-push` |
| `--branch` | `[branch]` | Destination branch with optional tokens (see below) |
| `--gitignore` | | Path to the `.gitignore` file to replace the current `.gitignore` |
| `--src` | | Directory where source repository is located. Uses root directory if not specified |
| `--root` | | Path to the root for file path resolution. Uses current directory if not specified |
| `--message` | `Deployment commit` | Commit message with optional tokens (see below) |
| `--no-cleanup` | | Do not cleanup after run |
| `--log` | | Path to the log file |
| `--show-changes` | | Show changes made to the repo by the build in the output |
| `--dry-run` | | Run without pushing to the remote repository |
| `--now` | | Internal value used to set internal time |
| `-h, --help` | | Display help for the given command |
| `-q, --quiet` | | Do not output any messages |
| `-V, --version` | | Display this application version |
| `--ansi` | | Force ANSI output. Use `--no-ansi` to disable |
| `-n, --no-interaction` | | Do not ask any interactive question |
| `-v, --verbose` | | Increase the verbosity of messages: 1 for normal, 2 for more verbose, 3 for debug |
## 🧹 Modifying artifact content
`--gitignore` option allows to specify the path to the artifact's `.gitignore`
file that replaces existing `.gitignore` (if any) during the build. 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()`](https://www.php.net/manual/en/function.date.php) expected format.
Both `--branch` and `--message` option values support token replacement.
Available tokens:
- `[timestamp:FORMAT]` - current time with a PHP [`date()`](https://www.php.net/manual/en/function.date.php)-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](https://github.com/drevops/git-artifact-destination/branches).
### Lint and fix code
```bash
composer lint
composer lint-fix
```
### Run tests
```bash
composer test
```
---
_Repository created using https://getscaffold.dev/ project scaffold template_