Automatic Metadata Git Push

Shipdriver-based plugins supports pushing metadata to a remote git repository. The goal is to simplify the process for creating pull requests against OpenCPN/plugins.

When enabled, all metadata files created when the plugin is built are replicated to a fork of OpenCPN/plugins set up by the user. This fork can be used to make a PR against OpenCPN/plugins. In particular, there is no need to download metadata files from Cloudsmith in order to make a PR.

Configuration

The configuration is documented in the plugins fork configuration page

During the build

When the builders are run, the git-push part will

Make a clone of the OpenCPN/plugins fork repository
Add the new metadata file.
Commit and push the change to the auto branch in the OpenCPN/plugins fork

As mentioned, the changes are pushed to the 'auto' branch by default. The branch name can be tweaked using the GIT_BRANCH environment variable in the builder.

If GIT_KEY_PASSWORD or GIT_REPO is missing git-push will not do anything besides some logging.

Making the Pull Request (PR) to OpenCPN/plugins

The builders have made commits in the OpenCPN/plugins fork’s auto branch, one for each build. These commits are the metadata files which work with the plugin installer of the main OpenCPN program. In beta and production mode they become part of the beta and master catalogs of plugins in OpenCPN.

Syncing branches

Before making the pull request to OpenCPN/plugins make sure your fork of this is up to date. This guide has been found useful. Or on the CLI:

$ git remote update upstream
$ git checkout master
$ git rebase upstream/master
$ git checkout Beta
$ git rebase upstream/Beta

If the Beta branch isn’t used, the last two commands can be omitted.

Master catalog

Adding metadata files from the OpenCPN/plugins fork auto branch to the master branch goes like this:

$ git fetch origin auto:auto
$ git checkout auto
$ git rebase master
$ git checkout master
$ git merge --squash auto
$ git commit

The rebase operation should not be strictly necessary, but will pick up possible errors if the metadata has been changed by other means. The --squash option lumps the too many commits in the auto branch (one for each build) to a single one, keeping the master branch tidy.

A PR (pull request) can then be made from the master branch for updating the master catalog of OpenCPN/plugins.

Beta catalog

If you configured for Beta metadata files you need:

$ git fetch origin auto:auto
$ git checkout auto
$ git rebase Beta
$ git checkout Beta
$ git merge --squash auto
$ git commit

The new TideFinder metadata files have been added to your OpenCPN/plugins fork Beta branch. A PR, if accepted, results in updating the Beta catalog of OpenCPN/plugins.

Cleaning up old metadata

Normally, only the last version of the plugin should be available in the catalog. The command

    $ ls -lt metadata/my-plugin*

lists all metadata files for given plugin in date order. Use git rm to remove all older files. When completed, commit and push:

    $ git commit -m "Removing obsoleted metadata."
    $ git push

Troubleshooting

The ci/git-push script can be run manually for debugging purposes as described in the Local CI build page

Security

The private ssh key created by new-credentials is encrypted using a standard DES alghorithm. There is probably some room to crack this given the fact that part of ciphertext is known. The encryption would be stronger if the header and trailer of the key wasn’t encrypted.

That said, given the context this should be reasonably safe. At least, a separate ssh key is used for this purpose, a key which could be easily revoked.

← Shipdriver template overview