DOCSEARCHbyAlgolia
Submit Docs

gitlab-ci-local

repository·master·Indexed 26 days ago

https://github.com/firecow/gitlab-ci-local

A tool that allows users to run GitLab CI pipelines locally using either a shell executor or a Docker executor. It enables testing .gitlab-ci.yml configurations without pushing code to a remote GitLab instance. Features include support for Docker-in-Docker, local registry integration, custom variable management via YAML or .env files, and the ability to define local-only jobs using the $GITLAB_CI == 'false' condition.

Tokens
6.7K
Snippets
20
Records
54
Agent score
87%

What's inside gitlab-ci-local

  1. Run local-only jobs and scripts

    master

    To prevent certain jobs or script segments from running in the actual GitLab CI environment while allowing them to run locally, use the $GITLAB_CI == 'false' condition in your rules or script blocks.

    local-only-job:
  rules:
    - { if: $GITLAB_CI == 'false' }

local-only-subsection:
  script:
    - if [ $GITLAB_CI == 'false' ]; then eslint . --fix; fi
    - eslint .

  4. Manage includes and artifacts

    master

    Includes

    Includes from external sources are cached. To force a refresh of external includes, use the --fetch-includes flag.

    Artifacts

    • Shell executor: Copies artifacts to the host/CWD directory. Use --shell-isolation to mimic correct artifact handling.
    • Docker executor: Copies artifacts to and from .gitlab-ci-local/artifacts.

  5. Install gitlab-ci-local on Windows (Git Bash)

    master
    1. Install Git Bash.
    2. Install rsync.
    3. Download the binary and place it in C:\Program Files\Git\mingw64\bin.

    Note: When executing, you may need to use the flag --variable MSYS_NO_PATHCONV=1 in certain situations.

    curl -L https://github.com/firecow/gitlab-ci-local/releases/latest/download/gitlab-ci-local-windows-amd64.zip -o gcl.zip && unzip -o gcl.zip -d /c/Program\ Files/Git/mingw64/bin && rm gcl.zip

  6. Build single executable binaries from source

    master

    To create standalone binaries for different operating systems, use the following Bun commands after running bun install:

    bun install

bun build:linux-amd64
bun build:linux-arm64
bun build:win
bun build:macos-x64
bun build:macos-arm64
bun build-all

  8. Install gitlab-ci-local on Linux (Debian-based)

    master

    For Debian-based distributions, it is recommended to use the Deb822 format. If your distribution does not support Deb822, you can use the standard repository method with an ASCII-armored .asc key for compatibility with older versions like Ubuntu Focal.

    # Recommended: Deb822 format
sudo wget -O /etc/apt/sources.list.d/gitlab-ci-local.sources https://gitlab-ci-local-ppa.firecow.dk/gitlab-ci-local.sources
sudo apt-get update
sudo apt-get install gitlab-ci-local

# Alternative: Standard method for older apts
PPA_KEY_PATH=/etc/apt/sources.list.d/gitlab-ci-local-ppa.asc
curl -s "https://gitlab-ci-local-ppa.firecow.dk/pubkey.gpg" | sudo tee "${PPA_KEY_PATH}"
echo "deb [ signed-by=${PPA_KEY_PATH} ] https://gitlab-ci-local-ppa.firecow.dk/./" | sudo tee /etc/apt/sources.list.d/gitlab-ci-local.list

sudo apt-get update
sudo apt-get install gitlab-ci-local

  10. Understand GitLab CI Job Execution Lifecycle

    master

    The project simulates the GitLab CI job lifecycle. When a job runs, it follows these stages:

    1. Pre-scripts: Executes before_script and the main script commands. The environment variable CI_JOB_STATUS is set to running during this phase and updated to success or failed based on the exit code.
    2. Main Scripts: Executes the primary script block defined in .gitlab-ci.yml.
    3. After-scripts: Executes the after_script block. This runs regardless of whether the main scripts succeeded or failed.
    4. Artifacts & Cache: Depending on the configuration, artifacts are exported and caches are pushed/pulled to/from the local state directory.

  11. Configure Home file variables

    master

    You can define project-specific, group-specific, or global variables in $HOME/.gitlab-ci-local/variables.yml.

    • Project variables: Matched by exact git remote syntax.
    • Group variables: Matched if the remote includes the group path.
    • Global variables: Always present. If a value is a file path, it is treated as type File. You can also use type: variable or type: file explicitly with scoped values using glob patterns.
    ---
project:
  gitlab.com/test-group/test-project.git:
    AUTHORIZATION_PASSWORD: djwqiod910321

group:
  gitlab.com/test-group/:
    DOCKER_LOGIN_PASSWORD: dij3213n123n12in3

global:
  KNOWN_HOSTS: '~/.ssh/known_hosts'
  DEPLOY_ENV_SPECIFIC:
    type: variable
    values:
      '*production*': 'Im production only value'
      'staging': 'Im staging only value'
  FILE_CONTENT_IN_VALUES:
    type: file
    values:
      '*': |
        Im staging only value
        I'm great for certs n' stuff

  12. Configure CLI options via Environment Variables or Files

    master

    You can assign default values to CLI options using environment variables or configuration files to avoid repetitive typing.

    Environment Variables: Prefix options with GCL_.

    Configuration Files: Use .gitlab-ci-local-env in the current working directory or $HOME/.gitlab-ci-local/.env.