Skip to content

OpenCPN Plugins Catalog and Github Integration

Jump to bottom
Rasbats edited this page May 3, 2021 · 29 revisions

Shipdriver-based plugins have experimental support for 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

Prerequisites:

To enable this support which copies metadata from TideFinder to the OpenCPN/plugins fork:

  1. Create a branch called auto in the OpenCPN/plugins fork:

    • For builds targeting the master catalog: drop possible existing auto branch and create a new on top of master:

      $ git branch -D auto                    # If it exists, ignore possible error messages
$ git remote update upstream            # Pick up latest version of upstream
$ git checkout -b auto upstream/master  # Create new branch on top of master:
$ git push -f origin auto:auto          # push to clone, overwrite old branch.

    • Builds targeting the beta catalog is handled in a similar way:

      $ git branch -D auto                    # Drop the auto branch completely
$ git remote update upstream            # Better safe than sorry
$ git checkout -b auto upstream/Beta    # Create a new auto branch based on Beta
$ git push -f origin auto:auto          # Unconditionally overwrite the github branch

  2. Run the script ci/new-credentials in the TideFinder repo. The script will ask for the ssh url to your plugins fork repo and a secret password. The ssh url can be found in the Github UI:

    1.plugins.jpg

  3. Dont forget the password...

  4. The script will create an encrypted private + a public key in the TideFinder ci directory. Commit and push these to Github:

    $ git add ci/*.enc ci/*.pub
$ git commit -m "Add git deployment key."
$ git push origin master:master

  5. Register the new public key (displayed by new-credentials) as a deployment key with write permissions (Allow write access) on your github OpenCPN/plugins fork repo (in Settings | Deploy keys):

    10.deploy.key.jpg

    After adding the key things should look like:

    9.deploy.key.jpg

  6. Set environment variables in all builders like Circleci, drone.io and Appveyor:

    • GIT_KEY_PASSWORD: Password entered to new-credentials.
    • GIT_REPO: The ssh-based url to your OpenCPN/plugins clone, the same as entered to new-credentials.

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 master branch

Before making the pull request to OpenCPN/plugins make sure your fork of this is up to date, and that the remote upstream exists. This guide has been found useful. Or on the CLI (creating the upstream remote, the first line, is only required the first time):

$ git remote add upstream https://github.com/OpenCPN/plugins.git
$ git remote update upstream
$ git checkout master
$ git rebase upstream/master

Master catalog

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

$ git checkout auto
$ git rebase master
$ git checkout master
$ git merge --squash auto
$ git commit
$ git push

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.

Syncing Beta branch

Before making the pull request to OpenCPN/plugins make sure your fork of this is up to date, and that the remote upstream exists. This guide has been found useful. Or on the CLI (creating the upstream remote, the first line, is only required the first time):

$ git remote add upstream https://github.com/OpenCPN/plugins.git
$ git remote update upstream
$ git checkout Beta
$ git rebase upstream/Beta

Beta catalog

Make sure you have fetched the auto and Beta branches from the OpenCPN/fork to the clone on your PC.

Using GitHub Desktop it was necessary to delete the local plugins folder and clone again.

If you configured for Beta metadata files you need:

$ git checkout auto
$ git rebase Beta
$ git checkout Beta
$ git merge --squash auto
$ git commit
$ git push

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.

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.

Bugs

Probably plenty.

Return to the main guide

Clone this wiki locally