From 23fe7f4a33164070825fb8032d11390bc1afc662 Mon Sep 17 00:00:00 2001 From: JulianTrommer Date: Wed, 23 Oct 2024 15:49:30 +0200 Subject: [PATCH] Added doc for new actions --- doc/development/build_action.md | 40 ++++++++++---------------------- doc/development/linter_action.md | 21 +++++++---------- 2 files changed, 20 insertions(+), 41 deletions(-) diff --git a/doc/development/build_action.md b/doc/development/build_action.md index 6c2c9473..191f8ae2 100644 --- a/doc/development/build_action.md +++ b/doc/development/build_action.md @@ -4,16 +4,13 @@ **Summary:** This page explains the GitHub build action we use to create an executable image of our work. -- [GitHub actions](#github-actions) - - [General](#general) - - [The Dockerfile (`build/docker/build/Dockerfile`)](#the-dockerfile-builddockerbuilddockerfile) - - [The `build-and-push-image` job](#the-build-and-push-image-job) - - [1. Checkout repository (`actions/checkout@v3`)](#1-checkout-repository-actionscheckoutv3) - - [2. Set up Docker Buildx (`docker/setup-buildx-action@v2`)](#2-set-up-docker-buildx-dockersetup-buildx-actionv2) - - [3. Log in to the Container registry (`docker/login-action@v2`)](#3-log-in-to-the-container-registry-dockerlogin-actionv2) - - [4. Bump version and push tag (`mathieudutour/github-tag-action`)](#4-bump-version-and-push-tag-mathieudutourgithub-tag-action) - - [5. Get commit hash](#5-get-commit-hash) - - [6. Build and push Docker image](#6-build-and-push-docker-image) +- [General](#general) +- [The `build-and-push-image` job](#the-build-and-push-image-job) + - [1. Checkout repository (`actions/checkout@v3`)](#1-checkout-repository-actionscheckoutv3) + - [2. Set up Docker Buildx (`docker/setup-buildx-action@v2`)](#2-set-up-docker-buildx-dockersetup-buildx-actionv2) + - [3. Log in to the Container registry (`docker/login-action@v2`)](#3-log-in-to-the-container-registry-dockerlogin-actionv2) + - [4. Test building the image (`docker/build-push-action@v3`)](#4-test-building-the-image-dockerbuild-push-actionv3) + - [5. Build and push the image (`docker/build-push-action@v3`)](#5-build-and-push-the-image-dockerbuild-push-actionv3) ## General @@ -27,12 +24,6 @@ or `docker pull ghcr.io/una-auxme/paf:` to get a specific version. If action is triggered by a pull request the created image is then used to execute a test run in the leaderboard, using the devtest routes. The results of this simulation are then added as a comment to the pull request. -## The Dockerfile ([`build/docker/build/Dockerfile`](../../build/docker/build/Dockerfile)) - -The Dockerfile uses [Dockerfile+](https://github.com/edrevo/dockerfile-plus) to include -the [agent Dockerfile](../../build/docker/agent/Dockerfile) to avoid duplicate code. -The code folder is then copied into the container instead of mounting it as in our dev setup. - ## The `build-and-push-image` job ### 1. Checkout repository ([`actions/checkout@v3`](https://github.com/actions/checkout)) @@ -52,20 +43,13 @@ Logs in with `GITHUB_TOKEN` into the registry (ghcr.io). Example taken from [here](https://docs.github.com/en/actions/publishing-packages/publishing-docker-images) -### 4. Bump version and push tag ([`mathieudutour/github-tag-action`](https://github.com/mathieudutour/github-tag-action)) - -If the current commit is on the `main` branch, this action bumps the version and pushes a new tag to the repo. - -Major releases can be done manually (e.g. `git tag v1.0.0`). - -### 5. Get commit hash +### 4. Test building the image ([`docker/build-push-action@v3`](https://github.com/docker/build-push-action/)) -If Step 4 was skipped, this step gets the commit hash of the current commit, to be used as a tag for the Docker image. +Tries to build the image without pushing it to the repository packages if the workflow was triggered with a pull request. -### 6. Build and push Docker image +### 5. Build and push the image ([`docker/build-push-action@v3`](https://github.com/docker/build-push-action/)) -Build and push the image to the registry. To avoid large downloads of the base image +This action builds the image and pushes it to repository under the `latest` tag if the workflow was triggered with a merge to the `main` branch. +To avoid large downloads of the base image the [GitHub Actions cache](https://docs.docker.com/build/building/cache/backends/gha/) is used to cache the image after build. -If the action is run on a branch other than `main`, the image is tagged with the commit hash from Step 5. -Otherwise, the image is tagged with both the tag created in Step 4 and `latest`. diff --git a/doc/development/linter_action.md b/doc/development/linter_action.md index e52a00ef..c934d45e 100644 --- a/doc/development/linter_action.md +++ b/doc/development/linter_action.md @@ -4,29 +4,24 @@ **Summary:** This page explains the GitHub lint action we use to unsure Code quality. -- [GitHub actions](#github-actions) - - [General](#general) - - [Pull requests](#pull-requests) - - [🚨 Common Problems](#-common-problems) - - [1. Error in the markdown linter](#1-error-in-the-markdown-linter) - - [2. Error in the python linter](#2-error-in-the-python-linter) +- [General](#general) +- [Pull requests](#pull-requests) +- [🚨 Common Problems](#-common-problems) + - [1. Error in the markdown linter](#1-error-in-the-markdown-linter) + - [2. Error in the python linter](#2-error-in-the-python-linter) ## General We use a GitHub action to verify code quality. These actions are defined in `.github/workflows/linter.yml` and `.github/workflows/format.yml`. -The actions are executed only on pull requests in order not to exceed the [minutes per month included in the Github](https://docs.github.com/en/billing/managing-billing-for-github-actions/about-billing-for-github-actions) free plan. -This is done by limiting the execution of the action by the following line: - -```yaml -on: pull_request -``` +The actions are executed on pull requests and on merges to the main branch. +This should not lead to issues regarding the [GitHub billing plan](https://docs.github.com/en/billing/managing-billing-for-github-actions/about-billing-for-github-actions). If any issues are encountered the linter action can also be run on the self-host runner. The actions use the same linters described in the section [Linting](./linting.md). Event though the linters are already active during development, -the execution on pull request ensures that nobody skips the linter during commit. +the execution ensures that nobody skips the linter during commit. ## Pull requests