Skip to content

Installing GitFlic Runner with Shell Type

Check the compatibility table for the required agent version and download it from the runner releases page. The latest runner version is available here.

  • For agents version 1.7.1 and below, working directory selection is not available
  • The default working directory is gitflic-runner in the home directory of the user running the agent
  • It's recommended to create a dedicated system user for running the agent

Dependency Installation

  1. Install Java

    • Check available OpenJDK versions: 
    sudo apt policy openjdk-11-jdk
    • Install the package: 
    sudo apt install openjdk-11-jdk
    • Verify installation: 
    java --version
    • Copy Axiom JDK deb package to remote server: 
    scp axiomjdk11-*.deb <username>@<ip>:~/
    • Install the package: 
    sudo apt install ./axiomjdk11*.deb
    • Verify installation: 
    java --version

  2. Install Git 

    sudo apt update && sudo apt install git -y

Agent Installation

  • Run installation script: 

    echo "deb [signed-by=/etc/apt/keyrings/gitflic.asc] https://registry.gitflic.ru/company/gitflic/package/-/deb main stable" | sudo tee -a /etc/apt/sources.list.d/gitflic.list  
sudo curl https://registry.gitflic.ru/company/gitflic/package/-/deb/dists/main/public-key.asc -o /etc/apt/keyrings/gitflic.asc  
sudo apt update && sudo apt install gitflic-runner -yq

  1. Create temp directory and extract runner package: 

    sudo mkdir /tmp/gitflic-runner  
sudo unzip gitflic-runner_*.zip -d /tmp/gitflic-runner

  2. Create working directory: 

    sudo mkdir /opt/gitflic-runner

  3. Create required subdirectories: 

    sudo mkdir /opt/gitflic-runner/build  
sudo mkdir /opt/gitflic-runner/cache  
sudo mkdir /opt/gitflic-runner/log

  4. Create gitflic-runner user: 

    sudo useradd --home-dir /opt/gitflic-runner --system --shell /bin/sh gitflic-runner

  5. Copy required files to /opt/gitflic-runner: 

    sudo cp /tmp/gitflic-runner/runner.jar /tmp/gitflic-runner/helper.jar /tmp/gitflic-runner/scripts/helper.sh /opt/gitflic-runner

    helper.jar - auxiliary file for agent operation in shell mode. Required for pre-task operations (downloading artifacts, cache preparation) and post-task operations (uploading artifacts/reports to GitFlic, creating cache etc.).

  6. Make helper.sh executable: 

    sudo chmod +x /opt/gitflic-runner/helper.sh

    helper.sh - shell script that calls helper.jar with various parameters. The CI/CD agent executes helper.jar through helper.sh.

    Without helper.jar and helper.sh files, the agent cannot properly execute CI/CD tasks.

Agent Registration

  1. Access web interface

    GitFlic → Admin Panel → CI/CD 

    http(s)://<Web Interface Address>/admin/runners

    Agent registration on gitflic.ru is only available at company level

    Company Settings → CI/CD Agents 

    https://gitflic.ru/company/<company_name>/setting/cicd/runners

  2. Copy and save URL and Token

    Get Token

  3. Navigate to runner.jar directory 

    sudo cd /opt/gitflic-runner

  4. Run registration command 

    sudo java -jar runner.jar register --url <url> --registration-token <token>
    Parameter Required Description
    --url <url> Yes URL copied in step 3
    --registration-token <token> or --token <token> Yes Token copied in step 1
    --name <name> No Agent name
    --tags <tags> No Agent tags (comma-separated)
    • Upon successful registration, the web interface will show the connected agent.
    • A config directory containing application.properties will be created.

    Agent Registration

  5. Add required parameters to config/application.properties: 

    runner.executor=shell  
runner.workingDir=/opt/gitflic-runner  
runner.helperDir=/opt/gitflic-runner  
logging.file.name=/opt/gitflic-runner/log/server.log  
logging.level.root=INFO

    Add additional parameters as needed. See parameter reference.

  6. Set directory ownership: 

    sudo chown -R gitflic-runner:gitflic-runner /opt/gitflic-runner

Starting the Agent

Run startup command: 

sudo -u gitflic-runner java -jar runner.jar start --config=config/application.properties

--config= specifies configuration file location.

  1. Create systemd unit file: 

    touch /etc/systemd/system/gitflic-runner.service

  2. Add service configuration: 

    sudo cat <<EOF >> /etc/systemd/system/gitflic-runner.service  
[Unit]  
Description=Gitflic-runner  

[Service]  
User=gitflic-runner  
Group=gitflic-runner  
WorkingDirectory=/opt/gitflic-runner  
ExecStart=/usr/bin/java -jar runner.jar start --config=config/application.properties  
ExecStop=/bin/kill -s 15 $MAINPID  
StandardOutput=journal  
StandardError=journal  
Restart=on-failure  
RestartSec=10  
TimeoutStartSec=2min  

[Install]  
WantedBy=multi-user.target  
EOF
    /etc/systemd/system/gitflic-runner.service 
    [Unit]  
Description=Gitflic-runner  

[Service]  
User=gitflic-runner  
Group=gitflic-runner  
WorkingDirectory=/opt/gitflic-runner  
ExecStart=/usr/bin/java -jar runner.jar start --config=config/application.properties  
ExecStop=/bin/kill -s 15 $MAINPID  
StandardOutput=journal  
StandardError=journal  
Restart=on-failure  
RestartSec=10  
TimeoutStartSec=2min  

[Install]  
WantedBy=multi-user.target

  3. Reload systemd: 

    sudo systemctl daemon-reload

  4. Enable and start service: 

    systemctl enable gitflic-runner.service  
systemctl start gitflic-runner.service

Automatic Translation!

This page has been translated using automated tools. The text may contain inaccuracies.