---
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

---

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