Commit, tag and push the record of a run #

After every run with --apply, the failed ones too, the migration engine writes the environment's status file and the run's log, commits both, tags the commit and pushes commit and tag. This gives every environment a history in git that anyone with a clone can read. This page sets it up and shows what to do when a push fails.

What you'll have at the end #

• [RepositorySettings] set for your installation, in the site's repository or a separate one;
• runs that end with Repository: commit ..., tag ..., push pushed;
• a cronjob or a command that pushes what could not be pushed.

Before you start #

• git_manager is installed and active: commits go through it. Without it a run says git_manager is not active: the record of the run is not committed and commits nothing.
• The system user that runs migrations can push to the remote (an SSH key or a credential helper). Nothing is stored by the migrations.

Steps #

1. Choose the repository #

<?php /* #?ini charset="utf-8"?
# settings/override/migration.ini.append.php
[RepositorySettings]
Mode=site
Path=migrations
Remote=origin
Branch=
*/ ?>

Branch empty means the branch the repository is on; a repository on another branch, or on no branch, is not committed to, and the report says why.

2. Choose the tag names #

[RepositorySettings]
Tag=enabled
TagPattern=migrations/<environment>/<run-id>

The placeholders are <environment> (default when the installation names none), <run-id> and <date> (YYYYMMDD). Keep <run-id> in the pattern: a tag that exists is never moved or replaced. A pattern that gives the same name twice (only <date>) leaves the second commit untagged, with the warning the tag <name> exists already: it is never moved, the commit stays untagged.

3. Run and read the repository line #

./console exp:migration:migrate --apply

Repository: commit 4e1f0a9c2b7d, tag migrations/production/20261101-120000-b2c3d4, push pushed

The commit message lists what the run did:

Updated: Migration run 20261101-120000-b2c3d4 in production: 1 applied

- applied site:20261101090000_news_note_priority

4. Push what failed again #

A failed push does not fail the run. The run's push_state is pending, and exp:migration:status warns 1 run(s) wait for their push: ./console exp:migration:push --apply.

./console exp:migration:push
./console exp:migration:push --apply --limit=20

Exponential migrations: push
  pending  20261101-120000-b2c3d4
Pushed 1 of 1 tried, 0 still pending

5. Let cron push #

The cronjob part migrationpush is in no default part. Add it to one the site runs, or run it on its own:

<?php /* #?ini charset="utf-8"?
# settings/override/cronjob.ini.append.php
[CronjobPart-migrationpush]
Scripts[]=migrationpush.php
*/ ?>

php runcronjobs.php migrationpush

It does nothing while no run waits.

6. Read the tags #

git fetch --tags
git tag -l 'migrations/production/*' --sort=version:refname | tail -5
git show migrations/production/20261101-120000-b2c3d4 --stat

Sort with --sort=version:refname (or sort -V), never by name alone.

Switching parts off #

A development installation often runs with Push=disabled; staging and production with all three on.

Check it #

exp:migration:status shows no run waiting for its push, and git ls-remote --tags origin 'migrations/*' lists the tag of the last run.

Next step #

Upgrade step or migration?: which of the two tools a change belongs in.

Related pages #

• Migrations: the hub · All recipes
• The guide, the tutorial, PHP migrations
• In the administration, Commands, Settings
• The file format
• When a migration fails, Troubleshooting messages
• Migrations versus migrating a site
• The migrations repository, migration.ini [RepositorySettings], exp:migration:push, the cronjob part migrationpush
• Team workflow with git, The audit trail of runs
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.