Configuring GitFlic Agent When Using a Self-Signed Certificate

If the GitFlic self-hosted server is configured with a self-signed certificate, additional setup steps are required for the agents to function correctly.

This guide describes the steps for all agent types, including agents running in Docker containers.

Adding the Certificate to Trusted Stores

For all agent types, the self-signed certificate must first be added to the trusted certificates and the Java Key Store (JKS).

Copy the self-signed certificate to the server where the agents will run.

Add the certificate to trusted certificates:

Ubuntu / DebianRedHat / CentOSmacOS

sudo cp selfsigned.crt /usr/local/share/ca-certificates/selfsigned.crt  
sudo update-ca-certificates

sudo cp selfsigned.crt /etc/pki/ca-trust/source/anchors/  
sudo update-ca-trust extract

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain selfsigned.crt

Where selfsigned.crt is the self-signed certificate.

Import the certificate into the Java Key Store (JKS):

keytool -import -noprompt \  
    -storepass changeit \  
    -trustcacerts \  
    -alias selfsigned-cert \  
    -file selfsigned.crt \  
    -keystore "$JAVA_HOME/lib/security/cacerts"

Ensure the $JAVA_HOME variable is available in your environment. Otherwise, manually specify the OpenJDK installation path.

Register the agent and verify that the process completes without errors.

Configuring a Docker-Type Agent

For Docker-type agents, the self-signed certificate must be passed to the container running the pipeline. This feature is available in agent version 4.0.0 and above.

Ensure the agent version is 4.0.0 or higher.
Ensure the certificate includes a SAN (Subject Alternative Name).

The certificate must be created with a SAN. If the certificate is for localhost, add host.docker.internal to the SAN.
Configure the certificate to be mounted into the pipeline container:

In the agent configuration, set up the mounting of the self-signed certificate.

Example:
```
docker.volumes[0]=/home/user/selfsigned.crt:/etc/gitflic-runner/certs/selfsigned.crt  
```
Where /home/user/selfsigned.crt is the host path to the certificate, and /etc/gitflic-runner/certs/selfsigned.crt is the container path.
Add the CA_CERTIFICATES_PATH variable to CI/CD:

Add the CA_CERTIFICATES_PATH variable (e.g., via CI/CD settings in the web interface or in the gitflic-ci.yaml file). Set its value to the certificate path in the container filesystem, as specified in the agent configuration (step 3).
```
variables:  
  CA_CERTIFICATES_PATH: /etc/gitflic-runner/certs/selfsigned.crt  
```

Configuring an Agent Running in a Docker Container

If the agent runs in a Docker container, modify the agent's Dockerfile and rebuild the image.

Add a command to copy the certificate from the host to the agent container:

Example:
```
COPY /home/user/selfsigned.crt /cert/selfsigned.crt  
```
Where /home/user/selfsigned.crt is the self-signed certificate.

Add a command to import the certificate into the Java Key Store:

RUN keytool -import -noprompt \  
    -storepass changeit \  
    -trustcacerts \  
    -alias my-selfsigned-cert \  
    -file /cert/selfsigned.crt \  
    -keystore "$JAVA_HOME/lib/security/cacerts"

Rebuild the image and start the agent:
```
docker compose up --build  
```

Additional Steps

Perform these additional steps if the container runs a docker-type agent:

Modify the ENTRYPOINT to include the certificate mount in the agent configuration:

ENTRYPOINT ([ -f config/application.properties ] && java -jar runner.jar start --config=config/application.properties) ||  
(java -jar runner.jar register --url ${REG_URL} --registration-token ${REG_TOKEN} && cat application.properties >>  
config/application.properties && echo "docker.volumes[0]=/home/user/selfsigned.crt:/etc/gitflic-runner/certs/selfsigned.crt" >>  
config/application.properties && java -jar runner.jar start --config=config/application.properties)

Replace /home/user/selfsigned.crt with the host path to the self-signed certificate, as the pipeline container uses the host's Docker socket, not the agent container's.

Add the CA_CERTIFICATES_PATH variable to CI/CD:

variables:  
  CA_CERTIFICATES_PATH: /etc/gitflic-runner/certs/selfsigned.crt

Rebuild the image and start the agent:
```
docker compose up --build  
```

Automatic translation!

This page has been automatically translated. The text may contain inaccuracies.