Well-manageable and well-maintainable repository template.
Highly automated, up-to-date, and well-documented repository template.
Checks for common problems, Markdown, YAML, Bash, formats, lints, and tests before committing or pushing so you don’t have any surprises at CI or when releasing your code to GitLab and GitHub!
The project is under active development.
The purpose is to have a template repository and to have it well-manageable and well-maintainable by both human beings and automation tools.
The rationale behind this is that taking care of tens or hundreds of repositories while keeping them working, tidy, consistent, and up-to-date, might be a daunting task.
The way how to achieve the desired state of manageability and maintainability is to unify and automate workflow to allow frequent small changes for multiple projects at scale.
Objectives:
Strategies and tactics to achieve objectives:
Optimized for GitHub flow, easily adjustable to GitLab flow or any other workflow.
commit scans committed codebase change, git push scans pushed codebase change, and GitLab CI scans the whole codebase, and the hooks are appliedcommit (both regular and merge) is normalized, checked, and tested:push is checked, and tested:release commits)[ci skip] or [skip ci], using any capitalization, or pass git push option ci.skip (git push -o ci.skip git >= 2.17, git push --push-option=ci.skip git >= 2.10)SKIP variable to a comma-separated list of skipped hooks, for example, SKIP=forbid-new-submodules,gitlab-ci-linter git commitpre-commit run -a --hook-stage manualfeat or fix commit is present, GitLab CI job release publishes release using semantic-release/semantic-release
scripts/setup setups commit-msg, pre-commit, pre-merge-commit, and pre-push hooksscripts/bootstrap installs dependenciesscripts/test runs tests, as arguments accepts test files or test sets (see *.bats or *.set files at the tests directory)scripts/update updates used dependencies
Release branches must match regex ^(((0|[1-9]\d*)\.)(((0|[1-9]\d*|x)\.)?x)|main|next(-major)?|beta|alpha)$, see https://regex101.com/r/gH9dCG/2.
When feat or fix commit is present in the merge (to be more precise since the last release tag) to main, next, next-major, beta, alpha, major.x, or major.minor.x branch, the publish release:
[skip release] or [release skip] in the commit messagePre-commit is by default configured to run these hooks:
wip, todo, or tbd at the commit message title.gitlab-ci.yml file using devopshq/gitlab-ci-linter when GL_TOKEN environment variable is set to GitLab Personal Tokenwip, todo, or tbd preceded with # at a text file, checked by regex (?i)#\s*\b(wip|todo|tbd)\b, see https://regex101.com/r/mKueFx/1Tests are written using BATS - GitHub - bats-core/bats-core: Bash Automated Testing System, GitHub - bats-core/bats-support: Supporting library for Bats test helpers, GitHub - bats-core/bats-assert: Common assertions for Bats, and GitHub - bats-core/bats-file: Common filesystem assertions for Bats and organized in test sets.
Test set is a simple text file format. Each line must begin or end without leading or trailing whitespace. Each line should contain included test sets (*.set), test files to be run (*.bats), comments starting with # as the first character on the line, or empty lines. File paths are relative to the test set file.
Example:
# Commented and empty lines are ignoredanother.setscript1.batsscript2.batsscript3.bats
Clone the project with --recursive option, run scripts/bootstrap as root to install dependencies, scripts/setup for a complete setup, and adjust to Your needs. Make sure GL_TOKEN: GitLab Personal Access Token with scope api is present, otherwise gitlab-ci-linter is skipped. To load secrets you can use shell extension like direnv, encryption like SOPS, or secrets manager HashiCorp Vault, please make sure you won’t commit your secrets.
Example:
git clone --recursive git@gitlab.com:xebis/repository-template.gitcd repository-templatesudo scripts/bootstrapscripts/setup
Run scripts/update from time to time to update repository dependencies.
To create working GitLab to GitHub repository synchronization:
GitLab GitHub Sync, with scopes:repo (and repo:status, repo_deployment, public_repo, repo:invite, security_events)workflowwrite:packages (and read:packages)delete:packagesGitLab GitHub Sync tokenSet up release and GitLab CI Linter tokens as the GitLab group or the GitLab project variable:
api and write_repository.lint is skipped on non-protected branches.GH_TOKEN: GitHub Personal Access Token with at least scopes repo for a private repository or public_repo for a public repository.
Settings
GL_TOKEN or GH_TOKENSet up the GitLab scheduled pipeline:
Simply fork the repository at GitLab or GitHub, delete all git tags, and tag the last commit to the desired starting version, e.g. v0.0.0. Clone the repository with --recursive option, run sudo scripts/bootstrap, scripts/setup, scripts/update, at .pre-commit-config.yaml replace gitlab-ci-linter project with your project, and enjoy!
git commit, or git merge runs checks on changed files and runs fast test setgit push runs checks on all files and runs reduced test setpush, merge request runs checks on all files and runs full test setmerge to main runs checks on all files, runs full test set, and publishes a new version releaseschedule runs checks on all files, runs nightly test setscripts/update manually from time to time to update repository dependenciesFor usage examples, you might take a look at:
Please read CONTRIBUTING for details on our code of conduct, and the process for submitting merge requests to us.
scripts/test fullMake sure all scripts/*, git hooks, and GitLab pipelines work as expected, testing checklist:
scripts/* scripts - covered by unit tests tests/*
git commit runs pre-commit hook-type commit-msg and scripts/pre-commitgit mergemerge commit runs pre-commit hook-type commit-msg and scripts/pre-commitmerge commit runs pre-commit hook-type commit-msg and scripts/pre-commitgit push runs scripts/pre-pushpre-commit run -a --hook-stage manual runs all hooks and check-hooks-apply hook fails on check-symlinks and forbid-binarymain branch runs validate:lint and validate:test-*-fullmain branch runs validate:lint, validate:test-*-full, and release:releasefeat or fix commit releases a new version in GitHub and GitLab
validate:lint and validate:test-*-nightlyTo test your changes in a different environment, you might try to run a Docker container and test it from there.
Run a disposal Docker container:
sudo docker run -it --rm -v "$(pwd)":/repository-template alpine:latestsudo docker run -it --rm -v "$(pwd)":/repository-template --entrypoint bash node:latestIn the container:
cd repository-template# Set variables GL_TOKEN and GH_TOKEN when needed# Put here commands from .gitlab-ci.yml job:before_script and job:script# For example job test-full:apk -U upgradeapk add batsbats tests# Result is similar to:# 1..1# ok 1 dummy test
local hook shellcheck - shellcheck has duplicated parameters from .shellcheckrc, because these are not taken into accountapk, pip, and npm