How to fork
Updated: 2020-12-31
This page describes what is needed to be created and configured after forking or cloning this GitHub repository.
Before reading this page it can be helpful to read the pages Concepts of building, Building stages, How building works and How CI works first.
This GitHub repository is the main part of a small automated engine for building sets of configurable Docker images and for publishing them on Docker Hub.
The complete engine consist of the following parts:
- One main GitHub repository containing all the resources except the selected Docker image metadata
- One main Docker Hub repository used as the builder repository fo building the images
- One or more Docker Hub repositories used as the deployment repositories for publishing the images
- One GitHub gist belonging to the builder repository
- One GitHub gist belonging to all the deployment repositories
The main GitHub repository (actually this repository accetto/ubuntu-vnc-xfce-g3) is created by forking or cloning it from GitHub the usual way.
The repository contains all necessary resources for building the Docker images except the selected image metadata, that are stored externally by intention.
You can keep this repository private or public.
The first thing you have to do after forking or cloning the repository is to adjust the hook source file env.rc. This is the only file you have to modify to your needs.
You have to replace the repository owner accetto by your account name:
declare _owner="accetto"Then you have to replace the name of the builder repository dev-ubuntu-vnc-xfce-g3 by the name of your builder repository:
DOCKER_REPO=${DOCKER_REPO:-${_owner}/dev-ubuntu-vnc-xfce-g3}If you have renamed the main GitHub repository after cloning it, then you have to adjust the name and maybe also the branch of the GitHub repository containing the CI workflows. In the original code it is the repository ubuntu-vnc-xfce-g3 and the master branch:
POST_PUSH_WORKFLOW_REPO=${POST_PUSH_WORKFLOW_REPO:-"ubuntu-vnc-xfce-g3"}
POST_PUSH_WORKFLOW_BRANCH=${POST_PUSH_WORKFLOW_BRANCH:-"master"}The last thing you have to adjust are the names of the deployment repositories. Modify the code lines that look like the following ones from the original code:
_deploy_repo="${_owner}/ubuntu-vnc-xfce-g3"
_deploy_repo="${_owner}/ubuntu-vnc-xfce-chromium-g3"
_deploy_repo="${_owner}/ubuntu-vnc-xfce-firefox-g3"After these changes the engine will use your GitHub repository, your Docker Hub builder repository and your CI workflows. It will also publish the images to your Docker Hub deployment repositories.
Strictly speaking, you could go also without the builder repository, if you would prefer to build the images only locally and push them into the deployment repositories from the local stage. However, this is not the primary scenario of this project and it will not be described here.
It is also possible to use the same Docker Hub repository as the builder and deployment repository. This scenario will also not be described here.
After forking or cloning the repository you have to create the following secrets in the repository (section Settings/Secrets):
- DockerHubWebhookBuildRelease (webhook)
- DOCKERHUB_USERNAME
- DOCKERHUB_PASSWORD
The detailed description is on the page Building stages.
Additionally to the repository secrets described above you need to create also the following secret personal access tokens (PTA):
- one PTA with the scope
gist(for the environment variable GIST_TOKEN) - one PTA with the scopes
repoandworkflow(for the environment variable POST_PUSH_WORKFLOW_TOKEN)
The actual names of these tokens is not important. Only their values need to be stored into the related environment variables.
The detailed description is on the page Building stages.
It should be understood, that the personal access tokens (PTA) are created not per repository, but per GitHub account. These tokens could have access to all gists, workflow and repositories of the same GitHub account (owner). Therefore they should be handled as secrets.
The personal access tokens should be created in the section Settings/Developer settings/Personal access tokens.
The main Docker Hub repository plays the role of builder repository (currently accetto/dev-ubuntu-vnc-xfce-g3).
It is used for building all the images that are then published to their own deployment repositories.
You have to create this repository on Docker Hub the usual way and you have to connect it to the main GitHub repository described above.
After entering the edit mode by clicking the button Configure Automated Builds on the Builds tab you have to create the following objects:
- build rules for each blend you want to build
- environment variables
- build trigger (webhook)
The detailed description is on the page Building stages.
You can keep this repository private or public. However, the repository is intended only for building and development, not for public use.
You don't need to create any secrets or personal access tokens (PTA) in this repository.
However, after creating the GitHub gists (see bellow), you will need to come back and store the gist ID values into the related environment variables GIST_ID and DEPLOY_GIST_ID.
You have to create one or more deployment repositories, where the images will be published.
Strictly speaking, you could use the same repository for building and deployment, but you would need to do some adjustments in the hook source file env.rc. You would also need to care about avoiding possible conflicts by naming the images and tags.
For example, the current project uses the following deployment repositories:
- for the base images (accetto/ubuntu-vnc-xfce-g3)
- for the images with Chromium Browser (accetto/ubuntu-vnc-xfce-chromium-g3)
- for the images with Firefox Browser (accetto/ubuntu-vnc-xfce-firefox-g3)
After creating the deployment repositories the usual way you don't need to do anything else. No further configuration is needed.
The deployment repositories do not need to be connected to the main GitHub repository and they can be kept public or private.
You don't need to create any secrets or personal access tokens (PTA) in deployment repositories.
The last thing you have to do, is to create two GitHub gists.
One gist will belong to the builder repository and the other one to the deployment repositories.
It makes no difference which one will become which. The actual assignment is done by storing their ID values into the related variables GIST_ID and DEPLOY_GIST_ID in the builder repository (see above). For building on the local stage they are also stored in the very same environment variables.
The gist ID value can be extracted from its URL.
However, to make the gist assignments more obvious, I recommend to create the first file in each gist manually and use for it some name, which will keep it always at the top position.
For example, in the current project it looks like this:
The gists require no further configuration and even creating the first file manually is not required. All content will be maintained automatically by the building pipeline.
You can keep both gists public or secret.
However, be aware that the secret gists are not really secret, because you can always access them if you know their ID values. These are used, for example, in badge links in README files.
It should be understood, that the gist belonging to the deployment repositories merely stores the metadata (e.g. badge endpoints) of the published images. It is maintained by the building pipeline, but it does not participate in decision making if an image needs to be refreshed. Only the verbose version sticker values from the gist belonging to the builder repository are taken into consideration.