drevops / git-artifact
Build artifact from your codebase in CI and push it to a separate git repo.
Installs: 19 179
Dependents: 0
Suggesters: 0
Security: 0
Stars: 20
Watchers: 5
Forks: 2
Open Issues: 11
Type:package
Requires
- php: >=8.2
- czproject/git-php: ^4.3
- monolog/monolog: ^3.5
- symfony/console: ^7
- symfony/filesystem: ^7
- symfony/finder: ^7
- symfony/monolog-bridge: ^7
- symfony/process: ^7
Requires (Dev)
- bamarni/composer-bin-plugin: ^1.8
- dealerdirect/phpcodesniffer-composer-installer: ^1.0
- drupal/coder: ^8.3
- phpmd/phpmd: ^2.15
- phpstan/phpstan: ^1.10
- phpunit/phpunit: ^10.5
- rector/rector: ^1.0.0
README
Package and push files to a remote repository
What is it?
A tool to assemble a code artifact from your codebase, remove unnecessary files, and push it into a separate Git repository.
Why?
In hosting environments like Acquia, there are restrictions on the languages or
frameworks available for building applications—for instance, the inability to
run composer install
due to a read-only filesystem. Consequently, a website
source code has to be developed in a separate (source) repository, then
assembled into a code artifact either locally or via CI, and then transferred
to the hosting provider's version control system (destination repository).
This tool facilitates such processes seamlessly: it uses a .gitignore.deployment
file to determine which files should be transferred to the destination
repository, ensuring only necessary files are included and leaving out those
specified by the ignore file.
Furthermore, since the destination repository requires a commit to incorporate
changes from the artifact (like CSS, JS, etc.), the tool offers two options for
this commit: force-push
or branch
, accommodating different workflow
preferences.
See example of deployed artifact in Artifact branches.
Modes
force-push
mode (default)
Push the packaged artifact to the same branch in the destination repository, carrying over the history from the source repository while overwriting the existing history in the destination repository.
Use case
Forwarding all changes from 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 "deployment"
commit.
branch
mode
Push packaged artifact to the new branch on each deployment, preserving history from the source repository, but requiring to trigger a deployment of newly created branch after each deployment.
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
composer require --dev drevops/git-artifact
or download the latest release from the GitHub releases page.
Usage
./git-artifact git@github.com: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.
Run in CI
See examples:
Call from CI configuration or deployment script:
export DEPLOY_BRANCH=<YOUR_CI_PROVIDER_BRANCH_VARIABLE> ./git-artifact git@github.com:yourorg/your-repo-destination.git \ --branch="${DEPLOY_BRANCH}" \ --push
See extended and fully-configured example in the Scaffold 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 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 flexibility). 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 PHPdate()
-compatibleFORMAT
.[branch]
- current branch in the source repository.[tags:DELIMITER]
- tags from the latest commit in the source repository separated by aDELIMITER
.
Maintenance
Lint and fix code
composer lint composer lint-fix
Run tests
composer test
Repository created using https://getscaffold.dev/ project scaffold template