Source: https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/app/github_http?at=release/7.0
GitHub repository by HTTP
Overview
This template is designed for the effortless deployment of GitHub repository monitoring by Zabbix via GitHub REST API and doesn't require any external scripts.
For more details about GitHub REST API, refer to the official documentation.
Requirements
Zabbix version: 7.0 and higher.
Tested versions
This template has been tested on:
- GitHub API version 2022-11-28
Configuration
Zabbix should be configured according to the instructions in the Templates out of the box section.
Setup
GitHub limits the number of REST API requests that you can make within a specific amount of time, which also depends on whether you are authenticated or not, the plan, and the token type used. Many REST API endpoints require authentication or return additional information if you are authenticated. Additionally, you can make more requests per hour when you are authenticated.
Additional information is available in the official documentation:
- Create an access token for monitoring
One of the simplest ways to send authenticated requests is to use a personal access token - either a classic or a fine-grained one.
Classic personal access token
You can create a new classic personal access token by following the instructions in the official documentation.
For public repositories, no additional permission scopes are required. For monitoring to work on private repositories, the repo
scope must be set to have full control of private repositories.
Additional information about OAuth scopes is available in the official documentation.
Note that authenticated users must have admin access to the repository and the repo
scope must be set to get information about self-hosted runners.
Fine-grained personal access token
Alternatively, you can use a fine-grained personal access token.
In order to use fine-grained tokens to monitor organization-owned repositories, organizations must opt in to fine-grained personal access tokens and set up a personal access token policy.
The fine-grained token needs to have the following permissions set to provide access to the repository resources:
- "Actions" repository permissions (read);
- "Administration" repository permissions (read);
- "Contents" repository permissions (read);
- "Issues" repository permissions (read);
- "Metadata" repository permissions (read);
- "Pull requests" repository permissions (read).
-
Set the access token that you've created in step 1 in the
{$GITHUB.API.TOKEN}
macro -
Change the API URL in the
{$GITHUB.API.URL}
macro if needed (for self-hosted installations) -
Set the repository owner name in the
{$GITHUB.REPO.OWNER}
macro -
Set the repository name in the
{$GITHUB.REPO.NAME}
macro - Set the LLD rule filters if needed (you may want to use them to stay within rate limits as on large repositories, LLD rules may generate a lot of script items):
- Filter repository branches by name:
{$GITHUB.BRANCH.NAME.MATCHES}
,{$GITHUB.BRANCH.NAME.NOT_MATCHES}
; - Filter repository workflows by name:
{$GITHUB.WORKFLOW.NAME.MATCHES}
,{$GITHUB.WORKFLOW.NAME.NOT_MATCHES}
; - Filter repository workflows by state:
{$GITHUB.WORKFLOW.STATE.MATCHES}
,{$GITHUB.WORKFLOW.STATE.NOT_MATCHES}
; - Filter self-hosted runners by name:
{$GITHUB.RUNNER.NAME.MATCHES}
,{$GITHUB.RUNNER.NAME.NOT_MATCHES}
; - Filter self-hosted runners by OS:
{$GITHUB.RUNNER.OS.MATCHES}
,{$GITHUB.RUNNER.OS.NOT_MATCHES}
.
Note: Update intervals and timeouts for script items can be changed individually via {$GITHUB.INTERVAL}
and {$GITHUB.TIMEOUT}
macros with context. Depending on the repository being monitored, it can be adjusted if needed (if you are exceeding rate limits, you can increase update intervals for some script items to stay within per hour request limits). But be aware that it may also affect the triggers (check whether the item is used in triggers and adjust thresholds and/or evaluation periods if needed).
Macros used
Name | Description | Default |
---|---|---|
{$GITHUB.API.URL} | Set the API URL here. |
https://api.github.com/ |
{$GITHUB.USER_AGENT} | The user agent that is used in headers for HTTP requests. |
Zabbix/7.0 |
{$GITHUB.API_VERSION} | The API version that is used in headers for HTTP requests. |
2022-11-28 |
{$GITHUB.REPO.OWNER} | Set the repository owner here. |
<SET THE REPO OWNER> |
{$GITHUB.REPO.NAME} | Set the repository name here. |
<SET THE REPO NAME> |
{$GITHUB.API.TOKEN} | Set the access token here. |
|
{$GITHUB.INTERVAL} | The update interval for the script items that retrieve data from the API. Can be used with context if needed (check the context values in relevant items). |
1m |
{$GITHUB.INTERVAL:regex:"get_(tags|releases|issues)_count"} | The update interval for the script items that retrieve the number of tags, releases, issues, and pull requests (total, open, closed). |
1h |
{$GITHUB.INTERVAL:"get_repo"} | The update interval for the script item that retrieves the repository information. |
15m |
{$GITHUB.INTERVAL:"get_(branches|workflows)"} | The update interval for the script items that retrieve the branches and workflows. Used only for related metric discovery. |
1h |
{$GITHUB.INTERVAL:"get_runners"} | The update interval for the script item that retrieves the information about self-hosted runners. |
15m |
{$GITHUB.INTERVAL:regex:"get_last_run:.+"} | The update interval for the script items that retrieve the information about the last workflow run results. |
15m |
{$GITHUB.INTERVAL:regex:"get_commits_count:.+"} | The update interval for the script items that retrieve the commits count in discovered branches. |
1h |
{$GITHUB.TIMEOUT} | The timeout threshold for the script items that retrieve data from the API. Can be used with context if needed (check the context values in relevant items). |
15s |
{$GITHUB.HTTP_PROXY} | The HTTP proxy for script items (set if needed). If the macro is empty, then no proxy is used. |
|
{$GITHUB.RESULTS_PER_PAGE} | The number of results to fetch per page. Can be used with context and adjusted if needed (check the context values in script parameters of relevant items). |
100 |
{$GITHUB.WORKFLOW.NAME.MATCHES} | The repository workflow name regex filter to use in workflow-related metric discovery - for including. |
.+ |
{$GITHUB.WORKFLOW.NAME.NOT_MATCHES} | The repository workflow name regex filter to use in workflow-related metric discovery - for excluding. |
CHANGE_IF_NEEDED |
{$GITHUB.WORKFLOW.STATE.MATCHES} | The repository workflow state regex filter to use in workflow-related metric discovery - for including. |
active |
{$GITHUB.WORKFLOW.STATE.NOT_MATCHES} | The repository workflow state regex filter to use in workflow-related metric discovery - for excluding. |
CHANGE_IF_NEEDED |
{$GITHUB.BRANCH.NAME.MATCHES} | The repository branch name regex filter to use in branch-related metric discovery - for including. |
.+ |
{$GITHUB.BRANCH.NAME.NOT_MATCHES} | The repository branch name regex filter to use in branch-related metric discovery - for excluding. |
CHANGE_IF_NEEDED |
{$GITHUB.RUNNER.NAME.MATCHES} | The repository self-hosted runner name regex filter to use in discovering metrics related to the self-hosted runner - for including. |
.+ |
{$GITHUB.RUNNER.NAME.NOT_MATCHES} | The repository self-hosted runner name regex filter to use in discovering metrics related to the self-hosted runner - for excluding. |
CHANGE_IF_NEEDED |
{$GITHUB.RUNNER.OS.MATCHES} | The repository self-hosted runner OS regex filter to use in discovering metrics related to the self-hosted runner - for including. |
.+ |
{$GITHUB.RUNNER.OS.NOT_MATCHES} | The repository self-hosted runner OS regex filter to use in discovering metrics related to the self-hosted runner - for excluding. |
CHANGE_IF_NEEDED |
{$GITHUB.REQUESTS.UTIL.WARN} | The threshold percentage of utilized API requests in a Warning trigger expression. |
80 |
{$GITHUB.REQUESTS.UTIL.HIGH} | The threshold percentage of utilized API requests in a High trigger expression. |
90 |
{$GITHUB.WORKFLOW.STATUS.QUEUED.THRESH} | The time threshold used in the trigger of a workflow run that has been in the queue for too long. Can be used with context if needed. |
1h |
{$GITHUB.WORKFLOW.STATUS.IN_PROGRESS.THRESH} | The time threshold used in the trigger of a workflow run that has been in the queue for too long. Can be used with context if needed. |
24h |
Items
Name | Description | Type | Key and additional info |
---|---|---|---|
Get self-hosted runners | Get the self-hosted runners of the repository. Note that admin access to the repository is required to use this endpoint: https://docs.github.com/en/rest/actions/self-hosted-runners?apiVersion=2022-11-28#list-self-hosted-runners-for-a-repository |
Script | github.repo.runners.get Preprocessing
|
Get self-hosted runner check | Carry out a self-hosted runners data collection check. |
Dependent item | github.repo.runners.get.check Preprocessing
|
Number of releases | The number of releases in the repository. Note that this number also includes draft releases. Information about endpoint: https://docs.github.com/en/rest/releases/releases?apiVersion=2022-11-28#list-releases |
Script | github.repo.releases.count Preprocessing
|
Number of tags | The number of tags in the repository. Information about endpoint: https://docs.github.com/en/rest/repos/repos?apiVersion=2022-11-28#list-repository-tags |
Script | github.repo.tags.count Preprocessing
|
Get issue count | Get the count of issues and pull requests in the repository (total, open, closed). Information about endpoint for issues: https://docs.github.com/en/rest/issues/issues?apiVersion=2022-11-28#list-repository-issues Information about endpoint for pull requests: https://docs.github.com/en/rest/pulls/pulls?apiVersion=2022-11-28#list-pull-requests |
Script | github.repo.issues.get Preprocessing
|
Number of issues | The total number of issues in the repository. |
Dependent item | github.repo.issues.total Preprocessing
|
Number of open issues | The number of open issues in the repository. |
Dependent item | github.repo.issues.open Preprocessing
|
Number of closed issues | The number of closed issues in the repository. |
Dependent item | github.repo.issues.closed Preprocessing
|
Number of PRs | The total number of pull requests in the repository. |
Dependent item | github.repo.pr.total Preprocessing
|
Number of open PRs | The number of open pull requests in the repository. |
Dependent item | github.repo.pr.open Preprocessing
|
Number of closed PRs | The number of closed pull requests in the repository. |
Dependent item | github.repo.pr.closed Preprocessing
|
Request limit | API request limit. Information about request limits in GitHub REST API documentation: https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api?apiVersion=2022-11-28 |
Dependent item | github.repo.requests.limit Preprocessing
|
Requests used | The number of used API requests. Information about request limits in GitHub REST API documentation: https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api?apiVersion=2022-11-28 |
Dependent item | github.repo.requests.used Preprocessing
|
Request limit utilization, in % | The calculated utilization of the API request limit in %. Information about request limits in GitHub REST API documentation: https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api?apiVersion=2022-11-28 |
Dependent item | github.repo.requests.util Preprocessing
|
Get repository | Get the general repository information. If the repository is not a fork, the community profile metrics are also retrieved. Information about endpoint: https://docs.github.com/en/rest/repos/repos?apiVersion=2022-11-28#get-a-repository Information about community profile metrics: https://docs.github.com/en/rest/metrics/community?apiVersion=2022-11-28#get-community-profile-metrics |
Script | github.repo.repository.get |
Get repository data check | Data collection check. |
Dependent item | github.repo.repository.get.check Preprocessing
|
Repository is a fork | Indicates whether the repository is a fork. |
Dependent item | github.repo.repository.is_fork Preprocessing
|
Repository size | The size of the repository. |
Dependent item | github.repo.repository.size Preprocessing
|
Repository stargazers | The number of GitHub users who have starred the repository. |
Dependent item | github.repo.repository.stargazers Preprocessing
|
Repository watchers | The number of GitHub users who are subscribed to the repository. |
Dependent item | github.repo.repository.watchers Preprocessing
|
Repository forks | The number of repository forks. |
Dependent item | github.repo.repository.forks.count Preprocessing
|
Get workflows | Get the repository workflows. Information about endpoint: https://docs.github.com/en/rest/actions/workflows?apiVersion=2022-11-28#list-repository-workflows |
Script | github.repo.workflows.get Preprocessing
|
Get branches | Get the repository branches. Information about endpoint: https://docs.github.com/en/rest/branches/branches?apiVersion=2022-11-28#list-branches |
Script | github.repo.branches.get Preprocessing
|
Triggers
Name | Description | Expression | Severity | Dependencies and additional info |
---|---|---|---|---|
GitHub: No access to repository self-hosted runners | Admin access to the repository is required to use this endpoint: |
find(/GitHub repository by HTTP/github.repo.runners.get.check,,"iregexp","Must have admin rights to Repository")=1 |
Average | |
GitHub: The total number of issues has increased | The total number of issues has increased which means that either a new issue (or multiple) has been opened. |
last(/GitHub repository by HTTP/github.repo.issues.total)>last(/GitHub repository by HTTP/github.repo.issues.total,#2) |
Warning | |
GitHub: The total number of PRs has increased | The total number of pull requests has increased which means that either a new pull request (or multiple) has been opened. |
last(/GitHub repository by HTTP/github.repo.pr.total)>last(/GitHub repository by HTTP/github.repo.pr.total,#2) |
Info | |
GitHub: API request limit utilization is high | The API request limit utilization is high. It can be lowered by increasing the update intervals for script items (by setting up higher values in corresponding context macros). |
max(/GitHub repository by HTTP/github.repo.requests.util,1h)>{$GITHUB.REQUESTS.UTIL.WARN} |
Warning | Depends on:
|
GitHub: API request limit utilization is very high | The API request limit utilization is very high. It can be lowered by increasing the update intervals for script items (by setting up higher values in corresponding context macros). |
max(/GitHub repository by HTTP/github.repo.requests.util,1h)>{$GITHUB.REQUESTS.UTIL.HIGH} |
Average | |
GitHub: There are errors in requests to API | Errors have been received in response to API requests. Check the latest values for details. |
length(last(/GitHub repository by HTTP/github.repo.repository.get.check))>0 |
Average |
LLD rule Workflow discovery
Name | Description | Type | Key and additional info |
---|---|---|---|
Workflow discovery | Discovers repository workflows. By default, only the active workflows are discovered. Information about endpoint: https://docs.github.com/en/rest/actions/workflows?apiVersion=2022-11-28#list-repository-workflows |
Dependent item | github.repo.workflows.discovery Preprocessing
|
Item prototypes for Workflow discovery
Name | Description | Type | Key and additional info |
---|---|---|---|
Workflow [{#WORKFLOW_NAME}]: Get last run | Get the data about the last workflow run. Information about endpoint: https://docs.github.com/en/rest/actions/workflow-runs?apiVersion=2022-11-28#list-workflow-runs-for-a-workflow |
Script | github.repo.workflows.last_run.get[{#WORKFLOW_NAME}] Preprocessing
|
Workflow [{#WORKFLOW_NAME}]: Last run status | The status of the last workflow run. Possible values: 0 - queued 1 - in_progress 2 - completed 10 - unknown |
Dependent item | github.repo.workflows.last_run.status[{#WORKFLOW_NAME}] Preprocessing
|
Workflow [{#WORKFLOW_NAME}]: Last run conclusion | The conclusion of the last workflow run. Possible values: 0 - success 1 - failure 2 - neutral 3 - cancelled 4 - skipped 5 - timed_out 6 - action_required 10 - unknown |
Dependent item | github.repo.workflows.last_run.conclusion[{#WORKFLOW_NAME}] Preprocessing
|
Workflow [{#WORKFLOW_NAME}]: Last run start date | The date when the last workflow run was started. |
Dependent item | github.repo.workflows.last_run.start_date[{#WORKFLOW_NAME}] Preprocessing
|
Workflow [{#WORKFLOW_NAME}]: Last run update date | The date when the last workflow run was updated. |
Dependent item | github.repo.workflows.last_run.update_date[{#WORKFLOW_NAME}] Preprocessing
|
Workflow [{#WORKFLOW_NAME}]: Last run duration | The duration of the last workflow run. |
Dependent item | github.repo.workflows.last_run.duration[{#WORKFLOW_NAME}] Preprocessing
|
Trigger prototypes for Workflow discovery
Name | Description | Expression | Severity | Dependencies and additional info |
---|---|---|---|---|
GitHub: Workflow [{#WORKFLOW_NAME}]: The workflow has been in the queue for too long | The last workflow run has been in the "queued" status for too long. This may mean that it has failed to be assigned to a runner. The default threshold is provided as an example and can be adjusted for relevant workflows with context macros. |
last(/GitHub repository by HTTP/github.repo.workflows.last_run.status[{#WORKFLOW_NAME}])=0 and changecount(/GitHub repository by HTTP/github.repo.workflows.last_run.status[{#WORKFLOW_NAME}],{$GITHUB.WORKFLOW.STATUS.QUEUED.THRESH:"workflow_queued:{#WORKFLOW_NAME}"})=0 |
Warning | |
GitHub: Workflow [{#WORKFLOW_NAME}]: The workflow has been in progress for too long | The last workflow run has been in the "in_progress" status for too long. The default threshold is provided as an example and can be adjusted for relevant workflows with context macros. |
last(/GitHub repository by HTTP/github.repo.workflows.last_run.status[{#WORKFLOW_NAME}])=1 and changecount(/GitHub repository by HTTP/github.repo.workflows.last_run.status[{#WORKFLOW_NAME}],{$GITHUB.WORKFLOW.STATUS.IN_PROGRESS.THRESH:"workflow_in_progress:{#WORKFLOW_NAME}"})=0 |
Warning | |
GitHub: Workflow [{#WORKFLOW_NAME}]: The workflow has failed | The last workflow run has returned a "failure" conclusion. |
last(/GitHub repository by HTTP/github.repo.workflows.last_run.conclusion[{#WORKFLOW_NAME}])=1 |
Warning |
LLD rule Branch discovery
Name | Description | Type | Key and additional info |
---|---|---|---|
Branch discovery | Discovers repository branches. Information about endpoint: https://docs.github.com/en/rest/branches/branches?apiVersion=2022-11-28#list-branches |
Dependent item | github.repo.branches.discovery Preprocessing
|
Item prototypes for Branch discovery
Name | Description | Type | Key and additional info |
---|---|---|---|
Branch [{#BRANCH_NAME}]: Number of commits | Get the number of commits in the branch. Information about endpoint: https://docs.github.com/en/rest/commits/commits?apiVersion=2022-11-28#list-commits |
Script | github.repo.branches.commits.total[{#BRANCH_NAME}] Preprocessing
|
LLD rule Self-hosted runner discovery
Name | Description | Type | Key and additional info |
---|---|---|---|
Self-hosted runner discovery | Discovers self-hosted runners of the repository. Note that admin access to the repository is required to use this endpoint: https://docs.github.com/en/rest/actions/self-hosted-runners?apiVersion=2022-11-28#list-self-hosted-runners-for-a-repository |
Dependent item | github.repo.runners.discovery Preprocessing
|
Item prototypes for Self-hosted runner discovery
Name | Description | Type | Key and additional info |
---|---|---|---|
Runner [{#RUNNER_NAME}]: Busy | Indicates whether the runner is currently executing a job. |
Dependent item | github.repo.runners.busy[{#RUNNER_NAME}] Preprocessing
|
Runner [{#RUNNER_NAME}]: Online | Indicates whether the runner is connected to GitHub and is ready to execute jobs. |
Dependent item | github.repo.runners.online[{#RUNNER_NAME}] Preprocessing
|
Trigger prototypes for Self-hosted runner discovery
Name | Description | Expression | Severity | Dependencies and additional info |
---|---|---|---|---|
GitHub: Runner [{#RUNNER_NAME}]: The runner has become offline | The runner was online previously, but is currently not connected to GitHub. This could be because the machine is offline, the self-hosted runner application is not running on the machine, or the self-hosted runner application cannot communicate with GitHub. |
last(/GitHub repository by HTTP/github.repo.runners.online[{#RUNNER_NAME}],#2)=1 and last(/GitHub repository by HTTP/github.repo.runners.online[{#RUNNER_NAME}])=0 |
Warning |
LLD rule Discovery of community profile metrics
Name | Description | Type | Key and additional info |
---|---|---|---|
Discovery of community profile metrics | Discovers community profile metrics (the repository must not be a fork). Information about community profile metrics: https://docs.github.com/en/rest/metrics/community?apiVersion=2022-11-28#get-community-profile-metrics |
Dependent item | github.repo.community_profile.discovery Preprocessing
|
Item prototypes for Discovery of community profile metrics
Name | Description | Type | Key and additional info |
---|---|---|---|
Health percentage score | The health percentage score is defined as a percentage of how many of the recommended community health files are present. For more information, see the documentation: https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/about-community-profiles-for-public-repositories |
Dependent item | github.repo.repository.health[{#SINGLETON}] Preprocessing
|
Feedback
Please report any issues with the template at https://support.zabbix.com
You can also provide feedback, discuss the template, or ask for help at ZABBIX forums