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: Pre-built Binaries (Recommended)

  1. Download the latest binary for your platform from Releases
  2. Make the binary executable
  3. Move the binary to your PATH

Releases provide tarballs (.tar.gz) for Linux and macOS, and zip for Windows. Each archive contains the binary, LICENSE, and README.

macOS / Linux (tarball)

# Get latest version and detect platform
VERSION=$(curl -s https://api.github.com/repos/InkyQuill/gitlab-ci-lint/releases/latest | jq -r .tag_name | sed 's/^v//')
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 tarball and extract
curl -sL "https://github.com/InkyQuill/gitlab-ci-lint/releases/download/v${VERSION}/gitlab-ci-lint_${VERSION}_${OS}_${ARCH}.tar.gz" | tar xz
chmod +x gitlab-ci-lint
mkdir -p ~/.local/bin
mv gitlab-ci-lint ~/.local/bin/

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

gitlab-ci-lint version

Linux (AMD64)

VERSION=$(curl -s https://api.github.com/repos/InkyQuill/gitlab-ci-lint/releases/latest | jq -r .tag_name | sed 's/^v//')
curl -sL "https://github.com/InkyQuill/gitlab-ci-lint/releases/download/v${VERSION}/gitlab-ci-lint_${VERSION}_linux_amd64.tar.gz" | tar xz
chmod +x gitlab-ci-lint
sudo mv gitlab-ci-lint /usr/local/bin/
gitlab-ci-lint version

macOS (Apple Silicon)

VERSION=$(curl -s https://api.github.com/repos/InkyQuill/gitlab-ci-lint/releases/latest | jq -r .tag_name | sed 's/^v//')
curl -sL "https://github.com/InkyQuill/gitlab-ci-lint/releases/download/v${VERSION}/gitlab-ci-lint_${VERSION}_darwin_arm64.tar.gz" | tar xz
chmod +x gitlab-ci-lint
sudo mv gitlab-ci-lint /usr/local/bin/
gitlab-ci-lint version

Windows (PowerShell, zip)

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

# Download zip and extract
$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
Expand-Archive -Path $zip -DestinationPath . -Force
Move-Item -Path "gitlab-ci-lint.exe" -Destination "$env:USERPROFILE\bin\" -Force
Remove-Item $zip

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

Method 2: 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 $GOPATH/bin (usually ~/go/bin/).

Method 3: 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

# Or build for all supported platforms
make build-all

# The binaries will be in ./build/
ls -lh build/

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

Method 4: Using Makefile Install

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

# Install to GOPATH/bin
make install

Verification

After installation, verify it works:

gitlab-ci-lint version

You should see version information.

Configuration

After installation, you can create a configuration file:

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

# Create config file
cat > ~/.tool-configs/.gitlab-ci-lint/config.yaml <<EOF
gitlab:
  instance: "https://gitlab.com"
  timeout: 30

auth:
  token: ""
  netrc: false

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. Set the GCL_TOKEN environment variable:
export GCL_TOKEN=glpat-xxxxxxxxxxxx

Or add it to your configuration file (see Configuration Guide).

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 > /usr/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 /usr/local/bin
sudo rm /usr/local/bin/gitlab-ci-lint

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

Remove Configuration

rm -rf ~/.tool-configs/.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=$PATH:/path/to/gitlab-ci-lint

"permission denied"

Make the binary executable:

chmod +x 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