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.

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

Body ParametersJSONExpand Collapse

contextUrl: optional string

formaturi

runnerId: optional string

formatuuid

ReturnsExpand Collapse

git: optional object { branch, cloneUrl, commit, 5 more }

branch: optional string

cloneUrl: optional string

commit: optional string

host: optional string

owner: optional string

repo: optional string

tag: optional string

upstreamRemoteUrl: optional string

issue: optional object { id, title }

id: optional string

id is the source system’s ID of this issue, e.g. BNFRD-6100

title: optional string

originalContextUrl: optional string

Deprecatedpr: optional object { id, fromBranch, title, toBranch }

Deprecated: Use top-level PullRequest message instead

id: optional string

fromBranch: optional string

title: optional string

toBranch: optional string

projectIds: optional array of string

project_ids is a list of projects to which the context URL belongs to.

pullRequest: optional object { id, author, draft, 6 more }

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.

id: optional string

Unique identifier from the source system (e.g., “123” for GitHub PR #123)

author: optional string

Author name as provided by the SCM system

draft: optional boolean

Whether this is a draft pull request

fromBranch: optional string

Source branch name (the branch being merged from)

repository: optional object { cloneUrl, host, name, owner }

Repository information

cloneUrl: optional string

host: optional string

name: optional string

owner: optional string

state: optional State

Current state of the pull request

One of the following:

"STATE_UNSPECIFIED"

"STATE_OPEN"

"STATE_CLOSED"

"STATE_MERGED"

title: optional string

Pull request title

toBranch: optional string

Target branch name (the branch being merged into)

url: optional string

Pull request URL (e.g., “https://github.com/owner/repo/pull/123”)

scmId: optional string

scm_id is the unique identifier of the SCM provider (e.g., “github”, “gitlab”, “bitbucket”)

ParseContextURL

curl https://app.gitpod.io/api/gitpod.v1.RunnerService/ParseContextURL \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{}'

{
  "git": {
    "branch": "branch",
    "cloneUrl": "cloneUrl",
    "commit": "commit",
    "host": "host",
    "owner": "owner",
    "repo": "repo",
    "tag": "tag",
    "upstreamRemoteUrl": "upstreamRemoteUrl"
  },
  "issue": {
    "id": "id",
    "title": "title"
  },
  "originalContextUrl": "originalContextUrl",
  "pr": {
    "id": "id",
    "fromBranch": "fromBranch",
    "title": "title",
    "toBranch": "toBranch"
  },
  "projectIds": [
    "string"
  ],
  "pullRequest": {
    "id": "id",
    "author": "author",
    "draft": true,
    "fromBranch": "fromBranch",
    "repository": {
      "cloneUrl": "cloneUrl",
      "host": "host",
      "name": "name",
      "owner": "owner"
    },
    "state": "STATE_UNSPECIFIED",
    "title": "title",
    "toBranch": "toBranch",
    "url": "url"
  },
  "scmId": "scmId"
}

Returns Examples

{
  "git": {
    "branch": "branch",
    "cloneUrl": "cloneUrl",
    "commit": "commit",
    "host": "host",
    "owner": "owner",
    "repo": "repo",
    "tag": "tag",
    "upstreamRemoteUrl": "upstreamRemoteUrl"
  },
  "issue": {
    "id": "id",
    "title": "title"
  },
  "originalContextUrl": "originalContextUrl",
  "pr": {
    "id": "id",
    "fromBranch": "fromBranch",
    "title": "title",
    "toBranch": "toBranch"
  },
  "projectIds": [
    "string"
  ],
  "pullRequest": {
    "id": "id",
    "author": "author",
    "draft": true,
    "fromBranch": "fromBranch",
    "repository": {
      "cloneUrl": "cloneUrl",
      "host": "host",
      "name": "name",
      "owner": "owner"
    },
    "state": "STATE_UNSPECIFIED",
    "title": "title",
    "toBranch": "toBranch",
    "url": "url"
  },
  "scmId": "scmId"
}