Github Port

Purpose

This is the Harbor reference integration for the GitHub REST API and Harbor's Action Model.

Use it when:

• building GitHub REST API actions in Harbor
• extending the Dock / Hub GitHub entry
• teaching Codex or OpenClaw how to map a developer-tool API into Harbor Ports and Harbor Actions without turning Harbor into a generic proxy

Harbor Port worksheet

Product

• Product: GitHub REST API
• Publisher slug: github
• Publisher name: GitHub
• Category: Developer Tools
• Tags: github, developer, issues, repositories, notifications

Safe Harbor Port metadata

• Kind: http_api
• Label: GitHub REST API
• Description: GitHub REST API connection managed locally through Harbor.
• Base URL: https://api.github.com/
• Auth mode: header_token
• Auth header name: Authorization
• Auth token prefix: Bearer

Hidden local config

• authToken

Harbor stores the token locally only. Dock / Hub manifests must never contain it.

Harbor action design notes

GitHub is a good Harbor fit today when we stay on fixed authenticated-user routes and bounded repo-scoped routes.

Harbor now also supports bounded input.path values for explicit repo-scoped capabilities.

Good Harbor GitHub actions:

• stable GET routes under /user, /issues, /notifications, and /user/repos
• explicit repo-scoped reads such as /repos/{owner}/{repo}, /repos/{owner}/{repo}/pulls, /repos/{owner}/{repo}/branches, and /repos/{owner}/{repo}/commits
• explicit bounded path templates like /repos/{owner}/{repo}/issues/{issue_number} and /repos/{owner}/{repo}/contents/{path}
• explicit fixed-path and repo-scoped write routes like /user/repos, /repos/{owner}/{repo}/pulls, and /repos/{owner}/{repo}/pulls/{pull_number}/merge
• requestBodyMode: "none" for reads
• requestBodyMode: "json" for bounded writes
• resultMode: "json_summary" for all starter actions

Avoid for now:

• broad administrative repository mutation surfaces
• giant multi-resource action sets imported all at once
• automatic publish of write actions

Starter GitHub actions

Automatic read actions

• get-authenticated-user -> GET /user
• list-my-issues -> GET /issues
• list-my-repositories -> GET /user/repos
• list-my-notifications -> GET /notifications
• list-my-organizations -> GET /user/orgs
• get-repository -> GET /repos/{owner}/{repo}
• list-repository-issues -> GET /repos/{owner}/{repo}/issues
• get-issue -> GET /repos/{owner}/{repo}/issues/{issue_number}
• list-issue-comments -> GET /repos/{owner}/{repo}/issues/{issue_number}/comments
• list-pull-requests -> GET /repos/{owner}/{repo}/pulls
• get-pull-request -> GET /repos/{owner}/{repo}/pulls/{pull_number}
• list-branches -> GET /repos/{owner}/{repo}/branches
• get-branch -> GET /repos/{owner}/{repo}/branches/{branch}
• list-commits -> GET /repos/{owner}/{repo}/commits
• get-commit -> GET /repos/{owner}/{repo}/commits/{ref}
• compare-two-commits -> GET /repos/{owner}/{repo}/compare/{basehead}
• get-repository-content -> GET /repos/{owner}/{repo}/contents/{path}

Approval-friendly write actions

• create-repository -> POST /user/repos
• create-issue -> POST /repos/{owner}/{repo}/issues
• create-issue-comment -> POST /repos/{owner}/{repo}/issues/{issue_number}/comments
• update-issue -> PATCH /repos/{owner}/{repo}/issues/{issue_number}
• create-pull-request -> POST /repos/{owner}/{repo}/pulls
• merge-pull-request -> PUT /repos/{owner}/{repo}/pulls/{pull_number}/merge
• create-or-update-file-contents -> PUT /repos/{owner}/{repo}/contents/{path}

Why these actions

These routes fit Harbor's Action Model well because they:

• stay under one fixed GitHub API origin
• use fixed paths relative to the Harbor Port
• work for the authenticated user without arbitrary path interpolation
• allow explicit repo-scoped routing only through named placeholders such as {owner}, {repo}, {issue_number}, {pull_number}, {branch}, {ref}, {basehead}, and {path}
• can be reviewed as named capabilities
• keep hidden auth entirely local to Harbor Node

Repo-scoped inputs

For repo-scoped actions like create-issue, get-repository-content, or merge-pull-request, Harbor stores the route as a fixed path with typed input.path values:

• POST /repos/{owner}/{repo}/issues

At execution time, the caller supplies those values through input.path, for example:

{
  "path": {
    "owner": "BreakwaterNinja",
    "repo": "harbor"
  },
  "title": "Document Harbor path templates",
  "body": "Add more examples for repo-scoped actions."
}

Harbor fills the placeholders safely, validates the typed location inputs, and sends the remaining JSON payload to GitHub.

For file writes, Harbor can safely model GitHub's single-file contents endpoint:

• PUT /repos/{owner}/{repo}/contents/{path}

That covers bounded file create/update flows, but it is not a replacement for full git transport or arbitrary push behavior.

Suggested operator workflow

1. Import the GitHub Dock entry from Dock / Hub.
2. Configure a local GitHub bearer token in Harbor Node.
3. Use the imported live action set immediately for low-risk reads after local auth is configured.
4. Keep create-repository, create-issue, create-issue-comment, update-issue, create-pull-request, merge-pull-request, and create-or-update-file-contents on require_approval unless there is a deliberate local policy reason not to.
5. Create new drafts only when you want to extend the imported GitHub surface beyond the Dock starter set.

Suggested agent workflow

1. Inspect the existing GitHub Harbor Port.
2. Inspect live actions and drafts.
3. Propose additional fixed-path actions only.
4. Validate and test drafts.
5. Request publish instead of self-publishing unless Harbor explicitly allows it.

Agents should never:

• ask Harbor for the stored token
• edit hidden GitHub auth
• widen GitHub into a generic arbitrary proxy
• invent undeclared repo-scoped path inputs outside the stored template

Current update strategy

For now, GitHub updates are manual:

• update the Dock / Hub GitHub integration document in apps/hub/catalog/integrations/github/github-rest-api.json
• bump the manifest version when the action set changes materially
• re-import into Harbor or create new drafts from the updated Dock entry

Future options such as repo-scoped templates, richer workflow packs, or parameterized action families are intentionally deferred until Harbor has clearer bounded-path semantics.

Official reference starting points

• GitHub REST API root: https://docs.github.com/en/rest
• GitHub REST API authentication: https://docs.github.com/en/rest/authentication/authenticating-to-the-rest-api
• Get the authenticated user: https://docs.github.com/en/rest/users/users#get-the-authenticated-user
• List issues assigned to the authenticated user: https://docs.github.com/en/rest/issues/issues#list-user-account-issues-assigned-to-the-authenticated-user
• List repositories for the authenticated user: https://docs.github.com/en/rest/repos/repos#list-repositories-for-the-authenticated-user
• List notifications for the authenticated user: https://docs.github.com/en/rest/activity/notifications#list-notifications-for-the-authenticated-user
• List organizations for the authenticated user: https://docs.github.com/en/rest/orgs/orgs#list-organizations-for-the-authenticated-user
• Get a repository: https://docs.github.com/en/rest/repos/repos#get-a-repository
• List repository issues: https://docs.github.com/en/rest/issues/issues#list-repository-issues
• Get an issue: https://docs.github.com/en/rest/issues/issues#get-an-issue
• List issue comments: https://docs.github.com/en/rest/issues/comments#list-issue-comments
• Create a repository for the authenticated user: https://docs.github.com/en/rest/repos/repos#create-a-repository-for-the-authenticated-user
• Create an issue: https://docs.github.com/en/rest/issues/issues#create-an-issue
• Create an issue comment: https://docs.github.com/en/rest/issues/comments#create-an-issue-comment
• Update an issue: https://docs.github.com/en/rest/issues/issues#update-an-issue
• List pull requests: https://docs.github.com/en/rest/pulls/pulls#list-pull-requests
• Get a pull request: https://docs.github.com/en/rest/pulls/pulls#get-a-pull-request
• Create a pull request: https://docs.github.com/en/rest/pulls/pulls#create-a-pull-request
• Merge a pull request: https://docs.github.com/en/rest/pulls/pulls#merge-a-pull-request
• List branches: https://docs.github.com/en/rest/branches/branches#list-branches
• Get a branch: https://docs.github.com/en/rest/branches/branches#get-a-branch
• List commits: https://docs.github.com/en/rest/commits/commits#list-commits
• Get a commit: https://docs.github.com/en/rest/commits/commits#get-a-commit
• Compare two commits: https://docs.github.com/en/rest/commits/commits#compare-two-commits
• Get repository content: https://docs.github.com/en/rest/repos/contents#get-repository-content
• Create or update file contents: https://docs.github.com/en/rest/repos/contents#create-or-update-file-contents