GitLab | Docs
Self-hosted GitLab EE|CE
-
GitLab package (Omnibus) | Install
Omnibus GitLab architecture and components : Omnibus GitLab is a customized fork of the Omnibus project from Chef (
omnibus-gitlab
), and it uses Chef components like cookbooks and recipes to perform the task of configuring GitLab on a user’s computer. Omnibus GitLab repository on GitLab.com hosts all the necessary components of Omnibus GitLab. These include parts of Omnibus that are required to build the package, like configurations and project metadata, and the Chef related components that are used in a user’s computer after installation.- Runit, a lightweight init system (predates
systemd
), is the service supervisor of GitLab Omnibus. The termrunsvdir
refers to a Runit component that handles serivce directories (svdir
) created by Runit. So, while GitLab usessystemd
, service supervision is delegated to Runit. | ChatGPT- See
/opt/gitlab/sv/*
- See
- Runit, a lightweight init system (predates
Single-node : Up to 20 RPS or 1,000 users | GitLab Single Server Architecture
Multi-node : Up to 40 RPS or 2,000 users
⋮
Cloud native hybrid : Single- or Multi- node
GitLab Operator : a K8s Operator (Not for production)
Releases :
/-/raw/<OPERATOR_VERSION>/CHART_VERSIONS
Operator Chart GitLab 1.4.2 8.4.2 v17.4.2 1.4.2 8.3.5 v17.3.5 1.4.2 8.2.9 v17.2.9 - Docs
gitlab-org/cloud-native
- Installation :
gitlab-org/cloud-native
|docs.gitlab.com
- Ingress : Ingress-NGINX Controller (forked chart).
- TLS :
cert-manager
- Auth by LDAP, SAML, and OAuth
Install & Configure : /etc/gitlab/gitlab.rb
# Install the package (RPM)
sudo dnf install -y gitlab-ee
# Else also inject configuration parameter(s) here (imperatively)
host=gitlab.local # Example; add/edit DNS record(s) of (sub)domain as apropos
sudo EXTERNAL_URL="https://$host" dnf install -y gitlab-ee
# Configure (further) declaratively (optional actually, but advised)
sudo vi /etc/gitlab/gitlab.rb
# Apply (re)configuration (REQUIRED; runs many Chef recipes)
gitlab-ctl reconfigure
# Verify the service is active (optional)
systemctl status gitlab-runsvdir.service # "status" else "is-active"
# Restart (optional)
gitlab-ctl restart [nginx] # All else one component by subcommand
- LDAP synchronization
Group sync : If your LDAP supports the
memberof
property, when the user signs in for the first time GitLab triggers a sync for groups the user should be a member of. ... group sync process runs every hour on the hour, andgroup_base
must be set in LDAP configuration for LDAP synchronizations based on groupCN
to work. This allows GitLab group membership to be automatically updated based on LDAP group members. :/etc/gitlab/gitlab.rb
:gitlab_rails['ldap_servers'] = { 'main' => { 'group_base' => 'ou=groups,dc=example,dc=com', } }
External groups :
/etc/gitlab/gitlab.rb
gitlab_rails['ldap_servers'] = { 'main' => { 'external_groups' => ['interns', 'contractors'], } }
- External users : This feature may be useful when for example a contractor is working on a given project and should only have access to that project. Such users are best handled as members of "External groups" (above).
- Features:
- Cannot create project, groups, and snippets in their personal namespaces.
- Can only create projects (including forks), subgroups, and snippets within top-level groups to which they are explicitly granted access.
- Can access public groups and public projects.
- Can only access projects and groups to which they are explicitly granted access. External users cannot access internal or private projects or groups that they are not granted access to.
- Can only access public snippets.
- Methods to set user as "External user":
- LDAP groups
- See "External groups" section above.
- SAML groups
- OmniAuth: Supported providers includes AuthO, AWS Cognito, Atlassian, GitHub, GitLab.com, Google, and …
- JWT
- OpenID Connect (OIDC)
- Generic OAuth2
- SAML
- Kerberos
- LDAP groups
- Features:
Upon any (re)configuration
Running "
gitlab-ctl reconfigure
" is the advised and standard method to apply changes made to/etc/gitlab/gitlab.rb
. This command ensures that all configuration changes are correctly applied across all GitLab components and services.
# Apply the reconfiguration
gitlab-ctl reconfigure
# Verify service is active
systemctl is-active gitlab-runsvdir.service
# Or, for more info
systemctl status gitlab-runsvdir.service
Install GitLab on K8s
Install GitLab : operator and app
Install GitLab Operator
Helm method
v=8.4.2 # Chart
# Download for offline install
helm pull gitlab/gitlab-operator --version $v
# Install the Operator
helm repo add gitlab https://charts.gitlab.io
helm repo update
helm update gitlab-operator gitlab/gitlab-operator \
--install \
--version $v \
--create-namespace \
--namespace gitlab-system
Manifest method
v=1.4.2 # Operator
url=https://gitlab.com/api/v4/projects/18899486/packages/generic/gitlab-operator/$v/gitlab-operator-kubernetes-$v.yaml
curl -sSLO $url
kubectl apply -f gitlab-operator-kubernetes-$v.yaml
Install GitLab (app)
Manifest method (only).
# Install the app : GitLab (CRD)
crd=gitlab
vi $crd.yaml # Configure for version and domain at least
kubectl -n gitlab-system apply -f $crd.yaml
# Monitor install process
kubectl -n gitlab-system get gitlab
kubectl -n gitlab-system logs deployment/gitlab-controller-manager -c manager -f
# Teardown
kubectl -n gitlab-system delete -f $crd.yaml
@ gitlab.yaml
apiVersion: apps.gitlab.com/v1beta1
kind: GitLab
metadata:
name: gitlab
spec:
chart:
## https://gitlab.com/gitlab-org/cloud-native/gitlab-operator/-/raw/1.4.2/CHART_VERSIONS
version: "8.4.2" # Chart
values:
global:
hosts:
domain: gitlab.k8s.local # use a real domain here
ingress:
configureCertmanager: true
certmanager-issuer:
email: admin@gitlab.k8s.local # use your real email address here
GitLab Agent for Kubernetes
CI/CD Pipelines
Reference: "GitLab CICD Intermediate" [2023]
- GitLab CE Server (+Web GUI) | Linode VM @ 4 CPU / 8 Gi Memory
- GitLab Runner (Golang) | Linode VM @ 2 CPU / 4Gi Memory See "3. Install GitLab Runner on Linux"
- Install GitLab Runner | Linux
- GitLab Runner Operator The GitLab Runner operator manages the lifecycle of GitLab Runner in Kubernetes or Openshift clusters. The operator aims to automate the tasks needed to run your CI/CD jobs in your container orchestration platform.
- Use the agent to install GitLab Runner
- Connecting a Kubernetes cluster with GitLab Connect your K8s cluster with GitLab to deploy, manage, and monitor your cloud-native solutions. To connect a Kubernetes cluster to GitLab, you must first install an agent in the cluster.
- May have several, each scoped to a team, each available to that team only.
- Must register and configure Runners with GitLab via Web UI (ChatGPT). Use the "Register an Instance Runner" (Button)
- Executor : Where the pipelines run; several options:
- Kubernetes - Use the Kubernetes executor to use Kubernetes clusters for your builds.
The executor calls the Kubernetes cluster API and creates a pod for each GitLab CI job,
dividing the build into multiple steps:
- Prepare: Create Pod having containers required for the build and services to run.
- Pre-build: Clone, restore cache, and download artifacts from previous stages. This step runs on a special container as part of the pod.
- Build: User build.
- Post-build: Create cache, upload artifacts to GitLab. This step also uses the special container as part of the pod.
- Docker - runs pipeline in container
- Shell - runs pipline at shell of host OS.
- Kubernetes - Use the Kubernetes executor to use Kubernetes clusters for your builds.
The executor calls the Kubernetes cluster API and creates a pod for each GitLab CI job,
dividing the build into multiple steps:
- Metrics :
GitLab git
workflow
Initialize a Project
# (Re)Set global/local(default) config param(s)
git config --global user.name "YOUR NAME"
git config --global user.email "YOUR_EMAIL"
git config --global user.account $_GIT_HOST_ACCOUNT_USERNAME
git config --list
# Create the local project from origin (Git repo)
prj=prj
## Set network params for SSH mode
proto='git@'
host='gitlab.com' # Domain name of the Git-server host
path="$(git config user.account)/$prj"
keypath=~/.ssh/${host%.*}_$(git config user.account)
## SSH login sans creds prompts
ssh -T -i $keypath git@${host}
## Initialize : git init
git clone git@${host}:${path}.git && pushd $prj
## Create/commit main bran
git switch --create main || git checkout main || git checkout -b main
touch README.md
git add README.md
git commit -m "Project init @ $(date -u '+%Y-%m-%dT%H:%M:%SZ')"
## Push to origin
git push --set-upstream origin main
# Else add origin in SSH mode and then push
# git remote add origin ${proto}${server}:${path}.git
# Push (securely)
# git push -u origin main # initial
# git push # subsequent
- The project (URI) must already exist at the Git server (
$host
).
Swap Modes (Protocols)
Git-server protocol/syntax allows for HTTPS using 'https://'
,
and for SSH using either 'git@'
or 'ssh://'
.
proto='https://'
git remote set-url origin ${proto}${host}:${path}.git
git remote set-url origin git@gitlab.com:/acct-y/prj-y.git # Example
# Verify
git remote show origin
SSH : Key-pair Setup
Setup secure comms enabling login sans password.
# Generate key pair
ssh-keygen [-t ed25519|ecdsa|rsa] -C "$email_addr" -f $keypath # ~/.ssh/gitlab
# Fingerprint (fpr)
# Show fpr of any key (public/private have common fpr)
## -v show visual in addition to the hash.
ssh-keygen [-E md5|sha1(default)] -l[v] -f $keypath
# Show fpr of (remote) host(s) : VALIDATE host ON FIRST CONNECT
ssh-keygen [-E md5|sha1(default)] -l[v] -f $keypath
# Copy/Paste user's PUBLIC key (*.pub) to remote:
# Web GUI @ https://gitlab.com/-/profile/keys
# LOGIN to create SSH tunnel (sans shell)
ssh -T[v[v[v[v]]]] -i $keypath git@github.com # -v; verbosity [levels]
# Optionally : Requires Git 2.10+
git config core.sshCommand "ssh -o IdentitiesOnly=yes -i $keypath -F /dev/null"
Configure @ ~/.ssh/config
Host gitlab gitlab.com
HostName gitlab.com
User git
RequestTTY no
IdentityFile ~/.ssh/gitlab_sempernow
Thereafter:
# Login : creates SSH tunnel (sans shell)
ssh gitlab