Skip to content

README.md

Latest commit

 

History

History
208 lines (160 loc) · 5.85 KB

README.md

File metadata and controls

208 lines (160 loc) · 5.85 KB
Raw

IGAnets organization configuration

This repository contains shared GitHub configuration for the IGAnets organization. Its main purpose is to keep CI/CD behavior consistent across IGAnets repositories by providing reusable GitHub Actions workflows.

The organization profile displayed at github.com/iganets is maintained separately in profile/README.md.

Reusable workflows

Workflows are called from a repository-level workflow using this form:

jobs:
  example:
    uses: iganets/.github/.github/workflows/<workflow>.yml@main

The caller controls when the workflow runs. The reusable workflow contains the implementation of the job itself.

Docker image publishing

docker.yml builds and publishes four multi-platform images to the GitHub Container Registry:

Default image Dockerfile Build target Platforms
ghcr.io/iganets/iganets:cpu Dockerfile.cpu Final stage linux/amd64, linux/arm64
ghcr.io/iganets/iganets:cpu-dev Dockerfile.cpu dev linux/amd64, linux/arm64
ghcr.io/iganets/iganets:cuda Dockerfile.cuda Final stage linux/amd64, linux/arm64
ghcr.io/iganets/iganets:cuda-dev Dockerfile.cuda dev linux/amd64, linux/arm64

The development images retain the source tree, build tree, compiler toolchain, and other files from the dev Docker stage. The final-stage images contain the installed runtime.

Example caller:

name: Build and publish Docker images

on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  contents: read
  packages: write

jobs:
  docker:
    uses: iganets/.github/.github/workflows/docker.yml@main
    with:
      IGANET_BUILD_TYPE: Release
      IGANET_BUILD_CPUONLY: "OFF"
      IGANET_BUILD_DOCS: "OFF"
      IGANET_BUILD_PCH: "ON"
      IGANET_OPTIONAL: "examples;python"
      IGANET_WITH_GISMO: "OFF"
      IGANET_WITH_MATPLOT: "OFF"
      IGANET_WITH_MPI: "OFF"
      IGANET_WITH_OPENMP: "ON"
      IMAGE_NAME: iganets

The workflow uses the caller's GITHUB_TOKEN; no registry password is needed. The caller must grant contents: read and packages: write.

Docker inputs

Input Default Description
IGANET_BUILD_TYPE Release CMake build type
IGANET_BUILD_CPUONLY OFF Enable a CPU-only IGAnets build
IGANET_BUILD_DOCS OFF Build the documentation
IGANET_BUILD_PCH ON Build precompiled headers
IGANET_OPTIONAL Empty Semicolon-separated optional modules
IGANET_WITH_GISMO OFF Enable G+Smo support
IGANET_WITH_MATPLOT OFF Enable Matplot++ support
IGANET_WITH_MPI OFF Enable MPI support
IGANET_WITH_OPENMP ON Enable OpenMP support
IMAGE_NAME iganets GHCR package name, without owner or registry
CPU_TAG cpu CPU runtime image tag
CPU_DEV_TAG cpu-dev CPU development image tag
CUDA_TAG cuda CUDA runtime image tag
CUDA_DEV_TAG cuda-dev CUDA development image tag
CPU_DOCKERFILE Dockerfile.cpu CPU Dockerfile path
CUDA_DOCKERFILE Dockerfile.cuda CUDA Dockerfile path
BUILD_CONTEXT . Docker build context

Values passed to CMake-style ON/OFF inputs should be quoted so YAML treats them as strings. Quote IGANET_OPTIONAL as well when it contains semicolons.

GitLab synchronization

gitlab-sync.yml mirrors the complete Git repository, including all branches and tags, to a GitLab repository.

Example caller:

name: GitLab Sync

on:
  - push
  - delete

jobs:
  sync:
    uses: iganets/.github/.github/workflows/gitlab-sync.yml@main
    secrets:
      GITLAB_REPO_TOKEN: ${{ secrets.GITLAB_REPO_TOKEN }}
      GITLAB_REPO_URL: ${{ secrets.GITLAB_REPO_URL }}
      GITLAB_REPO_USERNAME: ${{ secrets.GITLAB_REPO_USERNAME }}

Configure the three referenced secrets in the calling repository. The GitLab token must have permission to push to the target repository.

CMake build and test

cmake-multi-platform.yml builds and tests an IGAnets CMake project using:

  • GCC and Clang on Ubuntu
  • Clang on macOS
  • LibTorch CPU

Example caller:

name: CMake CI

on:
  - push
  - pull_request

jobs:
  test:
    uses: iganets/.github/.github/workflows/cmake-multi-platform.yml@main
    with:
      IGANET_OPTIONAL: "examples"

IGANET_OPTIONAL is optional and accepts the same semicolon-separated module list used by the IGAnets CMake configuration.

Documentation deployment

gh-pages.yml configures the project with documentation enabled, generates the Doxygen/Sphinx documentation, and deploys the result to GitHub Pages.

Example caller:

name: Publish documentation

on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  contents: write
  pages: write
  id-token: write

jobs:
  docs:
    uses: iganets/.github/.github/workflows/gh-pages.yml@main
    with:
      IGANET_OPTIONAL: "examples"

GitHub Pages must be configured to use GitHub Actions as its deployment source in the calling repository.

Repository layout

.
├── .github/
│   └── workflows/          # Reusable organization workflows
├── profile/
│   └── README.md           # Public organization profile
└── README.md               # Contributor documentation

Maintenance

Changes to a workflow referenced with @main are immediately used by every calling repository. Test changes with a branch reference in a caller before merging them:

uses: iganets/.github/.github/workflows/docker.yml@my-workflow-branch

For reproducible or security-sensitive callers, reference a release tag or commit SHA instead of @main.