In quickstart, initialise repo

[mugnier102]

Expected Behavior

Following https://github.com/retigra/ZabbixCI/blob/main/docs/tutorials/quickstart.md,
I expect the quickstart to work.

Possible Solution

We need to use git init after creation of config.yaml.
Improve documentation with git init after mkdir should be enough.

Steps to Reproduce

Follow quickstart guide.

[wouterdebruijn]

Hi, thanks for your report.

This manual step of using git init or even creating a directory should not be required.

What directory and repository and you initialising manually?

[q1x]

Hi @mugnier102,

What OS are you using ZabbixCi on?
Can you specify your python and git versions as well?

Thanks!

[mugnier102]

Here is a new attempt (WSL2 subsystem on windows 11).
Python 3.13.0
git version 2.39.5

cd zabbixci/
(ansible) omugnier@LAPTOP-8RG0QH3:~/zabbixci$ ls
config.yaml
(ansible) omugnier@LAPTOP-8RG0QH3:~/zabbixci$ cat config.yaml
# Zabbix API connection parameters
zabbix_token: 094439fbXXXXXXXXXXXXXXaf2f8954fa787
zabbix_url: http://10.0.200.10/zabbix

# optional, if you are using untrusted certificates for Zabbix
#ignore_ssl_verify: true

# Primary Template group in Zabbix
root_template_group: Templates

# Git connection parameters
remote: git@gitlab.XXXXX.com:omugnier/zabbixci.git
 #git_pubkey: ~/.ssh/id_rsa.pub
 #git_privkey: ~/.ssh/id_rsa

# optional, if you've used a passphrase on your SSH key
#git_keypassphrase: YOURPASSPHRASE
(ansible) omugnier@LAPTOP-8RG0QH3:~/zabbixci$ pip list | grep zabbix
zabbix-api                0.5.6
zabbix-utils              2.0.2
zabbixci                  0.3.8
(ansible) omugnier@LAPTOP-8RG0QH3:~/zabbixci$ zabbixci push -v --config ./config.yaml --dry-run
2025-07-08 16:05:46  [INFO]: Remote branch does not exist, using state from branch: main
2025-07-08 16:05:47  [ERROR]: Unexpected error:
Traceback (most recent call last):
 File "/home/omugnier/miniconda3/envs/ansible/lib/python3.13/site-packages/zabbixci/zabbixci.py", line 98, in push
   self._git.pull(Settings.REMOTE)
   ~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^
 File "/home/omugnier/miniconda3/envs/ansible/lib/python3.13/site-packages/zabbixci/git/git.py", line 228, in pull
   remote_id = self._repository.lookup_reference(
               ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^
       f"refs/remotes/origin/{branch}"
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   ).target
   ^
KeyError: 'refs/remotes/origin/main'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
 File "/home/omugnier/miniconda3/envs/ansible/lib/python3.13/site-packages/zabbixci/cli.py", line 473, in run_zabbixci
   await zabbixci.push()
 File "/home/omugnier/miniconda3/envs/ansible/lib/python3.13/site-packages/zabbixci/zabbixci.py", line 105, in push
   self._git.pull(Settings.REMOTE)
   ~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^
 File "/home/omugnier/miniconda3/envs/ansible/lib/python3.13/site-packages/zabbixci/git/git.py", line 228, in pull
   remote_id = self._repository.lookup_reference(
               ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^
       f"refs/remotes/origin/{branch}"
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   ).target
   ^
KeyError: 'refs/remotes/origin/main'
2025-07-08 16:05:47  [ERROR]: ZabbixCI run completed with errors

Then, adding more option for master branch instead of main for our gitlab instance:

(ansible) omugnier@LAPTOP-8RG0QH3:~/zabbixci$ cat config.yaml
# Zabbix API connection parameters
zabbix_token: 09XXXXXXXX787
zabbix_url: http://10.0.200.10/zabbix

# optional, if you are using untrusted certificates for Zabbix
#ignore_ssl_verify: true

# Primary Template group in Zabbix
root_template_group: Templates

# Git connection parameters
remote: git@gitlab.XXXX.com:omugnier/zabbixci.git
  #git_pubkey: ~/.ssh/id_rsa.pub
  #git_privkey: ~/.ssh/id_rsa

# optional, if you've used a passphrase on your SSH key
#git_keypassphrase: YOURPASSPHRASE
#
#
#

#### Option: pull_branch
# Git branch used to pull for synchronization.
# Mandatory: no
# Default: main
pull_branch: "master"

### Option: push_branch
# Git branch used to push for synchronization.
# Mandatory: no
# Default: main
push_branch: "master"

### Option: verbose
# Enable verbose output.
# Mandatory: no
# Default: false
verbose: true

### Option: debug
# Enable ZabbixCI debug output.
# Mandatory: no
# Default: false
debug: false

### Option: debug_all
# Enable all debug output, including underlying libraries.
# Mandatory: no
# Default: false
debug_all: false

(ansible) omugnier@LAPTOP-8RG0QH3:~/zabbixci$ zabbixci push -v --config ./config.yaml --dry-run
2025-07-08 16:10:49  [INFO]: Found 0 templates in Zabbix
2025-07-08 16:10:49  [INFO]: No changes detected
(ansible) omugnier@LAPTOP-8RG0QH3:~/zabbixci$

If i understand right, i should have 4 template file....

[wouterdebruijn]

Thanks for the additional information. from your post in the discussion section I presume you are using Zabbix 7.4? However this is not reflected by your provided output as that would require the skip_version_check flag on zabbix-utils=2.0.2

Could you upgrade the zabbix-utils package to zabbix-utils==2.0.3, this will enable full 7.4 support.
Could you provide the output of the following commands?

zabbixci version --config config.yaml -vvv (includes zabbix hostname, mask if necessary)
zabbixci push -v --config ./config.yaml --dry-run -vvv (includes zabbix hostname, mask if necessary)

The -vvv flag enables the debug output for ZabbixCI and its underlying packages.

[mugnier102]

Oh ! That seems to be zabbix API that don't send result on search. How can I get further ?

I did update to 2.0.3 my zabbix-utils: Requirement already satisfied: zabbix_utils==2.0.3
However, I didn't set skip_version_check in my config but does not look required for your command.

 zabbixci version --config config.yaml -vvv
2025-07-08 23:11:40 [zabbixci.cli]  [DEBUG]: Settings: {'__module__': 'zabbixci.settings', '__firstlineno__': 8, '__annotations__': {'VERBOSE': bool | None, 'DEBUG': bool | None, 'DEBUG_ALL': bool | None, 'ZABBIX_URL': str | None, 'ZABBIX_USER': str | None, 'ZABBIX_PASSWORD': str | None, 'ZABBIX_TOKEN': str | None, 'REMOTE': str | None, 'ROOT_TEMPLATE_GROUP': <class 'str'>, 'GIT_AUTHOR_NAME': <class 'str'>, 'GIT_AUTHOR_EMAIL': <class 'str'>, 'GIT_COMMIT_MESSAGE': str | None, 'PULL_BRANCH': <class 'str'>, 'PUSH_BRANCH': <class 'str'>, 'TEMPLATE_PREFIX_PATH': <class 'str'>, 'IMAGE_PREFIX_PATH': <class 'str'>, 'ICON_MAP_PREFIX_PATH': <class 'str'>, 'TEMPLATE_WHITELIST': <class 'str'>, 'TEMPLATE_BLACKLIST': <class 'str'>, 'CACHE_PATH': <class 'str'>, 'BATCH_SIZE': <class 'int'>, 'IGNORE_TEMPLATE_VERSION': <class 'bool'>, 'INSECURE_SSL_VERIFY': <class 'bool'>, 'GIT_USERNAME': <class 'str'>, 'GIT_PASSWORD': str | None, 'GIT_PUBKEY': str | None, 'GIT_PRIVKEY': str | None, 'GIT_KEYPASSPHRASE': str | None, 'CA_BUNDLE': str | None, 'DRY_RUN': <class 'bool'>, 'VENDOR': str | None, 'SET_VERSION': <class 'bool'>, 'SYNC_ICONS': <class 'bool'>, 'SYNC_BACKGROUNDS': <class 'bool'>, 'SYNC_TEMPLATES': <class 'bool'>, 'SYNC_ICON_MAPS': <class 'bool'>, 'IMAGE_WHITELIST': <class 'str'>, 'IMAGE_BLACKLIST': <class 'str'>, 'ICON_SIZES': <class 'str'>, 'BACKGROUND_SIZES': <class 'str'>, 'REGEX_MATCHING': <class 'bool'>, 'ICON_MAP_WHITELIST': <class 'str'>, 'ICON_MAP_BLACKLIST': <class 'str'>, 'ZABBIX_KWARGS': <class 'dict'>, 'GIT_KWARGS': <class 'dict'>, 'SKIP_VERSION_CHECK': <class 'bool'>}, '_DYN_IMG_EXT': ['png', 'jpg', 'jpeg', 'gif', 'bmp', 'svg'], 'VERBOSE': True, 'DEBUG': False, 'DEBUG_ALL': True, 'ZABBIX_URL': 'http://10.0.200.10/zabbix', 'ZABBIX_USER': None, 'ZABBIX_PASSWORD': '********', 'ZABBIX_TOKEN': '********', 'REMOTE': '********', 'ROOT_TEMPLATE_GROUP': 'Templates', 'GIT_AUTHOR_NAME': 'ZabbixCI', 'GIT_AUTHOR_EMAIL': 'zabbixci@localhost', 'GIT_COMMIT_MESSAGE': None, 'PULL_BRANCH': 'master', 'PUSH_BRANCH': 'master', 'TEMPLATE_PREFIX_PATH': 'templates', 'IMAGE_PREFIX_PATH': 'images', 'ICON_MAP_PREFIX_PATH': 'icon-maps', 'TEMPLATE_WHITELIST': '', 'TEMPLATE_BLACKLIST': '', 'CACHE_PATH': './cache', 'BATCH_SIZE': 5, 'IGNORE_TEMPLATE_VERSION': False, 'INSECURE_SSL_VERIFY': False, 'GIT_USERNAME': 'git', 'GIT_PASSWORD': None, 'GIT_PUBKEY': None, 'GIT_PRIVKEY': None, 'GIT_KEYPASSPHRASE': None, 'CA_BUNDLE': None, 'DRY_RUN': False, 'VENDOR': None, 'SET_VERSION': False, 'SYNC_ICONS': False, 'SYNC_BACKGROUNDS': False, 'SYNC_TEMPLATES': True, 'SYNC_ICON_MAPS': False, 'IMAGE_WHITELIST': '', 'IMAGE_BLACKLIST': '', 'ICON_SIZES': '24,48,64,128', 'BACKGROUND_SIZES': '480,720,1080', 'REGEX_MATCHING': False, 'ICON_MAP_WHITELIST': '', 'ICON_MAP_BLACKLIST': '', 'ZABBIX_KWARGS': {}, 'GIT_KWARGS': {}, 'SKIP_VERSION_CHECK': False, 'get_template_whitelist': <classmethod(<function Settings.get_template_whitelist at 0x7efc11f4e200>)>, 'get_template_blacklist': <classmethod(<function Settings.get_template_blacklist at 0x7efc11f4e2a0>)>, 'get_image_whitelist': <classmethod(<function Settings.get_image_whitelist at 0x7efc11f4e340>)>, 'get_image_blacklist': <classmethod(<function Settings.get_image_blacklist at 0x7efc11f4e3e0>)>, 'get_icon_map_whitelist': <classmethod(<function Settings.get_icon_map_whitelist at 0x7efc11f4e480>)>, 'get_icon_map_blacklist': <classmethod(<function Settings.get_icon_map_blacklist at 0x7efc11f4e520>)>, 'get_ICON_SIZES': <classmethod(<function Settings.get_ICON_SIZES at 0x7efc11f4e5c0>)>, 'get_BACKGROUND_SIZES': <classmethod(<function Settings.get_BACKGROUND_SIZES at 0x7efc11f4e660>)>, 'from_env': <classmethod(<function Settings.from_env at 0x7efc11f4e700>)>, 'read_config': <classmethod(<function Settings.read_config at 0x7efc11f4e7a0>)>, '__static_attributes__': (), '__dict__': <attribute '__dict__' of 'Settings' objects>, '__weakref__': <attribute '__weakref__' of 'Settings' objects>, '__doc__': None, 'ACTION': 'version', 'CONFIG': 'config.yaml'}
2025-07-08 23:11:40 [asyncio]  [DEBUG]: Using selector: EpollSelector
2025-07-08 23:11:40 [zabbix_utils.aioapi]  [DEBUG]: Sending request to http://10.0.200.10/zabbix/api_jsonrpc.php with body: {
    "jsonrpc": "2.0",
    "method": "apiinfo.version",
    "params": {},
    "id": "e31028f0-5d2c-47f4-9097-2d72e0e9aa60"
}
2025-07-08 23:11:40 [zabbix_utils.aioapi]  [DEBUG]: Received response body: {
    "jsonrpc": "2.0",
    "result": "7.2.10",
    "id": "e31028f0-5d2c-47f4-9097-2d72e0e9aa60"
}
2025-07-08 23:11:40 [zabbixci.zabbixci]  [DEBUG]: Using token for Zabbix authentication
ZabbixCI version 0.3.8
ZabbixAPI version 7.2.10
Python version 3.13.0



(ansible) omugnier@LAPTOP-8RG0QH3:~/zabbixci$ zabbixci push -v --config ./config.yaml --dry-run -vvv
2025-07-08 23:14:03 [zabbixci.cli]  [DEBUG]: Settings: {'__module__': 'zabbixci.settings', '__firstlineno__': 8, '__annotations__': {'VERBOSE': bool | None, 'DEBUG': bool | None, 'DEBUG_ALL': bool | None, 'ZABBIX_URL': str | None, 'ZABBIX_USER': str | None, 'ZABBIX_PASSWORD': str | None, 'ZABBIX_TOKEN': str | None, 'REMOTE': str | None, 'ROOT_TEMPLATE_GROUP': <class 'str'>, 'GIT_AUTHOR_NAME': <class 'str'>, 'GIT_AUTHOR_EMAIL': <class 'str'>, 'GIT_COMMIT_MESSAGE': str | None, 'PULL_BRANCH': <class 'str'>, 'PUSH_BRANCH': <class 'str'>, 'TEMPLATE_PREFIX_PATH': <class 'str'>, 'IMAGE_PREFIX_PATH': <class 'str'>, 'ICON_MAP_PREFIX_PATH': <class 'str'>, 'TEMPLATE_WHITELIST': <class 'str'>, 'TEMPLATE_BLACKLIST': <class 'str'>, 'CACHE_PATH': <class 'str'>, 'BATCH_SIZE': <class 'int'>, 'IGNORE_TEMPLATE_VERSION': <class 'bool'>, 'INSECURE_SSL_VERIFY': <class 'bool'>, 'GIT_USERNAME': <class 'str'>, 'GIT_PASSWORD': str | None, 'GIT_PUBKEY': str | None, 'GIT_PRIVKEY': str | None, 'GIT_KEYPASSPHRASE': str | None, 'CA_BUNDLE': str | None, 'DRY_RUN': <class 'bool'>, 'VENDOR': str | None, 'SET_VERSION': <class 'bool'>, 'SYNC_ICONS': <class 'bool'>, 'SYNC_BACKGROUNDS': <class 'bool'>, 'SYNC_TEMPLATES': <class 'bool'>, 'SYNC_ICON_MAPS': <class 'bool'>, 'IMAGE_WHITELIST': <class 'str'>, 'IMAGE_BLACKLIST': <class 'str'>, 'ICON_SIZES': <class 'str'>, 'BACKGROUND_SIZES': <class 'str'>, 'REGEX_MATCHING': <class 'bool'>, 'ICON_MAP_WHITELIST': <class 'str'>, 'ICON_MAP_BLACKLIST': <class 'str'>, 'ZABBIX_KWARGS': <class 'dict'>, 'GIT_KWARGS': <class 'dict'>, 'SKIP_VERSION_CHECK': <class 'bool'>}, '_DYN_IMG_EXT': ['png', 'jpg', 'jpeg', 'gif', 'bmp', 'svg'], 'VERBOSE': True, 'DEBUG': False, 'DEBUG_ALL': True, 'ZABBIX_URL': 'http://10.0.200.10/zabbix', 'ZABBIX_USER': None, 'ZABBIX_PASSWORD': '********', 'ZABBIX_TOKEN': '********', 'REMOTE': '********', 'ROOT_TEMPLATE_GROUP': 'Templates', 'GIT_AUTHOR_NAME': 'ZabbixCI', 'GIT_AUTHOR_EMAIL': 'zabbixci@localhost', 'GIT_COMMIT_MESSAGE': None, 'PULL_BRANCH': 'master', 'PUSH_BRANCH': 'master', 'TEMPLATE_PREFIX_PATH': 'templates', 'IMAGE_PREFIX_PATH': 'images', 'ICON_MAP_PREFIX_PATH': 'icon-maps', 'TEMPLATE_WHITELIST': '', 'TEMPLATE_BLACKLIST': '', 'CACHE_PATH': './cache', 'BATCH_SIZE': 5, 'IGNORE_TEMPLATE_VERSION': False, 'INSECURE_SSL_VERIFY': False, 'GIT_USERNAME': 'git', 'GIT_PASSWORD': None, 'GIT_PUBKEY': None, 'GIT_PRIVKEY': None, 'GIT_KEYPASSPHRASE': None, 'CA_BUNDLE': None, 'DRY_RUN': True, 'VENDOR': None, 'SET_VERSION': False, 'SYNC_ICONS': False, 'SYNC_BACKGROUNDS': False, 'SYNC_TEMPLATES': True, 'SYNC_ICON_MAPS': False, 'IMAGE_WHITELIST': '', 'IMAGE_BLACKLIST': '', 'ICON_SIZES': '24,48,64,128', 'BACKGROUND_SIZES': '480,720,1080', 'REGEX_MATCHING': False, 'ICON_MAP_WHITELIST': '', 'ICON_MAP_BLACKLIST': '', 'ZABBIX_KWARGS': {}, 'GIT_KWARGS': {}, 'SKIP_VERSION_CHECK': False, 'get_template_whitelist': <classmethod(<function Settings.get_template_whitelist at 0x7f766d47a200>)>, 'get_template_blacklist': <classmethod(<function Settings.get_template_blacklist at 0x7f766d47a2a0>)>, 'get_image_whitelist': <classmethod(<function Settings.get_image_whitelist at 0x7f766d47a340>)>, 'get_image_blacklist': <classmethod(<function Settings.get_image_blacklist at 0x7f766d47a3e0>)>, 'get_icon_map_whitelist': <classmethod(<function Settings.get_icon_map_whitelist at 0x7f766d47a480>)>, 'get_icon_map_blacklist': <classmethod(<function Settings.get_icon_map_blacklist at 0x7f766d47a520>)>, 'get_ICON_SIZES': <classmethod(<function Settings.get_ICON_SIZES at 0x7f766d47a5c0>)>, 'get_BACKGROUND_SIZES': <classmethod(<function Settings.get_BACKGROUND_SIZES at 0x7f766d47a660>)>, 'from_env': <classmethod(<function Settings.from_env at 0x7f766d47a700>)>, 'read_config': <classmethod(<function Settings.read_config at 0x7f766d47a7a0>)>, '__static_attributes__': (), '__dict__': <attribute '__dict__' of 'Settings' objects>, '__weakref__': <attribute '__weakref__' of 'Settings' objects>, '__doc__': None, 'ACTION': 'push', 'CONFIG': './config.yaml'}
2025-07-08 23:14:03 [asyncio]  [DEBUG]: Using selector: EpollSelector
2025-07-08 23:14:03 [zabbixci.git.credentials]  [DEBUG]: Using SSH agent for Git authentication
2025-07-08 23:14:03 [zabbix_utils.aioapi]  [DEBUG]: Sending request to http://10.0.200.10/zabbix/api_jsonrpc.php with body: {
    "jsonrpc": "2.0",
    "method": "apiinfo.version",
    "params": {},
    "id": "bad2d8b2-9cb4-4852-95b6-64027b25c40d"
}
2025-07-08 23:14:03 [zabbix_utils.aioapi]  [DEBUG]: Received response body: {
    "jsonrpc": "2.0",
    "result": "7.2.10",
    "id": "bad2d8b2-9cb4-4852-95b6-64027b25c40d"
}
2025-07-08 23:14:03 [zabbixci.zabbixci]  [DEBUG]: Using token for Zabbix authentication
2025-07-08 23:14:04 [zabbixci.git.git]  [DEBUG]: Switched to branch master
2025-07-08 23:14:05 [zabbixci.git.git]  [DEBUG]: Already up to date
2025-07-08 23:14:05 [zabbixci.handlers.validation.template_validation]  [DEBUG]: Skipping .yaml file ./cache/config.yaml outside of prefix path
2025-07-08 23:14:05 [zabbix_utils.aioapi]  [DEBUG]: Sending request to http://10.0.200.10/zabbix/api_jsonrpc.php with body: {
    "jsonrpc": "2.0",
    "method": "templategroup.get",
    "params": {
        "search": {
            "name": [
                "Templates"
            ]
        }
    },
    "id": "aaa5288f-22f8-4dc1-81a4-79c0009e9efa"
}
2025-07-08 23:14:05 [zabbix_utils.aioapi]  [DEBUG]: Received response body: {
    "jsonrpc": "2.0",
    "result": [],
    "id": "aaa5288f-22f8-4dc1-81a4-79c0009e9efa"
}
2025-07-08 23:14:05 [zabbix_utils.aioapi]  [DEBUG]: Sending request to http://10.0.200.10/zabbix/api_jsonrpc.php with body: {
    "jsonrpc": "2.0",
    "method": "template.get",
    "params": {
        "groupids": []
    },
    "id": "285b7433-de0a-42ad-9a6b-5bf468980f23"
}
2025-07-08 23:14:05 [zabbix_utils.aioapi]  [DEBUG]: Received response body: {
    "jsonrpc": "2.0",
    "result": [],
    "id": "285b7433-de0a-42ad-9a6b-5bf468980f23"
}
2025-07-08 23:14:05 [zabbixci.handlers.synchronization.template_synchronization]  [INFO]: Found 0 templates in Zabbix
2025-07-08 23:14:05 [zabbixci.handlers.synchronization.template_synchronization]  [DEBUG]: Found Zabbix templates: []
2025-07-08 23:14:05 [zabbixci.zabbixci]  [INFO]: No changes detected

[wouterdebruijn]

Hi there, thank you for the additional log output. Everything seems to be communicating correctly, but as you spotted allready the Zabbix server returns 0 templates on the templategroup.get API call.

I suspect that the user that your API token is bound to does not have permissions for the template group Templates. I was able to replicate your issue using a user with the following permissions:

User:

• User role: default Zabbix "User role" role (has access to API enabled)
• User group: default Zabbix "Guest" group, with no additional template permissions.

After which I added the "Templates" template group to the template permissions on the "Guest" group, which made the templates available for the user to read-write.

Could you take a look at the user bound to your API token, and add the "Templates" template group to the template permissions of the User group used by your API user?