GitLab — User Guide

Electric Monk provides Git hosting, CI/CD, and a Docker container registry powered by GitLab at gitlab.electricmonk.io.

Features

• Git repository hosting — create and manage public or private repos
• Merge requests — code review with inline comments, approvals, and CI status checks
• CI/CD pipelines — automated build, test, and deploy via .gitlab-ci.yml
• Container registry — push and pull Docker images at registry.electricmonk.io
• Package registry — host npm, Maven, PyPI, NuGet, and other package formats
• Issue tracking — track bugs, features, and tasks with labels, milestones, and boards
• Wiki — per-project documentation wikis with Markdown support
• Snippets — share code snippets (like Gists)
• SSO login — authenticate through Authentik (OpenID Connect)

Getting Started

Signing In

1. Go to gitlab.electricmonk.io
2. Click Authentik on the sign-in page
3. Log in with your Authentik credentials
4. Your account is created automatically on first login

Setting Up Your Profile

1. Click your avatar (top-right) → Edit profile
2. Set your display name and email
3. Optionally upload an avatar

Adding an SSH Key (for Git over SSH)

1. Generate a key if you don't have one:

   ssh-keygen -t ed25519 -C "you@electricmonk.io"
   

2. Go to Preferences → SSH Keys
3. Paste your public key (~/.ssh/id_ed25519.pub)
4. Click Add key

You can now clone and push via SSH:

git clone ssh://git@gitlab.electricmonk.io:2222/your-username/your-project.git

Creating a Project

1. Click + → New project/repository
2. Choose Create blank project (or import from another source)
3. Set the project name, visibility (Private, Internal, or Public), and options
4. Click Create project

Clone Your Project

# SSH (recommended)
git clone ssh://git@gitlab.electricmonk.io:2222/your-username/your-project.git

# HTTPS
git clone https://gitlab.electricmonk.io/your-username/your-project.git

Working with Merge Requests

1. Create a feature branch:

   git checkout -b my-feature
   # make changes, commit, push
   git push -u origin my-feature
   

2. In GitLab, go to your project → Merge Requests → New merge request
3. Select source branch (my-feature) and target branch (main)
4. Add a description, assign reviewers, and submit
5. Once approved and CI passes, click Merge

CI/CD Pipelines

Add a .gitlab-ci.yml file to the root of your repository:

stages:
  - build
  - test

build:
  stage: build
  script:
    - echo "Building..."

test:
  stage: test
  script:
    - echo "Running tests..."

Pipelines run automatically on every push. View results in your project → Build → Pipelines.

Container Registry

Push Docker images to the built-in registry:

# Log in to the registry
docker login registry.electricmonk.io

# Tag and push
docker build -t registry.electricmonk.io/your-username/your-project:latest .
docker push registry.electricmonk.io/your-username/your-project:latest

# Pull
docker pull registry.electricmonk.io/your-username/your-project:latest

Browse images in your project → Deploy → Container Registry.

Package Registry

GitLab can host packages for multiple ecosystems. Example for npm:

# .npmrc
@your-username:registry=https://gitlab.electricmonk.io/api/v4/projects/<id>/packages/npm/
//gitlab.electricmonk.io/api/v4/projects/<id>/packages/npm/:_authToken=<your-token>

npm publish

See your project → Deploy → Package Registry for setup instructions for npm, Maven, PyPI, NuGet, and more.

Issues and Project Management

• Issues: Track work items in your project → Plan → Issues
• Labels: Categorize issues (e.g. bug, feature, documentation)
• Milestones: Group issues into releases or sprints
• Boards: Kanban-style boards in Plan → Issue boards

Troubleshooting

Can't sign in

• Make sure you're clicking Authentik on the sign-in page, not entering local credentials
• If your account wasn't created, contact an administrator

Git push rejected

• Ensure your SSH key is registered in GitLab (Preferences → SSH Keys)
• For HTTPS, use a personal access token instead of your password: Preferences → Access Tokens → create a token with write_repository scope

CI pipeline not running

• Verify .gitlab-ci.yml is in the repository root and is valid YAML
• Check Build → Pipelines for error details
• Note: GitLab Runner is not installed yet — CI pipelines require a runner to be configured

Docker login fails

• Use a personal access token with read_registry / write_registry scope
• Registry URL is registry.electricmonk.io (not gitlab.electricmonk.io)