Skip to content

How CI works

Jump to bottom
accetto edited this page Sep 11, 2022 · 6 revisions

How CI works

Updated: 2022-09-11

Warning

It seems like the README publishing is currently not always working. Some changes on the Docker Hub side seem to be the reason. However, you can always copy the content generated by the utility util-readme.sh (preview command) to the Docker Hub manually.

Introduction

This page describes how the continuos integration infrastructure (CI) of this project works.

Before reading this page it can be helpful to read the pages Concepts of building, Building stages and How building works first.

The CI in this project is very simple and lightweight. It introduces no additional dependencies and almost no additional code. It uses the same building pipeline and the same resources as the non-CI building process.

It is not mandatory to use the CI infrastructure. The same images can be built manually on the local stage or semi-manually on the Docker Hub stage.

Features of the implemented CI include the following:

  • Image re-building and re-publishing can be triggered periodically by a scheduler or ad-hoc by publishing a new release on the GitHub.

  • Images are actually published only if something essential has changed since the previous release. This behavior can be overridden.

  • Image README files are published after the images has been published.

  • Image README files are actually published only after the images has been actually pushed into their deployment repositories on the Docker Hub. This behavior can be overridden.

The CI infrastructure utilizes the GitHub Actions workflows. However, to minimize the dependencies, no third-party Actions from the GitHub Marketplace are used. All necessary code is in the scripts included in this project.

CI concept

The CI concept is very simple and can be described as a sequence of the following steps:

  1. A GitHub Actions event triggers the auto-build workflow.
  2. The auto-build workflow triggers the build rules on the Docker Hub stage by calling the Docker Hub webhook.
  3. The auto-builder on the Docker Hub stage executes the post_push hook script, which triggers the post-push workflow on the GitHub.
  4. The post-push workflow generates an updated README file and publishes it on the Docker Hub.

CI environment

The CI infrastructure uses the same environment as the standard building pipeline.

However, some secrets are specific to the CI workflows and they must be defined as GitHub Actions secrets.

Such secrets will be mentioned also bellow by the workflows that use them. However, they are all described on the page Building stages.

CI workflows

The CI file structure looks like this:

  • .github/
    • workflows/
      • dockerhub-autobuild.yml
      • dockerhub-post-push.yml
      • deploy-readme.sh

Actually, only the workflow dockerhub-autobuild.yml is purely for the CI. The other artifacts are parts of the standard building pipeline.

Workflow dockerhub-autobuild.yml

This GitHub Actions workflow is the only code, which is specific to the CI.

The workflow is very simple. It only triggers the image building on the Docker Hub stage by calling the webhook in the builder repository.

The workflow itself can be triggered by any event supported by the GitHub Actions infrastructure.

For example, it can be triggered periodically by the GitHub Actions scheduler (e.g. "every Sunday at 2:15 AM") or ad-hoc by publishing a new release on the GitHub.

The workflow uses the following GitHub Actions secrets:

If you use multiple builder repositories, then you have to trigger the auto-building in all those repositories. By extending the workflow, use the naming pattern described on the page Building stages.

For example:

### excerpt
- name: Call webhook
  shell: bash
  run: |
    echo "Call webhook"
    curl -X POST -s -o /dev/null --write-out "%{http_code}" ${{ secrets.DockerHubWebhookBuildRelease }}
    if [ -n "${{ secrets.DockerHubWebhookBuildRelease_1 }}" ] ; then 
      curl -X POST -s -o /dev/null --write-out "%{http_code}" ${{ secrets.DockerHubWebhookBuildRelease_1 }}
    fi

Workflow dockerhub-post-push.yml

This workflow is not specific to the CI. It is part of the standard building pipeline.

The workflow generates the updated README files and publishes them on the Docker Hub. The actual publishing is implemented in the script deploy-readme.sh.

This workflow is intended to be used by building on the Docker Hub stage, even it can be used also locally.

However, there is also the utility util-readme.sh, which does the same and also offers some additional features. It allows previewing and length-proofing of the final README files.

The workflow is triggered by the GitHub Actions dispatch event, so it can be started also manually on GitHub.

The workflow is also very simple, because it only executes the script deploy-readme.sh, which does all the work.

The workflow uses the following GitHub Actions secrets:

Script deploy-readme.sh

This script generates the updated final README files and publishes them on the Docker Hub.

It is a standard bash script, which has no special dependencies or requirements. Everything is done using usual Linux utilities, e.g. curl.

The script itself works similar to the utility util-readme.sh. However, it does not implement the previewing and the length-proofing.

Clone this wiki locally