Skip to content

AutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.

feat(blocks): add GitHub repository traffic block (views, clones, referrers, popular content) (#15188)

Nicholas Tindlef90049a17abc
diff --git a/autogpt_platform/backend/backend/blocks/github/traffic.py b/autogpt_platform/backend/backend/blocks/github/traffic.py
new file mode 100644
index 0000000000..e6e54bd8ed
--- /dev/null
+++ b/autogpt_platform/backend/backend/blocks/github/traffic.py
@@ -0,0 +1,299 @@
+import asyncio
+from typing import Any, Literal
+
+from typing_extensions import TypedDict
+
+from backend.blocks._base import (
+ Block,
+ BlockCategory,
+ BlockEffect,
+ BlockOutput,
+ BlockSchemaInput,
+ BlockSchemaOutput,
+)
+from backend.data.model import SchemaField
+from backend.util.exceptions import BlockExecutionError, BlockInputError
+from backend.util.request import HTTPClientError
+
+from ._api import GITHUB_API_URL, get_api
+from ._auth import (
+ TEST_CREDENTIALS,
+ TEST_CREDENTIALS_INPUT,
+ GithubCredentials,
+ GithubCredentialsField,
+ GithubCredentialsInput,
+)
+from ._utils import normalize_repo_path
+
+GITHUB_WEB_URL = "https://github.com"
+
+TrafficPeriod = Literal["day", "week"]
+
+# What GitHub's 403 says when the caller may not read traffic: no push access
+# ("Must have push access to repository"), or a fine-grained token without
+# Administration (read) ("Resource not accessible by personal access token").
+# Other 403s, such as rate limits or SSO enforcement, keep GitHub's own message.
+_NO_TRAFFIC_ACCESS_MESSAGES = ("must have push access", "resource not accessible")
+
+
+class TrafficCount(TypedDict):
+ timestamp: str
+ count: int
+ uniques: int
+
+
+class TrafficReferrer(TypedDict):
+ referrer: str
+ count: int
+ uniques: int
+
+
+class PopularContent(TypedDict):
+ path: str
+ title: str
+ url: str
+ count: int
+ uniques: int
+
+
+# Responses in the shapes the traffic endpoints return, for the self-test
+TEST_VIEWS_PAYLOAD = {
+ "count": 3270,
+ "uniques": 1416,
+ "views": [
+ {"timestamp": "2026-09-28T00:00:00Z", "count": 1810, "uniques": 840},
+ {"timestamp": "2026-09-29T00:00:00Z", "count": 1460, "uniques": 692},
+ ],
+}
+TEST_CLONES_PAYLOAD = {
+ "count": 412,
+ "uniques": 87,
+ "clones": [
+ {"timestamp": "2026-09-28T00:00:00Z", "count": 230, "uniques": 51},
+ {"timestamp": "2026-09-29T00:00:00Z", "count": 182, "uniques": 44},
+ ],
+}
+TEST_REFERRERS_PAYLOAD = [
+ {"referrer": "github.com", "count": 1203, "uniques": 655},
+ {"referrer": "Google", "count": 421, "uniques": 302},
+]
+TEST_POPULAR_PATHS_PAYLOAD = [
+ {"path": "/owner/repo", "title": "Overview", "count": 2010, "uniques": 1033},
+ {"path": "/owner/repo/issues", "title": "/issues", "count": 288, "uniques": 120},
+]
+
+
+class GithubGetRepositoryTrafficBlock(Block):
+ class Input(BlockSchemaInput):
+ credentials: GithubCredentialsInput = GithubCredentialsField("repo")
+ repo_url: str = SchemaField(
+ description="Repository URL or '{owner}/{repo}'",
+ placeholder="https://github.com/owner/repo",
+ )
+ period: TrafficPeriod = SchemaField(
+ description="Whether to break the views and clones down by day or by "
+ "week. Days and weeks start at midnight UTC, and weeks start on Monday.",
+ default="day",
+ )
+
+ class Output(BlockSchemaOutput):
+ views: int = SchemaField(description="Views in the last 14 days")
+ unique_visitors: int = SchemaField(
+ description="Unique visitors in the last 14 days. Someone who visited "
+ "on several days counts once."
+ )
+ views_by_period: list[TrafficCount] = SchemaField(
+ description="Views and unique visitors for each day or week, "
+ "oldest first"
+ )
+ clones: int = SchemaField(
+ description="Git clones in the last 14 days. Counts full clones, "
+ "not fetches."
+ )
+ unique_cloners: int = SchemaField(
+ description="Unique cloners in the last 14 days"
+ )
+ clones_by_period: list[TrafficCount] = SchemaField(
+ description="Clones and unique cloners for each day or week, "
+ "oldest first"
+ )
+ referrers: list[TrafficReferrer] = SchemaField(
+ description="Top 10 sites that sent visitors in the last 14 days, "
+ "with the views and unique visitors from each"
+ )
+ popular_content: list[PopularContent] = SchemaField(
+ description="Top 10 most viewed pages of the repository in the last "
+ "14 days, with the views, unique visitors and github.com link of each"
+ )
+
+ def __init__(self):
+ super().__init__(
+ id="aa46e092-b04f-492a-ae13-bb920f1469c2",
+ description="Get a GitHub repository's views and clones over the last "
+ "14 days, with unique visitors and cloners, plus its top referring "
+ "sites and most viewed pages. Views and clones are also broken down "
+ "by day or week. GitHub only shows traffic to accounts with push "
+ "access to the repository.",
+ categories={BlockCategory.DEVELOPER_TOOLS, BlockCategory.MARKETING},
+ input_schema=GithubGetRepositoryTrafficBlock.Input,
+ output_schema=GithubGetRepositoryTrafficBlock.Output,
+ test_input={
+ "repo_url": "https://github.com/owner/repo",
+ "credentials": TEST_CREDENTIALS_INPUT,
+ },
+ test_credentials=TEST_CREDENTIALS,
+ test_output=[
+ ("views", 3270),
+ ("unique_visitors", 1416),
+ ("views_by_period", TEST_VIEWS_PAYLOAD["views"]),
+ ("clones", 412),
+ ("unique_cloners", 87),
+ ("clones_by_period", TEST_CLONES_PAYLOAD["clones"]),
+ ("referrers", TEST_REFERRERS_PAYLOAD),
+ (
+ "popular_content",
+ [
+ {
+ **TEST_POPULAR_PATHS_PAYLOAD[0],
+ "url": "https://github.com/owner/repo",
+ },
+ {
+ **TEST_POPULAR_PATHS_PAYLOAD[1],
+ "url": "https://github.com/owner/repo/issues",
+ },
+ ],
+ ),
+ ],
+ test_mock={
+ "get_views": lambda *args, **kwargs: TEST_VIEWS_PAYLOAD,
+ "get_clones": lambda *args, **kwargs: TEST_CLONES_PAYLOAD,
+ "get_referrers": lambda *args, **kwargs: TEST_REFERRERS_PAYLOAD,
+ "get_popular_content": lambda *args, **kwargs: (
+ TEST_POPULAR_PATHS_PAYLOAD
+ ),
+ },
+ effect=BlockEffect.READ,
+ )
+
+ @staticmethod
+ async def get_views(
+ credentials: GithubCredentials, repo: str, period: TrafficPeriod
+ ) -> dict:
+ return await _get_traffic(credentials, repo, "views", {"per": period})
+
+ @staticmethod
+ async def get_clones(
+ credentials: GithubCredentials, repo: str, period: TrafficPeriod
+ ) -> dict:
+ return await _get_traffic(credentials, repo, "clones", {"per": period})
+
+ @staticmethod
+ async def get_referrers(credentials: GithubCredentials, repo: str) -> list[dict]:
+ return await _get_traffic(credentials, repo, "popular/referrers")
+
+ @staticmethod
+ async def get_popular_content(
+ credentials: GithubCredentials, repo: str
+ ) -> list[dict]:
+ return await _get_traffic(credentials, repo, "popular/paths")
+
+ async def run(
+ self,
+ input_data: Input,
+ *,
+ credentials: GithubCredentials,
+ **kwargs,
+ ) -> BlockOutput:
+ try:
+ repo = normalize_repo_path(input_data.repo_url)
+ except ValueError as e:
+ raise BlockInputError(
+ message=str(e), block_name=self.name, block_id=self.id
+ ) from e
+
+ try:
+ views, clones, referrers, paths = await asyncio.gather(
+ self.get_views(credentials, repo, input_data.period),
+ self.get_clones(credentials, repo, input_data.period),
+ self.get_referrers(credentials, repo),
+ self.get_popular_content(credentials, repo),
+ )
+ except HTTPClientError as e:
+ if message := _traffic_error_message(e, repo):
+ raise BlockExecutionError(
+ message=message, block_name=self.name, block_id=self.id
+ ) from e
+ raise
+
+ yield "views", views.get("count") or 0
+ yield "unique_visitors", views.get("uniques") or 0
+ yield "views_by_period", [
+ _to_traffic_count(item) for item in views.get("views") or []
+ ]
+ yield "clones", clones.get("count") or 0
+ yield "unique_cloners", clones.get("uniques") or 0
+ yield "clones_by_period", [
+ _to_traffic_count(item) for item in clones.get("clones") or []
+ ]
+ yield "referrers", [_to_referrer(item) for item in referrers or []]
+ yield "popular_content", [_to_popular_content(item) for item in paths or []]
+
+
+async def _get_traffic(
+ credentials: GithubCredentials,
+ repo: str,
+ endpoint: str,
+ params: dict[str, str] | None = None,
+) -> Any:
+ api = get_api(credentials, convert_urls=False)
+ response = await api.get(
+ f"{GITHUB_API_URL}/repos/{repo}/traffic/{endpoint}", params=params
+ )
+ return response.json()
+
+
+def _traffic_error_message(error: HTTPClientError, repo: str) -> str | None:
+ """A message for the errors the user can fix, or None to keep GitHub's own."""
+ detail = str(error).lower()
+ if error.status_code == 403 and any(
+ message in detail for message in _NO_TRAFFIC_ACCESS_MESSAGES
+ ):
+ return (
+ f"GitHub only shows traffic to people with push access to {repo}. "
+ "Connect a GitHub account that can push to it; a fine-grained token "
+ "also needs the Administration (read) permission."
+ )
+ if error.status_code == 404:
+ return (
+ f"GitHub can't find {repo}, or the connected GitHub account can't see "
+ "it. Check the repository name, and that the account or token has "
+ "access to the repository."
+ )
+ return None
+
+
+def _to_traffic_count(item: dict) -> TrafficCount:
+ return {
+ "timestamp": item.get("timestamp") or "",
+ "count": item.get("count") or 0,
+ "uniques": item.get("uniques") or 0,
+ }
+
+
+def _to_referrer(item: dict) -> TrafficReferrer:
+ return {
+ "referrer": item.get("referrer") or "",
+ "count": item.get("count") or 0,
+ "uniques": item.get("uniques") or 0,
+ }
+
+
+def _to_popular_content(item: dict) -> PopularContent:
+ path = item.get("path") or ""
+ return {
+ "path": path,
+ "title": item.get("title") or "",
+ "url": f"{GITHUB_WEB_URL}/{path.lstrip('/')}" if path else "",
+ "count": item.get("count") or 0,
+ "uniques": item.get("uniques") or 0,
+ }
diff --git a/autogpt_platform/backend/backend/blocks/github/traffic_effects_test.py b/autogpt_platform/backend/backend/blocks/github/traffic_effects_test.py
new file mode 100644
index 0000000000..b91e89bca5
--- /dev/null
+++ b/autogpt_platform/backend/backend/blocks/github/traffic_effects_test.py
@@ -0,0 +1,16 @@
+import pytest
+
+from backend.blocks._base import Block, BlockEffect
+from backend.blocks.github.traffic import GithubGetRepositoryTrafficBlock
+
+
+ ("block", "effect"),
+ [
+ (GithubGetRepositoryTrafficBlock, BlockEffect.READ),
+ ],
+)
+def test_block_declares_what_it_does(block: type[Block], effect: BlockEffect):
+ # AutoPilot runs reads without asking, asks before anything that changes
+ # GitHub, and treats an undeclared block as the latter.
+ assert block().effect is effect
diff --git a/autogpt_platform/backend/backend/blocks/github/traffic_test.py b/autogpt_platform/backend/backend/blocks/github/traffic_test.py
new file mode 100644
index 0000000000..e41a8906e9
--- /dev/null
+++ b/autogpt_platform/backend/backend/blocks/github/traffic_test.py
@@ -0,0 +1,343 @@
+import asyncio
+from http import HTTPStatus
+from typing import Any
+from unittest import mock
+
+import pytest
+
+from backend.blocks.github import traffic
+from backend.blocks.github._auth import TEST_CREDENTIALS, TEST_CREDENTIALS_INPUT
+from backend.blocks.github.traffic import (
+ TEST_CLONES_PAYLOAD,
+ TEST_POPULAR_PATHS_PAYLOAD,
+ TEST_REFERRERS_PAYLOAD,
+ TEST_VIEWS_PAYLOAD,
+ GithubGetRepositoryTrafficBlock,
+)
+from backend.data.execution import ExecutionContext
+from backend.util.exceptions import (
+ BlockExecutionError,
+ BlockInputError,
+ BlockUnknownError,
+)
+from backend.util.request import HTTPClientError, http_status_error
+
+TRAFFIC_URL = "https://api.github.com/repos/owner/repo/traffic"
+VIEWS_URL = f"{TRAFFIC_URL}/views"
+CLONES_URL = f"{TRAFFIC_URL}/clones"
+REFERRERS_URL = f"{TRAFFIC_URL}/popular/referrers"
+PATHS_URL = f"{TRAFFIC_URL}/popular/paths"
+
+NO_PUSH_ACCESS_MESSAGE = (
+ "GitHub only shows traffic to people with push access to owner/repo. "
+ "Connect a GitHub account that can push to it; a fine-grained token also "
+ "needs the Administration (read) permission."
+)
+
+
+def _github_error(status: int, message: str) -> HTTPClientError:
+ """The error `Requests` raises for a GitHub error response."""
+ body = (
+ f'{{"message":"{message}","documentation_url":'
+ f'"https://docs.github.com/rest/metrics/traffic#get-page-views",'
+ f'"status":"{status}"}}'
+ )
+ error = http_status_error(status, HTTPStatus(status).phrase, body.encode())
+ assert isinstance(error, HTTPClientError)
+ return error
+
+
+class _FakeApi:
+ """Serves canned responses by URL and records every request."""
+
+ def __init__(
+ self,
+ views: Any = TEST_VIEWS_PAYLOAD,
+ clones: Any = TEST_CLONES_PAYLOAD,
+ referrers: Any = TEST_REFERRERS_PAYLOAD,
+ paths: Any = TEST_POPULAR_PATHS_PAYLOAD,
+ error: Exception | None = None,
+ ):
+ self.responses = {
+ VIEWS_URL: views,
+ CLONES_URL: clones,
+ REFERRERS_URL: referrers,
+ PATHS_URL: paths,
+ }
+ self.error = error
+ self.calls: dict[str, dict] = {}
+
+ async def get(self, url: str, **kwargs):
+ self.calls[url] = kwargs
+ if self.error:
+ raise self.error
+ payload = self.responses[url]
+ return mock.Mock(json=lambda: payload)
+
+
+async def _run(api: _FakeApi, **inputs) -> dict[str, Any]:
+ """Run the block end to end with only the HTTP layer faked."""
+ with mock.patch.object(traffic, "get_api", return_value=api):
+ return await _execute(**inputs)
+
+
+async def _execute(**inputs) -> dict[str, Any]:
+ block = GithubGetRepositoryTrafficBlock()
+ input_data = {
+ "credentials": TEST_CREDENTIALS_INPUT,
+ "repo_url": "owner/repo",
+ **inputs,
+ }
+ return {
+ name: value
+ async for name, value in block.execute(
+ input_data,
+ credentials=TEST_CREDENTIALS,
+ execution_context=ExecutionContext(),
+ )
+ }
+
+
+# ── Requests ──
+
+
+class TestRequests:
+ async def test_reads_all_four_traffic_endpoints(self):
+ api = _FakeApi()
+ await _run(api)
+ assert set(api.calls) == {VIEWS_URL, CLONES_URL, REFERRERS_URL, PATHS_URL}
+
+ async def test_views_and_clones_are_daily_by_default(self):
+ api = _FakeApi()
+ await _run(api)
+ assert api.calls[VIEWS_URL]["params"] == {"per": "day"}
+ assert api.calls[CLONES_URL]["params"] == {"per": "day"}
+
+ async def test_weekly_period_is_sent_as_per_week(self):
+ api = _FakeApi()
+ await _run(api, period="week")
+ assert api.calls[VIEWS_URL]["params"] == {"per": "week"}
+ assert api.calls[CLONES_URL]["params"] == {"per": "week"}
+
+ async def test_referrers_and_paths_take_no_period(self):
+ api = _FakeApi()
+ await _run(api, period="week")
+ assert api.calls[REFERRERS_URL]["params"] is None
+ assert api.calls[PATHS_URL]["params"] is None
+
+ async def test_urls_are_sent_as_built(self):
+ # convert_urls would rewrite an api.github.com URL as if it were a
+ # github.com one, turning /repos/owner/repo into /repos/repos/owner.
+ with mock.patch.object(traffic, "get_api", return_value=_FakeApi()) as get_api:
+ await _execute()
+ assert (
+ get_api.call_args_list
+ == [mock.call(TEST_CREDENTIALS, convert_urls=False)] * 4
+ )
+
+ async def test_the_four_requests_are_in_flight_together(self):
+ everyone_asked = asyncio.Event()
+
+ class WaitForAllApi(_FakeApi):
+ async def get(self, url: str, **kwargs):
+ self.calls[url] = kwargs
+ if len(self.calls) == 4:
+ everyone_asked.set()
+ # Requests made one at a time would never get here.
+ await asyncio.wait_for(everyone_asked.wait(), timeout=5)
+ return await super().get(url, **kwargs)
+
+ outputs = await _run(WaitForAllApi())
+ assert outputs["views"] == TEST_VIEWS_PAYLOAD["count"]
+
+
+# ── Repository input ──
+
+
+class TestRepositoryInput:
+ @pytest.mark.parametrize(
+ "repo_url",
+ [
+ "owner/repo",
+ "https://github.com/owner/repo",
+ "https://github.com/owner/repo/",
+ "http://www.github.com/owner/repo",
+ "github.com/owner/repo.git",
+ " https://github.com/owner/repo ",
+ ],
+ )
+ async def test_urls_and_owner_repo_name_the_same_repository(self, repo_url):
+ api = _FakeApi()
+ await _run(api, repo_url=repo_url)
+ assert all(url.startswith(f"{TRAFFIC_URL}/") for url in api.calls)
+
+ @pytest.mark.parametrize(
+ "repo_url",
+ [
+ "",
+ "owner",
+ "owner/repo/issues",
+ "owner/../../user",
+ "https://github.com/owner/repo/tree/main",
+ "https://gitlab.com/owner/repo",
+ ],
+ )
+ async def test_invalid_repository_is_rejected_before_any_request(self, repo_url):
+ api = _FakeApi()
+ with pytest.raises(BlockInputError, match="repository"):
+ await _run(api, repo_url=repo_url)
+ assert api.calls == {}
+
+ async def test_unknown_period_is_rejected(self):
+ api = _FakeApi()
+ with pytest.raises(BlockInputError):
+ await _run(api, period="month")
+ assert api.calls == {}
+
+
+# ── Parsing ──
+
+
+class TestParsing:
+ async def test_maps_github_responses_to_outputs(self):
+ assert await _run(_FakeApi()) == {
+ "views": 3270,
+ "unique_visitors": 1416,
+ "views_by_period": [
+ {"timestamp": "2026-09-28T00:00:00Z", "count": 1810, "uniques": 840},
+ {"timestamp": "2026-09-29T00:00:00Z", "count": 1460, "uniques": 692},
+ ],
+ "clones": 412,
+ "unique_cloners": 87,
+ "clones_by_period": [
+ {"timestamp": "2026-09-28T00:00:00Z", "count": 230, "uniques": 51},
+ {"timestamp": "2026-09-29T00:00:00Z", "count": 182, "uniques": 44},
+ ],
+ "referrers": [
+ {"referrer": "github.com", "count": 1203, "uniques": 655},
+ {"referrer": "Google", "count": 421, "uniques": 302},
+ ],
+ "popular_content": [
+ {
+ "path": "/owner/repo",
+ "title": "Overview",
+ "url": "https://github.com/owner/repo",
+ "count": 2010,
+ "uniques": 1033,
+ },
+ {
+ "path": "/owner/repo/issues",
+ "title": "/issues",
+ "url": "https://github.com/owner/repo/issues",
+ "count": 288,
+ "uniques": 120,
+ },
+ ],
+ }
+
+ async def test_repository_without_traffic(self):
+ outputs = await _run(
+ _FakeApi(
+ views={"count": 0, "uniques": 0, "views": []},
+ clones={"count": 0, "uniques": 0, "clones": []},
+ referrers=[],
+ paths=[],
+ )
+ )
+ assert outputs == {
+ "views": 0,
+ "unique_visitors": 0,
+ "views_by_period": [],
+ "clones": 0,
+ "unique_cloners": 0,
+ "clones_by_period": [],
+ "referrers": [],
+ "popular_content": [],
+ }
+
+ async def test_missing_and_null_fields_degrade_to_zero_and_empty(self):
+ outputs = await _run(
+ _FakeApi(
+ views={},
+ clones={
+ "count": None,
+ "clones": [{"timestamp": "2026-09-28T00:00:00Z"}],
+ },
+ referrers=[{"referrer": "Google"}],
+ paths=[{"count": 3, "title": None}],
+ )
+ )
+ assert outputs["views"] == 0
+ assert outputs["unique_visitors"] == 0
+ assert outputs["views_by_period"] == []
+ assert outputs["clones"] == 0
+ assert outputs["clones_by_period"] == [
+ {"timestamp": "2026-09-28T00:00:00Z", "count": 0, "uniques": 0}
+ ]
+ assert outputs["referrers"] == [
+ {"referrer": "Google", "count": 0, "uniques": 0}
+ ]
+ assert outputs["popular_content"] == [
+ {"path": "", "title": "", "url": "", "count": 3, "uniques": 0}
+ ]
+
+ @pytest.mark.parametrize(
+ ("path", "url"),
+ [
+ (
+ "/owner/repo/blob/main/README.md",
+ "https://github.com/owner/repo/blob/main/README.md",
+ ),
+ ("owner/repo/wiki", "https://github.com/owner/repo/wiki"),
+ ],
+ )
+ async def test_popular_content_links_to_the_page(self, path, url):
+ outputs = await _run(_FakeApi(paths=[{"path": path, "count": 1, "uniques": 1}]))
+ assert outputs["popular_content"][0]["url"] == url
+
+
+# ── Errors ──
+
+
+class TestErrors:
+ @pytest.mark.parametrize(
+ "message",
+ [
+ # What GitHub sends a token without push access (checked live)
+ "Must have push access to repository",
+ # A fine-grained token without the Administration (read) permission
+ "Resource not accessible by personal access token",
+ ],
+ )
+ async def test_no_access_to_traffic_explains_what_is_needed(self, message):
+ error = _github_error(403, message)
+ with pytest.raises(BlockExecutionError) as caught:
+ await _run(_FakeApi(error=error))
+ assert str(caught.value) == NO_PUSH_ACCESS_MESSAGE
+ assert caught.value.__cause__ is error
+
+ async def test_repository_not_found(self):
+ error = _github_error(404, "Not Found")
+ with pytest.raises(BlockExecutionError) as caught:
+ await _run(_FakeApi(error=error))
+ assert str(caught.value) == (
+ "GitHub can't find owner/repo, or the connected GitHub account can't "
+ "see it. Check the repository name, and that the account or token has "
+ "access to the repository."
+ )
+ assert caught.value.__cause__ is error
+
+ async def test_rate_limit_keeps_githubs_message(self):
+ # A rate-limited 403 is not about access, so it must not say it is.
+ error = _github_error(403, "API rate limit exceeded for user ID 1.")
+ with pytest.raises(BlockUnknownError, match="API rate limit exceeded"):
+ await _run(_FakeApi(error=error))
+
+ async def test_rejected_credentials_keep_their_status(self):
+ # AutoPilot asks the user to reconnect when it finds a 401 on the
+ # error's cause chain, so a 401 must reach it unchanged.
+ error = _github_error(401, "Bad credentials")
+ with pytest.raises(BlockUnknownError) as caught:
+ await _run(_FakeApi(error=error))
+ assert caught.value.__cause__ is error
+ assert error.status_code == 401
diff --git a/docs/integrations/README.md b/docs/integrations/README.md
index 45787cde18..7c4df3e4ed 100644
--- a/docs/integrations/README.md
+++ b/docs/integrations/README.md
@@ -570,6 +570,7 @@ Below is a comprehensive list of all available blocks, categorized by their prim
| [Github Get Notification Thread](block-integrations/github/notifications.md#github-get-notification-thread) | This block fetches a single GitHub notification thread |
| [Github Get PR Review Comments](block-integrations/github/reviews.md#github-get-pr-review-comments) | This block gets all review comments from a GitHub pull request or from a specific review |
| [Github Get Repository Info](block-integrations/github/repo.md#github-get-repository-info) | This block retrieves metadata about a GitHub repository |
+| [Github Get Repository Traffic](block-integrations/github/traffic.md#github-get-repository-traffic) | Get a GitHub repository's views and clones over the last 14 days, with unique visitors and cloners, plus its top referring sites and most viewed pages |
| [Github Get Repository Tree](block-integrations/github/repo_files.md#github-get-repository-tree) | This block lists the entire file tree of a GitHub repository recursively |
| [Github Get User Info](block-integrations/github/users.md#github-get-user-info) | This block fetches information about a GitHub user, or about the authenticated user (yourself) if no username is given |
| [Github Issues Trigger](block-integrations/github/triggers.md#github-issues-trigger) | This block triggers on GitHub issues events |
diff --git a/docs/integrations/SUMMARY.md b/docs/integrations/SUMMARY.md
index 2b8a48c4ce..febb81c0fa 100644
--- a/docs/integrations/SUMMARY.md
+++ b/docs/integrations/SUMMARY.md
@@ -101,6 +101,7 @@
* [GitHub Repo Files](block-integrations/github/repo_files.md)
* [GitHub Reviews](block-integrations/github/reviews.md)
* [GitHub Statuses](block-integrations/github/statuses.md)
+* [GitHub Traffic](block-integrations/github/traffic.md)
* [GitHub Triggers](block-integrations/github/triggers.md)
* [GitHub Users](block-integrations/github/users.md)
* [Google Calendar](block-integrations/google/calendar.md)
diff --git a/docs/integrations/block-integrations/github/traffic.md b/docs/integrations/block-integrations/github/traffic.md
new file mode 100644
index 0000000000..fa84a2b017
--- /dev/null
+++ b/docs/integrations/block-integrations/github/traffic.md
@@ -0,0 +1,48 @@
+# GitHub Traffic
+<!-- MANUAL: file_description -->
+A block for reading a repository's traffic: the views, git clones, referring sites and popular content on its **Insights > Traffic** page. GitHub only shows traffic to people with push (write) access to the repository. The GitHub connection or a classic personal access token needs the `repo` scope, and a fine-grained token needs the **Administration** repository permission set to read.
+<!-- END MANUAL -->
+
+## Github Get Repository Traffic
+
+### What it is
+Get a GitHub repository's views and clones over the last 14 days, with unique visitors and cloners, plus its top referring sites and most viewed pages. Views and clones are also broken down by day or week. GitHub only shows traffic to accounts with push access to the repository.
+
+### How it works
+<!-- MANUAL: how_it_works -->
+Calls GitHub's four traffic endpoints at the same time: `traffic/views` and `traffic/clones` (with `per` set to `day` or `week`), `traffic/popular/referrers` and `traffic/popular/paths`. `repo_url` can be a github.com link or `owner/repo`. Anything else is rejected before a request is made. If the connected account can't push to the repository, or a fine-grained token lacks the Administration (read) permission, GitHub refuses and the block says which access is missing. A repository that doesn't exist, or that the account can't see, fails as not found. Other errors, such as rate limits, keep GitHub's own message.
+
+GitHub keeps only the last 14 days. Days and weeks start at midnight UTC, and weeks start on Monday. Views and clones refresh every hour; referring sites and popular content refresh once a day. Clones are full git clones, not fetches. Unique counts don't add up across days: someone who visited on three days counts once in `unique_visitors` but once on each of those days in `views_by_period`. `referrers` and `popular_content` are GitHub's top 10 for the 14 days, and each page comes with its github.com link. GitHub lists each path as it was visited, so the same page can appear twice with different capitalisation.
+<!-- END MANUAL -->
+
+### Inputs
+
+| Input | Description | Type | Required |
+|-------|-------------|------|----------|
+| repo_url | Repository URL or '{owner}/{repo}' | str | Yes |
+| period | Whether to break the views and clones down by day or by week. Days and weeks start at midnight UTC, and weeks start on Monday. | "day" \| "week" | No |
+
+### Outputs
+
+| Output | Description | Type |
+|--------|-------------|------|
+| error | Error message if the operation failed | str |
+| views | Views in the last 14 days | int |
+| unique_visitors | Unique visitors in the last 14 days. Someone who visited on several days counts once. | int |
+| views_by_period | Views and unique visitors for each day or week, oldest first | List[TrafficCount] |
+| clones | Git clones in the last 14 days. Counts full clones, not fetches. | int |
+| unique_cloners | Unique cloners in the last 14 days | int |
+| clones_by_period | Clones and unique cloners for each day or week, oldest first | List[TrafficCount] |
+| referrers | Top 10 sites that sent visitors in the last 14 days, with the views and unique visitors from each | List[TrafficReferrer] |
+| popular_content | Top 10 most viewed pages of the repository in the last 14 days, with the views, unique visitors and github.com link of each | List[PopularContent] |
+
+### Possible use case
+<!-- MANUAL: use_case -->
+**Traffic History**: Run the block on a daily schedule and append yesterday's views and clones to a Google Sheet, so you keep more than the 14 days GitHub holds.
+
+**Weekly Report**: Every Monday, post last week's views, unique visitors, clones and top referrers to Slack.
+
+**Launch Check**: After a release or a blog post, see whether views and clones went up and which sites sent the visitors.
+<!-- END MANUAL -->
+
+---