Skip to content

Installation Guide

Jump to bottom
Inky Quill edited this page Feb 1, 2026 · 4 revisions

Installation Guide

This guide covers various installation methods for GitLab CI Linter.

Prerequisites

  • Go 1.24+ (if building from source)
  • Git (if building from source)

Installation Methods

Method 1: Install Script (Recommended)

Use our automated install script for the easiest installation:

curl -sSL https://github.com/InkyQuill/gitlab-ci-lint/raw/main/install.sh | bash

The script will:

  • Detect your platform and download the latest release
  • Extract only the binary (no extra files like README.md or LICENSE left behind)
  • Install to ~/.local/bin (follows XDG Base Directory specification)
  • Add to PATH if needed
  • Verify installation

Why ~/.local/bin?

  • XDG Base Directory compliant
  • No sudo required (user-level installation)
  • Works seamlessly with Linux and macOS
  • Separates user tools from system packages

Method 2: Manual Binary Download

Download the binary for your platform from Releases.

Linux / macOS

# Get latest version
VERSION=$(curl -s https://api.github.com/repos/InkyQuill/gitlab-ci-lint/releases/latest | grep -E '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/' | sed 's/^v//')

# Detect platform
OS=$(uname | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m)
case "$ARCH" in x86_64) ARCH="amd64";; aarch64|arm64) ARCH="arm64";; i386|i686) ARCH="386";; esac

# Download and extract ONLY the binary (tar xz -O extracts to stdout)
curl -sL "https://github.com/InkyQuill/gitlab-ci-lint/releases/download/v${VERSION}/gitlab-ci-lint_${VERSION}_${OS}_${ARCH}.tar.gz" | \
    tar xz -O gitlab-ci-lint > gitlab-ci-lint

# Make executable and install
chmod +x gitlab-ci-lint
mkdir -p ~/.local/bin
mv gitlab-ci-lint ~/.local/bin/

# Add to PATH if needed
[[ ":$PATH:" != *":$HOME/.local/bin:"* ]] && echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.bashrc
export PATH=$HOME/.local/bin:$PATH

# Verify
gitlab-ci-lint version

Windows (PowerShell)

# Get latest version
$version = (Invoke-RestMethod -Uri "https://api.github.com/repos/InkyQuill/gitlab-ci-lint/releases/latest").tag_name -replace '^v', ''

# Download zip
$zip = "gitlab-ci-lint_${version}_windows_amd64.zip"
Invoke-WebRequest -Uri "https://github.com/InkyQuill/gitlab-ci-lint/releases/download/v$version/$zip" -OutFile $zip -UseBasicParsing

# Extract only the binary (using Expand-Archive with specific file)
Add-Type -AssemblyName System.IO.Compression.FileSystem
$zipFile = [System.IO.Compression.ZipFile]::OpenRead($zip)
$entry = $zipFile.Entries | Where-Object { $_.Name -eq 'gitlab-ci-lint.exe' }
[System.IO.Compression.ZipFileExtensions]::ExtractToFile($entry, "gitlab-ci-lint.exe", $true)
$zipFile.Dispose()

# Install
mkdir -p "$env:USERPROFILE\.local\bin" 2>$null | Out-Null
Move-Item -Path "gitlab-ci-lint.exe" -Destination "$env:USERPROFILE\.local\bin\" -Force
Remove-Item $zip

# Add to PATH if needed
$binPath = "$env:USERPROFILE\.local\bin"
$path = [Environment]::GetEnvironmentVariable("Path", "User")
if ($path -notlike "*$binPath*") {
    [Environment]::SetEnvironmentVariable("Path", "$path;$binPath", "User")
    $env:Path += ";$binPath"
}

gitlab-ci-lint version

Method 3: Go Install

If you have Go installed:

go install github.com/InkyQuill/gitlab-ci-lint/cmd/gitlab-ci-lint@latest

The binary will be installed to $(go env GOPATH)/bin (usually ~/go/bin/).

Add to PATH if needed:

[[ ":$PATH:" != *":$(go env GOPATH)/bin:"* ]] && echo 'export PATH=$(go env GOPATH)/bin:$PATH' >> ~/.bashrc
export PATH=$(go env GOPATH)/bin:$PATH

Method 4: Build from Source

# Clone the repository
git clone https://github.com/InkyQuill/gitlab-ci-lint.git
cd gitlab-ci-lint

# Build for your current platform
make build

# Install to ~/.local/bin
mkdir -p ~/.local/bin
cp build/gitlab-ci-lint ~/.local/bin/

# Add to PATH if needed
[[ ":$PATH:" != *":$HOME/.local/bin:"* ]] && echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.bashrc
export PATH=$HOME/.local/bin:$PATH

Build for Specific Platform

# Linux AMD64
GOOS=linux GOARCH=amd64 go build -o gitlab-ci-lint-linux-amd64 cmd/gitlab-ci-lint/main.go

# macOS ARM64 (Apple Silicon)
GOOS=darwin GOARCH=arm64 go build -o gitlab-ci-lint-darwin-arm64 cmd/gitlab-ci-lint/main.go

# Windows AMD64
GOOS=windows GOARCH=amd64 go build -o gitlab-ci-lint-windows-amd64.exe cmd/gitlab-ci-lint/main.go

Verification

After installation, verify it works:

gitlab-ci-lint version

You should see version information.

Configuration

After installation, run the interactive setup:

gitlab-ci-lint setup

The wizard will help you configure:

  • GitLab instances (multiple instances supported)
  • Personal access tokens for API validation
  • Output preferences

Or create a configuration file manually:

# Create config directory
mkdir -p ~/.tools-config/.gitlab-ci-lint

# Create config file
cat > ~/.tools-config/.gitlab-ci-lint/config.yaml <<EOF
gitlab:
  instances:
    - name: gitlab.com
      url: "https://gitlab.com"
      token: "glpat-xxxxxxxxxxxx"

validation:
  skip_api: false
  strict: true

output:
  format: "text"
  verbose: false
  color: "auto"
EOF

GitLab Personal Access Token

For API validation, you'll need a GitLab personal access token:

  1. Go to your GitLab instance
  2. Navigate to User Settings > Access Tokens
  3. Create a new token with api scope
  4. Configure via setup wizard or set environment variable:
export GCL_TOKEN=glpat-xxxxxxxxxxxx

Shell Completion

Bash

# Generate completion script
gitlab-ci-lint completion bash > /etc/bash_completion.d/gitlab-ci-lint

# Or add to ~/.bash_completion
gitlab-ci-lint completion bash >> ~/.bash_completion
source ~/.bash_completion

Zsh

# Generate completion script
gitlab-ci-lint completion zsh > ~/.local/share/zsh/site-functions/_gitlab-ci-lint

# Or add to ~/.zshrc
gitlab-ci-lint completion zsh >> ~/.zshrc

Fish

gitlab-ci-lint completion fish > ~/.config/fish/completions/gitlab-ci-lint.fish

Uninstallation

Remove Binary

# If installed to ~/.local/bin (recommended method)
rm ~/.local/bin/gitlab-ci-lint

# If installed via go install
rm $(go env GOPATH)/bin/gitlab-ci-lint

Remove Configuration

rm -rf ~/.tools-config/.gitlab-ci-lint

Remove from Shell Completion

Remove the completion scripts added during installation.

Troubleshooting

"command not found: gitlab-ci-lint"

Ensure the binary is in your PATH:

echo $PATH
which gitlab-ci-lint

Add to PATH if needed:

# Add to ~/.bashrc or ~/.zshrc
export PATH=$HOME/.local/bin:$PATH

"permission denied"

Make the binary executable:

chmod +x ~/.local/bin/gitlab-ci-lint

Build Errors

If building from source fails:

# Ensure you have Go 1.24+
go version

# Update dependencies
cd gitlab-ci-lint
go mod tidy

# Clean and rebuild
make clean
make build

Next Steps

Clone this wiki locally