---
title: "ParseContextURL"
method: POST
path: "/gitpod.v1.RunnerService/ParseContextURL"
tags: ["gitpod.v1.RunnerService"]
---

# ParseContextURL

`POST /gitpod.v1.RunnerService/ParseContextURL`

Parses a context URL and returns the parsed result.

 Use this method to:
 - Validate context URLs
 - Check repository access
 - Verify branch existence

 Returns:
 - FAILED_PRECONDITION if authentication is required
 - PERMISSION_DENIED if access is not allowed
 - INVALID_ARGUMENT if URL is invalid
 - NOT_FOUND if repository/branch doesn't exist

 ### Examples

 - Parse URL:

   Parses and validates a context URL.

   ```yaml
   contextUrl: "https://github.com/org/repo/tree/main"
   ```

## Request body

- GitpodV1ParseContextURLRequest
  - `contextUrl` string, uri
  - `runnerId` string, uuid

## Response `200`

Success

- GitpodV1ParseContextURLResponse
  - `git` GitpodV1ParseContextURLResponseGitContext
    - `branch` string
    - `cloneUrl` string
    - `commit` string
    - `host` string
    - `owner` string
    - `repo` string
    - `tag` string
    - `upstreamRemoteUrl` string
  - `issue` GitpodV1ParseContextURLResponseIssue
    - `id` string — id is the source system's ID of this issue, e.g. BNFRD-6100
    - `title` string
  - `originalContextUrl` string
  - `pr` GitpodV1ParseContextURLResponsePullRequest — Deprecated: Use top-level PullRequest message instead
    - `fromBranch` string
    - `id` string
    - `title` string
    - `toBranch` string
  - `projectIds` string[] — project_ids is a list of projects to which the context URL belongs to.
  - `pullRequest` GitpodV1PullRequest — PullRequest represents pull request metadata from source control systems. This message is used across workflow triggers, executions, and agent contexts to maintain consistent PR information throughout the system.
    - `author` string — Author name as provided by the SCM system
    - `draft` boolean — Whether this is a draft pull request
    - `fromBranch` string — Source branch name (the branch being merged from)
    - `headSha` string — Current revision identity for the PR head commit. Used internally for workflow execution deduplication and excluded from customer SDKs.
    - `id` string — Unique identifier from the source system (e.g., "123" for GitHub PR #123)
    - `repository` GitpodV1PullRequestRepository — Repository information
      - `cloneUrl` string
      - `host` string
      - `name` string
      - `owner` string
    - `state` 'STATE_UNSPECIFIED' | 'STATE_OPEN' | 'STATE_CLOSED' | 'STATE_MERGED' — Current state of the pull request
    - `title` string — Pull request title
    - `toBranch` string — Target branch name (the branch being merged into)
    - `url` string — Pull request URL (e.g., "https://github.com/owner/repo/pull/123")
  - `recommendedEnvironmentClasses` string[] — recommended_environment_classes is an ordered list of environment class IDs that are suitable for creating an environment for this context URL.
  - `scmId` string — scm_id is the unique identifier of the SCM provider (e.g., "github", "gitlab", "bitbucket")

## Other responses

- `default` — Error

## Changes

> 18 revisions in range; 1 could not be searched.

- **2026-01-21** `2423c089f280` — 2 info
  - added the optional property `pullRequest/draft` to the response with the `200` status
  - added the optional property `pullRequest/state` to the response with the `200` status
- **2025-12-15** `d62ef4b9187c` — 5 info
  - added the optional property `git/tag` to the response with the `200` status
  - added the optional property `issue` to the response with the `200` status
  - added the optional property `pr` to the response with the `200` status
  - added the optional property `pullRequest` to the response with the `200` status
  - …1 more
- **2025-06-10** `ca9a49ac7fbb` — 1 info
  - added the optional property `projectIds` to the response with the `200` status
- **2025-02-21** `3655d5ad0ac3` — 1 breaking, 8 info
  - the `git` response's property type/format changed from ``/`` to `object`/`` for status `200`
  - added the optional property `git/branch` to the response with the `200` status
  - added the optional property `git/cloneUrl` to the response with the `200` status
  - added the optional property `git/commit` to the response with the `200` status
  - …5 more
- **2025-02-18** `cd6a05ae99d2` — 1 warning
  - removed the optional property `detail` from the response with the `default` status

[Change history](https://skmtc.dev/gitpod-io/apis/gitpod-v1/changes/gitpod.v1.RunnerService/ParseContextURL/post.md)

---

[API](https://skmtc.dev/gitpod-io/apis/gitpod-v1.md) · [All operations](https://skmtc.dev/gitpod-io/apis/gitpod-v1/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/gitpod-io/gitpod-v1/revisions/44d50c2ac284/schema)