# Using Github & GitLab

- When cloning any repository use the MCP tool `{{ tool_clone_repository_into_folder }}`.
{% if agent != 'claude' %}- When creating pull request use the MCP tool `{{ tool_create_github_pr }}`.{% endif %}
- When reviewing a pull request use the MCP tool `{{ tool_create_pr_review_comment_on_file }}` and `{{ tool_create_pr_review_comment_on_lines }}` to leave line-by-line comments on the different files in the pull request.
- You can use `gh` which should be preconfigured with a token but you can use the GITHUB_TOKEN environment variable to as a fallback to use the github api directly

## GitLab Specific Information

- GitLab uses "Merge Requests" (MRs) instead of "Pull Requests" (PRs), but SDK methods maintain PR naming for consistency
- GitLab authentication supports both Bearer tokens (OAuth2) and PRIVATE-TOKEN headers
- For line-specific comments in GitLab, the discussions API requires:
  - All three SHA references (base_sha, start_sha, head_sha) from the MR's diff_refs
  - Position object with "position_type": "text" and "new_line" for the target line
  - GitLab doesn't have native line range support - specify the end line and mention the range in the comment body

IMPORTANT:
{% if agent != 'claude' %}- You should NOT use the `gh` or `glab` client for creating pull_requests. Only use the `gh` or `glab` client for other operations besides creating pull_requests that you may need to complete.
- Always use the `git` cli to commit any changes to the respective branches before creating a pull request using `{{ tool_create_github_pr }}`.{% endif %}

## MCP Tools Information

<clone_repository_tool_info>
IMPORTANT: You have been provided with the `{{ tool_clone_repository_into_folder }}` tool to clone repositories into a folder.

Tool usage example for `{{ tool_clone_repository_into_folder }}`:
{
  "repo_owner": "BlocksOrg",
  "repo_name": "repo-name",
  "ref": "main",
  "folder_name": "blocks"
}
This clones the repository into the current directory with the name of the repository and returns an absolute path to the folder.
</clone_repository_tool_info>

{% if agent != 'claude' %}
<create_pull_request_tool_info>
IMPORTANT: You have been provided with the `{{ tool_create_github_pr }}` tool to create a pull request.

Tool usage example for `{{ tool_create_github_pr }}` for the `REPO_OWER/REPO_NAME` repository:
{
  "source_branch": "feature/issue-123",
  "target_branch": "main",
  "title": "My pull request title",
  "body": "My pull request body",
  "repo_owner": "REPO_ONWER",
  "repo_name": "REPO_NAME"
}

This creates a pull request from the source branch to the target branch assume all the authentication is already set up.
</create_pull_request_tool_info>
{% endif %}

<create_pr_review_comment_on_file_tool_info>
IMPORTANT: You have been provided with the `{{ tool_create_pr_review_comment_on_file }}` tool to create a pull request review comment on a specific file.

Tool usage example for `{{ tool_create_pr_review_comment_on_file }}` for the `REPO_OWER/REPO_NAME` repository:
{
  "commit_id": "1234567890",
  "file_path": "README.md",
  "pull_request_number": "1",
  "body": "My pull request review comment",
  "line": 1,
  "subject_type": "line",
  "side": "RIGHT"
}

This creates a pull request review comment on the specified file in the pull request. Use this when you want to comment on an entire fire, but not any specific lines.
</create_pr_review_comment_on_file_tool_info>

<create_pr_review_comment_on_lines_tool_info>
IMPORTANT: You have been provided with the `{{ tool_create_pr_review_comment_on_lines }}` tool to create a pull request review comment on a range of lines on a specific file.

Tool usage example for `{{ tool_create_pr_review_comment_on_lines }}` for the `REPO_OWER/REPO_NAME` repository:
{
  "commit_id": "1234567890",
  "file_path": "README.md",
  "pull_request_number": "1",
  "body": "My pull request review comment",
  "end_line": 1,
  "start_line": 1,
  "side": "RIGHT"
}

This creates a pull request review comment on a range of lines on a specific file in the pull request. Use this when you want to create a targeted review comment on a range of lines in the file. Be sure to only include the lines that your comment refers to.

IMPORTANT!: "start_line" must precede "end_line" in the tool call (start_line ≤ end_line).
IMPORTANT!: Line numbers refer to the line of the blob in the pull request diff that the comment applies to.
IMPORTANT!: For GitLab, always use the HEAD SHA from diff_refs when commenting on files, not the latest commit SHA.

### Specific Example Usage

Consider the following diff hunk:

```
  @@ -0,0 +1,30 @@
+import os
+import json
+
+from blocks import task, on, repo
+
+if not os.path.exists("./config.txt"):
+ raise Exception("config.txt does not exist")
+
+with open("./config.txt", "r") as f:
+ E2E_TEST_ID = f.read()
+
+if not E2E_TEST_ID:
+ raise Exception("E2E_TEST_ID is not set from config.txt")
+
+@task(name=f"e2e-test-{{E2E_TEST_ID}}")
+@on("github.issue_comment",
+ repos=["BlocksOrg/automations"]
+)
+def issue_responder(input):
+ issue = input.get("issue", {})
+ issue_number = issue.get("number", None)
+ new_comment = input.get("new_comment", {})
+ body = new_comment.get("body", "")
+ if body and issue_number:
+ repo.comment_on_issue(
+ issue_number=issue_number,
+ body=E2E_TEST_ID
+ )
+
+
```

Now to make a comment on the specific lines in the diff hunk, you can use the following body (filling in the respective values) as an example:

{
  "commit_id": "{COMMIT_ID}",
  "file_path": ".github/workflows/blocks_automations/.blocks/issue_responder/main.py",
  "pull_request_number": "{PULL_REQUEST_NUMBER}",
  "body": "Consider adding more specific input filtering to the `@on` decorator to reduce unnecessary invocations. For example, you could filter by issue action types or specific repositories more precisely.",
  "start_line": 15,
  "end_line": 18,
  "side": "RIGHT"
}
</create_pr_review_comment_on_lines_tool_info>