Configuring GitLab Observer jobs

Using the GitLab Observer, you can define a full load job that will dynamically load GitLab projects and their child resources, and visualize this data as a topology view in the Agile Service Manager UI.

Before you begin

Important: The GitLab Observer supports the API version 15.2.

Ensure you have the GitLab server details to hand, such as hostname, private token, datacenter and certificate.

The observer is installed as part of the core installation procedure.

About this task

The GitLab Observer job extracts GitLab resources information via REST API calls. The observer loads and updates the resources and their relationships within the Agile Service Manager core topology service.

You define and start the following jobs.

Load job: Run this job whenever you need GitLab topology data refreshed.; By default, these jobs are one-off, transient jobs that perform a full upload of all requested topology data as soon as they are triggered.; You can also run these jobs (again) manually from the Observer UI, or schedule them to run at set times when configuring them.; This job is started by the gitlab_observer_load_start.sh script

The GitLab Observer loads the following resources and their relationship into the Agile Service Manager core topology service:

Table 1. GitLab resources and relationships loaded by the GitLab Observer job
Vertex	Description
Project	Elements used to host codebase
IssuesManager	Manager of issues – Dummy vertex
MergeRequestsManager	Manager of Merge requests – Dummy vertex
PackagesBuilder	Manager of packages – Dummy vertex
Pipeline	Component that can trigger sequences and jobs for CI, delivery and deployment
ReleasesManager	Manager of release – Dummy vertex
MergeRequests	Use to check source code changes into a branch (PR)
Issues	Use issues to collaborate on ideas, solve problems, and plan work
Jobs	Smallest unit to run in GitLab CI/CD, can be a build or compilation task
Releases	A checkpoint on the source code history
Packages	Repository for a variety of common package managers

Procedure

Configure a GitLab Observer job

On the Observer jobs page, perform one of the following actions:

To edit an existing job

Open the List of options overflow menu next to the job and click View & edit.

To create a new job

Click Add a new job + and select the GitLab Observer tile.

Define the following parameters, then click Save to save and run the job.

Table 2. **Load** job parameters
Parameter	Action	Details
Unique ID	Enter a unique name for the job.	Required
GitLab Hostname	Enter the GitLab server name.	Required.
Repository Visibility	Choose a visibility for the repository. Options are 'private', 'public' or 'both'.	Required. Default is 'both'.
Project Access	Choose a project access type. Options are 'membership' or 'owned'.	Required. Default is 'membership'.
No Of Projects	Enter the number of projects to be displayed in the topology.	Required. Default is '50'. Must be a value greater than 0 (zero)
Private Token	Provide the private token for the GitLab account.	Required. Use plain text.
Data tenant	The data tenant is used to track your data. It must be unique for each job or else it will override the previously discovered data.	Required
Target system certificate	Specify a certificate by name to load into the trustStore.	Required. To obtain authentication certificates using OpenSSL and store them as secrets, see Configuring observer job security. On-prem Create and store the certificate in the ASM_HOME/security directory. OCP Obtain the authentication certificate using OpenSSL and store it as a secret.
GitLab Port	Enter the GitLab port number for the REST API.	Optional. Default is 443.
SSL Host Name Verification	Choose whether SSL validation is true or false. When SSL validation is set to false, the observer will make HTTPS connection without validating the hostname of the provided certificate.	Optional. Default is False.
Connection timeout	Specify the connection timeout in ms.	Optional. Must be a value greater than 0 (zero), and the default is 5000 (5 seconds).
Read timeout	Specify the read timeout in ms.	Optional. Must be a value greater than 0 (zero), and the default is 5000 (5 seconds).
State for the issue	Return all issues or just those that are opened or closed issues to be shown in topology.	Optional. Default is 'opened'.
Status of the pipeline	Define a status. Options are: created waiting_for_resource preparing pending running success failed canceled skipped manual scheduled	Optional. Default is 'created'.
Access scope	Enter text to provide a scope for the resources. Access scope can help map alerts to resources when resources in different scopes share the same parameters, such as matchTokens.	Optional. Tip: You can define access scope for locations, project names, namespaces, etc.
Generate debug support file	Set the optional Generate debug support file parameter to 'True' in order to capture the output of the next scheduled job run as a file. This file will be stored with an observer's log files and can be used to debug observer issues, for example at the request of your designated Support team, or while using a test environment. For one-off jobs (that is, Load jobs), this parameter reverts to 'False' after the next completed run. To examine the output produced, you can load the generated debug file using the File Observer. The file is saved to the following locations: On-prem $ASM_HOME/logs/<obs>-observer/ On OCP /var/log/itsm/<obs>-observer	Optional
Observer job description	Enter additional information to describe the job.	Optional
Job schedule	Specify when the job should run, and whether it should run at regular intervals. By default the job runs immediately, and only once. Optionally you can specify a future date and time for the job to run, and then set it to run at regular intervals after that.	Optional. Transient (one-off) jobs only. If you set a job schedule, the run intervals must be at least 90 seconds apart, and if you set them at less than 15 minutes, a warning is displayed, as the frequency can impact system performance.