Integrations

Connect GitHub or GitLab to show live pull request, merge request, and issue details on Feature links. Webhooks can add pull or merge request links to Stories, Tasks, and Bugs automatically. They also complete linked work when all requests are closed and at least one is merged. You can also send application logs to Seq.

Connect GitHub and GitLab link cards

Set integration defaults in the Integrations section of Instance settings, or provide the matching environment variables. Settings saved in the app override the environment defaults for the GitHub and GitLab tokens and the GitLab URL. SHIPLEAN_GITHUB_API_URL can be set only in the environment. Clearing the saved GitLab URL restores the environment URL and token pair. The environment token is never combined with a saved GitLab URL.

Setting	What it enables
SHIPLEAN_GITHUB_TOKEN	Lets GitHub Feature links show private issue and pull request details, as well as public ones. Without a token, only public repositories can be read.
SHIPLEAN_GITHUB_API_URL	GitHub API endpoint. Keep the default https://api.github.com, or set a GitHub Enterprise Server API URL such as https://github.example.com/api/v3.
SHIPLEAN_GITLAB_URL	The GitLab host whose Feature issue and merge request links ShipLean reads, such as https://gitlab.example.com. Other GitLab hosts remain ordinary links.
SHIPLEAN_GITLAB_TOKEN	Lets GitLab Feature links show private issue and merge request details on the configured GitLab host.

Tokens are sent only to HTTPS API addresses. The app does not save a token with an HTTP URL. Store tokens in instance settings or in your secret manager. Give each token only the read access it needs to retrieve issue and request details.

To use environment values only, add these settings to your deployment environment:

SHIPLEAN_GITHUB_TOKEN=<github-read-token>
SHIPLEAN_GITHUB_API_URL=https://api.github.com
SHIPLEAN_GITLAB_URL=https://gitlab.example.com
SHIPLEAN_GITLAB_TOKEN=<gitlab-read-token>

Omit the GitLab settings if you do not use GitLab. To use GitHub Enterprise Server, point SHIPLEAN_GITHUB_API_URL at its API endpoint. The integration makes API requests only to configured HTTPS hosts.

Turn on pull request webhooks

Webhooks let GitHub or GitLab tell ShipLean when a request opens, changes, merges, or closes. Each provider has its own secret and endpoint. While a provider’s secret is unset, its endpoint returns 404. Set the secret on ShipLean first, then configure the same value in the provider.

Generate a separate long random secret for each provider. For example:

openssl rand -hex 32

Set one or both values in the ShipLean environment:

SHIPLEAN_GITHUB_WEBHOOK_SECRET=<github-webhook-secret>
SHIPLEAN_GITLAB_WEBHOOK_SECRET=<gitlab-webhook-secret>

When ShipLean is behind an identity proxy, configure the proxy to skip sign-in for /api/webhooks/. The webhook endpoint authenticates deliveries with its provider secret. GitHub must send Content-Type: application/json, and GitLab posts JSON. See sign-in options for the proxy path requirements.

Configure GitHub

On a repository, open Settings, select Webhooks, and choose Add webhook. An organization owner can add an organization webhook under Organization settings, then Webhooks, then Add webhook. The organization webhook covers the organization’s repositories. Set:

• Payload URL: https://shiplean.example.com/api/webhooks/github
• Content type: application/json
• Secret: the value of SHIPLEAN_GITHUB_WEBHOOK_SECRET
• Which events: select Let me select individual events, then Pull requests only.
• Make sure the webhook is Active, then add it.

GitHub sends a ping when you create the webhook. ShipLean responds with pong.

Configure GitLab

On a project, open Settings, select Webhooks, and choose Add new webhook. A group owner can create a group webhook for the group’s projects. Set:

• URL: https://shiplean.example.com/api/webhooks/gitlab
• Secret token: the value of SHIPLEAN_GITLAB_WEBHOOK_SECRET
• Trigger: Merge request events only.

GitLab’s current webhook UI offers a signing token as a stronger option than a plain secret token. ShipLean currently verifies the X-Gitlab-Token secret-token header, so use the Secret token field for this integration. A GitLab signing token is not compatible with this endpoint.

GitLab’s menu and fields are documented in Configure webhooks. GitHub’s webhook creation guide documents the payload URL, JSON content type, secret, event selection, and ping delivery.

Link and complete work from requests

Put a work item key in the pull or merge request title or its source branch. ShipLean checks the title and the source branch. Titles must use an uppercase key of two to four letters and digits, such as SHIP-123. Branch keys can use any case, such as feature/ship-123-search.

Only existing Stories, Tasks, and Bugs are linked. Features and Epics are ignored. The link card shows whether the request is open, merged, or closed. ShipLean does not create work items from webhook payloads.

An item moves to its type’s first Completed state when all pull or merge requests linked to it are merged or closed, and at least one has merged. A close without a merge does not complete an item on its own. If an item has several linked requests, one that is still open, or one with no event yet, keeps the item open. Reopening a request updates its card but does not reopen a completed work item.

If someone removes an auto-created link, ShipLean does not add it again. Removing the key from a title later also leaves the existing link in place. You can inspect webhook deliveries in each provider’s delivery log.

Each provider’s endpoint accepts events from any repository or group that holds the right secret. ShipLean has no repository allowlist. Keep each secret private. To rotate a secret, change the matching environment variable. Each provider can be disabled on its own by unsetting its secret, after which its endpoint returns 404.

Send logs to Seq

Set SHIPLEAN_SEQ_URL to your Seq server’s ingestion endpoint. If the Seq instance requires an API key, set SHIPLEAN_SEQ_API_KEY as well. ShipLean writes logs to the console and also sends them to Seq.

SHIPLEAN_SEQ_URL=http://seq.example.com:5341
SHIPLEAN_SEQ_API_KEY=<seq-ingestion-key>

Use HTTPS when the endpoint is reachable over an untrusted network. Keep the API key in your deployment’s secret store.

Export traces, metrics, and logs

To send telemetry to an OTLP collector, set OTEL_EXPORTER_OTLP_ENDPOINT. This enables traces, metrics, and logs. Without it, OTLP export is off. ShipLean keeps logging to the console and, when Seq is configured, to Seq.

OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.example.com
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_HEADERS=api-key=<collector-api-key>
OTEL_SERVICE_NAME=shiplean-production
OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production

Set the protocol to the one your collector accepts, either grpc or http/protobuf. With http/protobuf, the exporter adds signal paths such as /v1/logs. Put credentials in OTEL_EXPORTER_OTLP_HEADERS, and keep them in your deployment’s secret store. OTEL_SERVICE_NAME defaults to shiplean. The resource attributes are optional. For OTLP details, see the OpenTelemetry .NET configuration reference.

For every integration variable and its defaults, see configuration.