AppSec Engineer's Local Setup

When evaluating security issues or MRs, it can be useful to have a way to reproduce issues, dig in to root causes, look for further impacts. This can also be a great way to get familiar with GitLab during your first few weeks of onboarding. Here are some handy tips & tricks.

How to setup a local GDK environment

Request a license using this form to Request a team member license with Ultimate and at least 100 seats (this would avoid removing the ~50 users allready added to the gdk at install)
If you plan to replace an existing local install of a GDK or do the setup for geo, first run in the existing gdk folder gdk kill. This will stop the processes and release the ports used by different services.
General information about the gdk install steops can be found at gitlab-development-kit
- Start the one line install with curl "https://gitlab.com/gitlab-org/gitlab-development-kit/-/raw/main/support/install" | bash
- install in gdk, or choose the folder name
- install with mise
- once the install finihed do a gdk restart to make sure all services started
Once the install is done login with root / 5iveL!fe and change the default password
Apply the license, either via admin/settings/addlicense or using the [rails console(https://docs.gitlab.com/administration/license_file/#add-a-license-through-the-console)].
Check if the licese was applied correctly in admin/subscription(http://localhost:3000/admin/subscription)

Enable Gitlab Duo in GDK

Prerequisites:

Working GDK intall
GCP console access. Log in to gcp console if you have access to ai-enablement-dev-69497ba7 project. If access is needed, submit an AR with this
gcloud CLI is installed. Run glcoud init to setup the default configuration
Anthropic license key. Submit an access request here using the Anthropic_Console_Access_Request. This link should start a new issue with the template applied.
Search for Fireworks license key from 1password.

Setting up the Gitlab AI Gateway

Following is a summary from the how to configure the Gitlab AI Gateway:

In the gdk folder run gdk rake setup_ai_gateway

The prompts are:

Enter your Anthropic API key: The key you enter will be used to authenticate requests to Anthropic’s AI services. It’s essential for accessing their API and using their AI models.
Enter your Fireworks API key: The key you enter will be used to authenticate requests to Fireworks’s API services. This key is currently available on 1Password, in the Engineering or the Security Folder, under the name (Fireworks development key)
Set additional environment variables for debugging: It will set additional environment variables that provide more detailed logs and information, useful for troubleshooting and development.
Enable AI Gateway in SaaS: Option to enable the AI Gateway in a SaaS configuration. Answer with (Y) it needs to run SASS mode. If you answer no (N), the GDK runs in self-managed mode.
Enable hot reload: It will enable hot reloading, which allows the application to update in real-time as you make code changes, without requiring a full restart

Once the install is done move to the gdk/gitlab and run the following commands:

gdk config set duo_workflow.enabled true
gdk reconfigure
gdk restart duo-workflow-service rails
Login with the admin user and you should see a new group named gitlab-duo http://localhost:3000/gitlab-duo. Add users to this group to get access to AI features at http://localhost:3000/groups/gitlab-duo/-/group_members.
Note: if you are testing GitLab Duo in GDK with multiple users, after inviting an user to GitLab Duo group, (as the admin) go to Settings > GitLab Duo > Assign seats and enable the “GitLab Duo Enterprise” option for that user.

seat_utilization

Once the install is done you can confirm it is working by looking into http://<your-gdk-url>/help/instance_configuration#ai_gateway_url and look for AI Gateway URL: http://127.0.0.1:5052. For debugging use gdk tail gitlab-ai-gateway, this will show debug messages and AI responses.

Enable Duo with VS code

With a user that has access to the AI features, create a PAT with API access
Download and install VS code
From Extensions install Gitlab Workflow
Configure a VS code profile for GDK go to Code > Settings > Profiles > New Profile
In VS code, open the Command Palette (Command + Shift + P) and select “GitLab Select Account for this Workspace” to switch to your GDK account. PAT should be added here
Gitlab Agent should be added on left tool bar

Link the VS Code Duo extension to Language Server

The following sequence illustrates how an IDE extension authenticates with the GitLab instance and later Duo Workflow Service.

sequenceDiagram
    participant ext as Editor Extension
    participant lsp as GitLab Language Server
    participant sm as GitLab
    participant aigw as AI Gateway (GitLab-hosted)
    participant dws as Duo Workflow Service (GitLab-hosted)

    ext-->>lsp: Send workspace configuration
    par Fetch Personal Access Token info
        lsp->>+sm: GET /api/v4/personal_access_tokens/self
        sm->>-lsp: 200 OK {...}
    and Fetch OAuth token info
        lsp->>+sm: GET /oauth/token/info
        sm->>-lsp: 200 OK {...}
        Note right of lsp: Store OAuth access token until just before expiry
    end

    loop Every ~120 minutes
        lsp->>+sm: GET /api/v4/ai/duo_workflows/direct_access
        sm->>+dws: Send GenerateToken request (gRPC)
        Note right of dws: duo_workflow_service/server.py generates a signed JWT through the Cloud Connector library code.
        dws->>-sm: ServiceResponse.success
        sm->>-lsp: 200 OK {...}
        Note right of lsp:  Store direct access details for Duo Workflow Service for ~120 minutes
    end

Note: these steps are an expansion from the existing steps in documentation.

All of below steps are completed as the GitLab user profile:

Clone the gitlab-vscode-extension project.
Clone the gitlab-lsp project in the same path as your VS Code extension project, for example:
- LSP is in /Users//Projects/gitlab-lsp
- vscode extension is in /Users//Projects/gitlab-vscode-extension
Have the two project open side by side in a terminal for better setup.
For gitlab-vscode-extension project, follow below steps:
- Run: npm install
- Run extension in dev mode:
  1. Open the project in vscode
  2. Run the View: Show Run and Debug command (Cmd+Shift+P).
  3. Ensure the Run Extension command is selected.
  4. Select the green play icon, or press F5.
For gitlab-lsp project, follow below steps:
1. Open the project in vscode
2. Run npm install
3. Run npm run build
4. Run GITLAB_WORKFLOW_PATH=/Users/<USERNAME>/Projects/gitlab-vscode-extension code .
5. Run the Attach to VS Code Extension launch task.
6. Run npm run watch -- --editor=vscode --packages agentic-duo-chat webview-duo-workflow duo-chat duo-chat-v2 webview-duo-chat webview-duo-chat-v2 webview-vuln-details
Verification: to verify it’s working, first make sure you have enabled the GitLab debugging option in the Duo Workflow extension setting and then restart the extension so that you can see debug logs:

Verification debug

Connect LS with Local GDK Changes for Duo Development

Setup a GDK profile
Follow the two steps outlined in the doc

In VSCode, check for “GitLab Language Server” logs in the output pane and see there are any errors. If you come across token errors like below, then go to GitLab Workflow extension setting and make sure ignore TLS/SSL cert errors option is ticked:

2025-08-20T10:54:14:972 [warning]: Both PAT and OAuth token checks failed: PAT Token: {"valid":false,"reason":"unknown","message":"Token validation failed: Error: request to https://gdk.test:3443/api/v4/personal_access_tokens/self failed, reason: unable to verify the first certificate"}, OAuth Token: {"valid":false,"reason":"unknown","message":"Token validation failed: Error: request to https://gdk.test:3443/oauth/token/info failed, reason: unable to verify the first certificate"}
2025-08-20T10:54:14:973 [info]: [CodeSuggestionsInstanceTelemetry] Instance Telemetry: GitLab Duo Code Suggestions telemetry is always enabled in self-managed instances.
2025-08-20T10:54:14:973 [warning]: Token is invalid. Token validation failed: Error: request to https://gdk.test:3443/api/v4/personal_access_tokens/self failed, reason: unable to verify the first certificate. Reason: unknown
2025-08-20T10:54:14:973 [warning]: Token is invalid. No token provided. Reason: invalid_token

Setup_language_server

Restart the extension and to check if it’s working, open a GDK folder (git clone a GDK project locally, make sure it has Duo enabled) and check the logs for errors, an example of a working agentic workflow log:

2025-08-20T11:13:46:002 [info]: [Duo Agentic Chat Plugin] Received new event
2025-08-20T11:13:46:002 [debug]: [WebviewInstanceMessageBus:agentic-duo-chat:8327ccee-1b85-48ba-abd6-eb4cfb5e3f1f] Sending notification: workflowCheckpoint
2025-08-20T11:13:46:002 [debug]: [WebviewInstanceMessageBus:agentic-duo-chat:8327ccee-1b85-48ba-abd6-eb4cfb5e3f1f] Sending notification: workflowStatus
2025-08-20T11:13:46:503 [debug]: [WorkflowTokenService] Reusing existing valid token for workflow "3"
2025-08-20T11:13:46:503 [debug]: [DuoWorkflowNodeExecutor][3] Received new checkpoint: {"workflowStatus":"RUNNING"}

Step through execution chains

If you want to see the code executed as part of a web or API request, an interactive debugger may be a useful tool. Here’s how to configure Pry & Thin

A typical workflow might be to find the Controller action which kicks off the request (methods like create or update are good bets), add in binding.pry, save the file, then perform that request in a browser. The execution will stop and in a terminal you can inspect the current state using IRB, type step to go in_to_ a method, next to go to the next statement, and continue to let the request run to the next break point and/or completion.

Watching logs can be helpful: tail -f gitlab/log/development.log.

Install a testing proxy

Your role might not require you to do “penetration testing”, but having access to a testing proxy that lets you intercept and manipulate requests can help with reproducing HackerOne issues.

The AppSec team have a multi-user license for Burp Suite Professional. Ask in #sec-appsec about getting a license, and (download the latest stable version here). You can also use OWASP ZAP which is free and open source.

These tools can easily cause damage to websites or eat up your CPU with active scans. In OWASP Zap, use “Safe” mode to prevent any potentially malicious requests. In Burp Suite, disable any live “audit” scans.

Browser Profiles

When testing requires using multiple users, an Incognito / Private tab is an easy option. You can also create and use un-signed-in Chrome Profiles or Firefox Multi-Account Containers to provide “session sandboxes”, which will persist beyond window closure (unlike Incognito tabs) and you can colour code them to help with visual distinction.

Mocking Servers / tunnels

Making your local machine accessible from the internet is not permitted, which precludes tools like ngrok or localtunnel. Use GitLab’s Sandbox Cloud to host mock servers instead. Refer to Secure Cloud testing environments for advice on how to secure your Sandbox Cloud test environments.

Debugging and GDK tips

gdk update Pull application changes from Git
gdk tail Tail logs for all services
gdk tail gitlab-ai-gateway Tail logs for AI services
gdk doctor Run diagnostics on GDK
gdk kill Forcibly kills services - usefull when a service hangs a port or when to upgrade
Feature flags can be enabled via http://127.0.0.1:3000/rails/features

Last modified September 5, 2025: Fix image path links (0bb12a10)

View page source - Edit this page - please contribute.